abdallahfalou/ux-review

UX Review

Process a screen recording into a structured review: timestamped transcript, correlated screen frames, and AI-synthesized feedback.

Workflow

Step 1: Understand what the user recorded

Ask (or infer from context) what kind of recording this is, so you can pick the right extraction parameters:

| Scenario | Recommended flags | Why | |----------|------------------|-----| | Narrated walkthrough — mostly static screens, pointing and talking | --frames-per-segment (default) | Speech-driven, one frame per thought | | Live demo — clicking through flows, screens change frequently | --frames-per-segment --scene-detect 0.3 | Catches screen transitions between spoken segments | | Debug session — terminal/IDE, subtle text changes | --interval 2 --no-frames-per-segment | High-frequency capture for small text changes | | Design review — animations, transitions, visual details | --frames-per-segment --scene-detect 0.1 | Low threshold catches subtle visual shifts | | Exhaustive — long session, unsure what matters | --frames-per-segment --scene-detect 0.2 --interval 5 | Capture everything, analyze after |

If the user provides a focus area or describes the content, select parameters accordingly. If unclear, ask briefly or default to --frames-per-segment --scene-detect 0.3 which works well for most cases.

Step 2: Run the extraction script

ux-review <video-path> [flags from above]

The script is at bin/ux-review in this repo. If not on PATH, use the full path.

Script parameters (all optional, all combinable):

| Flag | What it does | |------|-------------| | --frames-per-segment | One frame at midpoint of each transcript segment (default: on) | | --no-frames-per-segment | Disable per-segment frames | | --scene-detect <0.0-1.0> | Extract frames at visual scene changes. Lower = more sensitive | | --interval <seconds> | Extract frames at fixed time interval | | --segment-duration <seconds> | Re-chunk transcript into ~N second segments using word-level timestamps | | --no-frames | Skip all frame extraction (transcript only) | | --model <name> | Whisper model (default: mlx-community/whisper-large-v3-turbo) | | --backend <mlx\|cpp> | Whisper backend (default: mlx) | | --output-dir <path> | Custom output location |

Wait for the script to complete and note the output directory.

Step 3: Read the outputs

Read these files from the output directory:

• review.md — the structured review document with segments and frame references
• transcript.json — full transcript with word-level timestamps
• scene_changes.json — scene change timestamps (if --scene-detect was used)

Examine frames that appear relevant to the user's request. You don't need to look at every frame — use the transcript to identify which moments matter, then look at those frames.

Step 4: Analyze and synthesize

Based on the transcript and frames, produce:

1. Summary — Brief overview of what was covered
2. Key observations — Important feedback points, categorized (UX issue, bug, suggestion, positive feedback, question)
3. Prioritized issues — Ranked by severity/impact (P0-P3)

Always reference specific timestamps (e.g., [02:15]) and frame filenames when citing observations.

If the user specified a focus area (e.g., "accessibility", "onboarding", "error states"), weight the analysis toward that.

Step 5: Actionable output (based on user request)

Do whichever of these the user asks for:

• Issues — Create Linear or GitHub issues with titles, descriptions, reproduction steps, and frame references
• Report — Save a synthesized analysis.md in the output directory alongside the raw review.md
• Answer questions — If the user asked specific questions about the recording, answer with timestamp and frame evidence
• Comparison — If reviewing multiple recordings, compare and contrast findings

If the user doesn't specify, default to producing the summary + prioritized issues list, and ask if they want issues created.

Notes

• If transcript quality is poor (frequent [inaudible], nonsensical text), flag this and suggest re-running with a larger Whisper model (--model mlx-community/whisper-large-v3-turbo)
• Scene change detection may over-trigger on recordings with animations or video content — if the frame count is very high, mention this and suggest a higher threshold
• The transcript.json contains word-level timestamps even if --segment-duration wasn't used — you can reference specific words/phrases at exact timestamps
• Frame filenames encode their timestamp (e.g., seg_0012_45.3s.png = frame at 45.3 seconds) — use this to cross-reference with transcript