/ia-feature-video

name: ia-feature-video
description: Record a video walkthrough of a feature and add it to the PR description
argument-hint: "[PR number or 'current'] [optional: base URL, default localhost:3000]"

Feature Video Walkthrough

<command_purpose>Record a video walkthrough demonstrating a feature, upload it, and add it to the PR description.</command_purpose>

Introduction

<role>Developer Relations Engineer creating feature demo videos</role>

This command creates professional video walkthroughs of features for PR documentation:

• Records browser interactions using agent-browser CLI
• Demonstrates the complete user flow
• Uploads the video for easy sharing
• Updates the PR description with an embedded video

Prerequisites

<requirements>

• Local development server running (e.g., `npm run dev`, `php artisan serve`)
• agent-browser CLI installed
• Git repository with a PR to document
• `ffmpeg` installed (for video conversion)
• `rclone` configured (optional, for cloud upload - see rclone documentation)
• Public R2 base URL known (for example, `https://<public-domain>.r2.dev`)

</requirements>

Setup

For agent-browser install/verify steps and the full command reference, see [references/agent-browser-cli.md](references/agent-browser-cli.md).

Main Tasks

1. Parse Arguments

<parse_args>

**Arguments:** $ARGUMENTS

Parse the input:

• First argument: PR number or "current" (defaults to current branch's PR)
• Second argument: Base URL (defaults to `http://localhost:3000`)

# Get PR number for current branch if needed
gh pr view --json number -q '.number'

</parse_args>

2. Gather Feature Context

<gather_context>

**Get PR details:**

gh pr view [number] --json title,body,files,headRefName -q '.'

**Get changed files:**

gh pr view [number] --json files -q '.files[].path'

**Map files to testable routes** (same mapping used by `/ia-test-browser` — see [references/agent-browser-cli.md](references/agent-browser-cli.md) for the full file-to-route table).

</gather_context>

3. Plan the Video Flow

<plan_flow>

Before recording, create a shot list:

1. **Opening shot**: Homepage or starting point (2-3 seconds) 2. **Navigation**: How user gets to the feature 3. **Feature demonstration**: Core functionality (main focus) 4. **Edge cases**: Error states, validation, etc. (if applicable) 5. **Success state**: Completed action/result

Ask user to confirm or adjust the flow:

**Proposed Video Flow**

Based on PR #[number]: [title]

1. Start at: /[starting-route]
2. Navigate to: /[feature-route]
3. Demonstrate:
   - [Action 1]
   - [Action 2]
   - [Action 3]
4. Show result: [success state]

Estimated duration: ~[X] seconds

Does this look right?
1. Yes, start recording
2. Modify the flow (describe changes)
3. Add specific interactions to demonstrate

</plan_flow>

4. Setup Video Recording

<setup_recording>

**Create videos directory:**

mkdir -p tmp/videos

**Recording approach: Use browser screenshots as frames**

agent-browser captures screenshots at key moments, then combine into video using ffmpeg:

ffmpeg -framerate 2 -pattern_type glob -i 'tmp/screenshots/*.png' -vf "scale=1280:-1" tmp/videos/feature-demo.gif

</setup_recording>

5. Record the Walkthrough

<record_walkthrough>

Execute the planned flow, capturing each step:

**Step 1: Navigate to starting point**

agent-browser open "[base-url]/[start-route]"
agent-browser wait 2000
agent-browser screenshot tmp/screenshots/01-start.png

**Step 2: Perform navigation/interactions**

agent-browser snapshot -i  # Get refs
agent-browser click @e1    # Click navigation element
agent-browser wait 1000
agent-browser screenshot tmp/screenshots/02-navigate.png

**Step 3: Demonstrate feature**

agent-browser snapshot -i  # Get refs for feature elements
agent-browser click @e2    # Click feature element
agent-browser wait 1000
agent-browser screenshot tmp/screenshots/03-feature.png

**Step 4: Capture result**

agent-browser wait 2000
agent-browser screenshot tmp/screenshots/04-result.png

**Create video/GIF from screenshots:**

# Create directories
mkdir -p tmp/videos tmp/screenshots

# Create MP4 video (RECOMMENDED - better quality, smaller size)
# -framerate 0.5 = 2 seconds per frame (slower playback)
# -framerate 1 = 1 second per frame
ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
  tmp/videos/feature-demo.mp4

# Create low-quality GIF for preview (small file, for GitHub embed)
ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
  -vf "scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse" \
  -loop 0 tmp/videos/feature-demo-preview.gif

**Note:**

• The `-2` in MP4 scale ensures height is divisible by 2 (required for H.264)
• Preview GIF uses 640px width and 128 colors to keep file size small (~100-200KB)

</record_walkthrough>

6. Upload the Video

<upload_video>

**Upload with rclone (skip if rclone is not configured):**

# Check rclone is configured -- abort upload step if not
rclone listremotes || { echo "rclone not configured, skipping upload"; exit 0; }

# Config: set these to your rclone remote, bucket, and public base URL
R2_REMOTE="${R2_REMOTE:-r2}"              # rclone remote name
R2_BUCKET="${R2_BUCKET:-my-bucket}"       # bucket name
PUBLIC_BASE_URL="${PUBLIC_BASE_URL:-https://your-domain.r2.dev}"  # NO trailing slash

UPLOAD_PATH="$R2_REMOTE:$R2_BUCKET/pr-videos/pr-[number]"

# Upload video, preview GIF, and screenshots
rclone copy tmp/videos/ "$UPLOAD_PATH/" --s3-no-check-bucket --progress
rclone copy tmp/screenshots/ "$UPLOAD_PATH/screenshots/" --s3-no-check-bucket --progress

# List uploaded files
rclone ls "$UPLOAD_PATH/"

# Build and validate public URLs BEFORE updating PR
VIDEO_URL="$PUBLIC_BASE_URL/pr-videos/pr-[number]/feat