Last updated 2026-05-07

Capturing a Video Demo

Use the built-in video-capture action to attach a walkthrough to your feature. The dashboard automatically discovers and plays the video on the feature page.

1. Pick a scenario file

A scenario is a YAML script of UI steps. Drop it under scenarios/ in your repo. For example, scenarios/onboarding.yml:

name: "Onboarding"
description: "First-run experience"
steps:
  - action: pause
    duration: 1500
    screenshot: launch-screen
  - action: click
    selector: "[data-testid='get-started']"
    wait: 1000
    screenshot: account-form
  - action: type
    selector: "input[name='email']"
    text: "demo@example.com"
  - action: click
    selector: "button[type='submit']"
    wait: 2500
    screenshot: dashboard

2. Add the workflow

name: Feature Video
on:
  workflow_dispatch:
    inputs:
      feature:
        description: Feature slug
        required: true

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'npm' }
      - run: npm ci
      - run: npm run build
      - run: npm start &
      - run: npx wait-on http://localhost:3000

      - id: capture
        uses: ./platform/actions/video-capture
        with:
          platform: web
          app-url:  http://localhost:3000
          scenario: ./scenarios/onboarding.yml
          output-dir: ./.stax/features/${{ inputs.feature }}/video-capture
          video-quality: high

      - uses: actions/upload-artifact@v4
        with:
          name: demo-${{ inputs.feature }}
          path: ./.stax/features/${{ inputs.feature }}/video-capture

3. Run it

stax run feature-video -i feature=onboarding

The action records the walkthrough, generates a thumbnail, captures the named screenshots, and writes everything under the output-dir. The runner streams Playwright's logs over SSE so you see the run live in the dashboard.

4. View it on the dashboard

Open the feature page (/features/onboarding). The dashboard auto-mounts the video via /api/features/onboarding/video and renders the screenshots strip from /api/features/onboarding/screenshots/....

5. Tweak quality vs. file size

6. Mobile capture

# Android
- uses: ./platform/actions/video-capture
  with:
    platform: android
    device:   "Pixel 7"
    scenario: ./scenarios/android.yml

# iOS
- uses: ./platform/actions/video-capture
  with:
    platform: ios
    device:   "iPhone 15"
    scenario: ./scenarios/ios.yml

iOS capture requires Xcode + simulators on the host running the runner; Android capture requires the Android emulator (the runner uses actions/setup-java's shim and android-actions/setup-android when present).