Vc Screenscribe

Vibecrafted. Screenscribe

Use this skill for two related jobs:

1. Run Screenscribe on real recordings and turn them into actionable outputs.
2. Work on the Screenscribe codebase without guessing its CLI, gates, or report model.

Canonical Orientation Gate

For Screenscribe repo work, run or consume the vc-init procedure before editing, planning, or release judgement. Loctree:loctree is the default structural perception skill for that pass and must produce or refresh the Code-Derived Application Map.

If fresh vc-init evidence is absent, perform the init pass first and treat Screenscribe repo work as blocked until repo truth exists.

For pure video-analysis runs, state the no-repo exception and use the installed Screenscribe CLI directly.

Repository Work Doctrine

For repository work, start with Loctree as the map: use loct context, loct occurrences, loct body, and loct find --literal before broad manual search. Use AICX for intent and session context. Use rg/grep as fallback or local magnifier, not as a replacement for structural mapping. If Loctree fails or misses a surface, append feedback to ~/.vibecrafted/loctree/loctree-fail.md.

What Screenscribe Is

Screenscribe is a screencast pipeline, not a vague "video AI thing."

Its strongest value is artifact production:

• extracts audio from videos
• transcribes commentary with timestamps
• detects bugs, change requests, and UI issues
• captures screenshots at relevant moments
• generates transcript, JSON, Markdown, and optional HTML Pro outputs

Primary commands exposed by the project:

• review
• analyze
• transcribe
• preprocess
• config
• version

When To Use

Use this skill when the user wants to:

• analyze a screen recording of an app review
• turn spoken bug commentary into structured findings
• process one or many .mov / .mp4 files
• generate HTML Pro reports, screenshots, transcripts, or transcript-first bundles
• run Screenscribe in dry-run, estimate, resume, or batch mode
• extract artifacts first and let an agent/model analyze them later
• debug Screenscribe output, prompts, providers, or report generation
• modify the Screenscribe repo and keep its quality gates honest

Default Mindset

Do not treat Screenscribe like a model endpoint. Treat it like a concrete pipeline with real stages, real artifacts, and real failure points.

Default to the shortest working path. If the user hands you a video and wants review findings, the first move is usually just:

screenscribe review /absolute/path/to/video.mov

Do not start by circling around uv run, repo internals, or --help unless:

• the user explicitly wants repo/debug work
• the screenscribe command is missing
• the first real run failed and you are diagnosing why

Always establish:

• what the input video set is
• whether the goal is review, preprocess, analyze, or transcribe
• whether the user wants speed, depth, interactivity, or artifact extraction
• whether provider config and FFmpeg are available

Fast Decision Table

Use this mapping:

• User wants full actionable review from one or more narrated videos:
  • use screenscribe review ...
• User wants transcript-first artifact bundle for downstream model/agent work:
  • use screenscribe preprocess ...
• User wants transcript only:
  • use screenscribe transcribe ...
• User wants interactive/reversed flow server:
  • use screenscribe analyze ... or repo make analyze
• User wants to change the tool itself:
  • work in repo and run repo quality gates

Fast Path First

For normal user-facing video analysis, prefer the installed CLI directly:

screenscribe review /absolute/path/to/video.mov

Batch:

screenscribe review /path/video1.mov /path/video2.mov -o /absolute/output/dir

Transcript-first bundle:

screenscribe preprocess /absolute/path/to/video.mov

Transcript only:

screenscribe transcribe /absolute/path/to/video.mov -o /absolute/path/to/transcript.txt

This is the default path unless it fails.

Transcript-First Lane

preprocess is the artifact-first lane. Use it when the user wants the deterministic parts of the pipeline without committing to semantic/VLM analysis.

Expected bundle:

{video}_preprocess/
  transcript.txt
  transcript.timestamped.txt
  transcript.segments.json
  transcript.vtt
  preprocess.json
  audio.mp3

This is the best handoff shape when:

• a later model/agent should choose timestamps or POIs
• the user wants transcript and timing truth first
• analysis quality is suspect and the artifact pack matters more

Repo / Debug Path

Canonical upstream repo:

• vetcoders/Screenscribe

When repo work is needed, prefer the current Screenscribe checkout if the user already opened one. Do not assume a fixed local path. If no checkout is open, refer to the default repo above and only mention a local path once it is actually known.

Drop into the repo only when:

• the CLI is missing or broken
• provider/config/runtime debugging is needed
• the user wants work on Screenscribe itself

Then prefer:

cd /path/to/Screenscribe
uv run python -m screenscribe review /absolute/path/to/video.mov

Review

Single video:

cd /path/to/Screenscribe
uv run python -m screenscribe review /absolute/path/to/video.mov

Batch:

cd /path/to/Screenscribe
uv run python -m screenscribe review /path/video1.mov /path/video2.mov -o /absolute/output/dir

Useful flags:

• --keywords-only
• --estimate
• --dry-run
• --no-vision
• --resume
• --lang en
• -o /path/output

Preprocess

cd /path/to/Screenscribe
uv run python -m screenscribe preprocess /absolute/path/to/video.mov

Useful flags:

• --no-audio
• --force
• --lang en
• -o /path/output

Transcribe

cd /path/to/Screenscribe
uv run python -m screenscribe transcribe /absolute/path/to/video.mov -o /absolute/path/to/transcript.txt

Interactive Analyze Server

Preferred:

cd /path/to/Screenscribe
make analyze VIDEO=/absolute/path/to/video.mov PORT=8766

Safe Triage Commands

Only use these if the normal screenscribe review ... or screenscribe preprocess ... path failed:

screenscribe review --help
screenscribe preprocess --help
screenscribe version
ffmpeg -version
test -f ~/.config/screenscribe/config.env && echo CONFIG_OK || echo CONFIG_MISSING

Output Expectations

For a normal review run, expect an output directory like:

{video}_review/
  {video}_transcript.txt
  {video}_report.json
  {video}_report.md
  {video}_report.html
  screenshots/

For preprocess, expect the transcript-first bundle described above.

When reporting results back to the user, always include:

• input video(s)
• exact command run
• output directory path
• whether run was full, preprocess-only, dry-run, keywords-only, or no-vision
• important blockers or warnings

Config and Dependencies

Important runtime dependencies:

• Python 3.11+
• uv
• FFmpeg
• configured provider credentials / endpoints

Primary config file:

• ~/.config/screenscribe/config.env

If a run fails, check these first:

1. FFmpeg installed and visible in PATH
2. API keys configured
3. endpoint/model alignment
4. output path permissions
5. whether user wanted review but actually needed preprocess, transcribe, or analyze

Do not invent config values or fake API success.

Repo Workflows

When editing or debugging Screenscribe itself, use the repo-native gates:

cd /path/to/Screenscribe
make lint
make typecheck
make test

Useful extras:

make security
make test-integration
make test-all
make format

If integration tests need external API access and keys are missing, say so clearly and run unit tests plus static gates.

Investigation Order For Failures

When Screenscribe behavior looks wrong, debug in this order:

1. command shape
2. input file validity
3. FFmpeg/audio extraction
4. transcription output
5. detection or preprocess mode choice
6. screenshot extraction
7. semantic / unified analysis
8. report generation
9. HTML Pro rendering/opening

Do not jump straight to model blame before checking pipeline stage boundaries.

Output Format For Screenscribe Tasks

Use this response structure when helpful:

Current state: what the input is and what Screenscribe path we are using.
Proposal: which command/workflow best fits and why.
Migration plan: concrete steps or fixes if repo work is involved.
Quick win: the smallest useful run or fix right now.

If the task is simple, compress this into a short paragraph.

Examples

Example 1 Input: "Przeleć mi ten review.mov i wypluj JSON + markdown z bugami." Action: run screenscribe review /absolute/path/to/review.mov, return output dir and key findings.

Example 2 Input: "Mam video, ale chcę tylko transcript, timestampy i pack dla agenta." Action: run screenscribe preprocess /absolute/path/to/video.mov, return bundle dir and artifact list.

Example 3 Input: "W repo https://github.com/vetcoders/Screenscribe coś popsuliśmy w HTML Pro." Action: treat this as repo work, use repo-native commands and quality gates, not a plain review run.

Anti-Patterns

Do not:

• treat Screenscribe as a generic summarizer
• start with repo plumbing when a plain screenscribe review <file> or screenscribe preprocess <file> would do
• probe --help before the first real run on a normal video-analysis request
• run random repo commands when make already defines the quality path
• skip reporting the output directory
• ignore whether the user wants review vs preprocess vs transcribe vs analyze
• claim a run is valid if FFmpeg or provider config is missing
• assume HTML report exists unless the run actually produced it
• trust the AI layer more than the transcript/screenshot artifacts when they disagree

Definition of Done

A Screenscribe task is done when:

• the right command was chosen
• the run or code change actually completed
• output artifacts are named and located
• blockers are concrete if the run could not finish
• repo changes, if any, pass the closest real quality gates