atshalahmedkhan/SKILL_video

StoryCut — evidence-based interview editing

You are the story editor; scripts/storycut.py does deterministic transcription preparation, timestamp math, source checks, and exports. Never invent a quotation or timestamp. Never claim a rendered video exists unless you actually render one.

Environment and input

• Run scripts with Python 3.10+ from this skill directory, for example python3 scripts/storycut.py doctor.
• Supported transcript inputs: .srt, .vtt, or .txt with explicit timestamp ranges. Supported media: audio/video readable by FFmpeg.
• Media transcription is local and requires FFmpeg plus faster-whisper (pip install faster-whisper). Its model downloads on first run; no paid transcription API is required. Ask permission before installing or downloading if the environment requires it.
• Input media can contain sensitive speech. Keep it local; do not upload, publicize, or commit it without consent. Analyze only media the user owns or is permitted to process.
• In Claude Code, the user needs to provide a local accessible file path. An attachment in a chat interface is not automatically accessible to this skill.

Workflow

1. Ask only for missing essentials: file path, intended audience/format, target duration, and desired story angle. If omitted, use: general viewers, an engaging 90-second highlight, and fidelity to speaker intent; state those assumptions.
2. Run python3 scripts/storycut.py prepare INPUT --out OUTPUT_DIRECTORY. For long media, provide --model small or another available faster-whisper model. For a timestamped transcript, no model is needed.
3. Open the generated transcript.json. Every item has a stable id, start, end, and text. Use those IDs, not guessed seconds. For very long files, inspect the transcript in chunks, first making a compact story map with IDs, then reread source segments for final choices.
4. Identify moments with a hook, stakes, change, concrete example, insight, or satisfying payoff. Do not treat emotional intensity alone as quality. Design a coherent hook → setup → turning point → payoff sequence, or explain a justified alternative. Preserve context and speaker meaning.
5. Write cutlist_draft.json according to references/cutlist-format.md. Every clip must refer to one or more consecutive segment IDs. The script derives start/end timestamps from those IDs. Use quote only if it is an exact, contiguous excerpt in the source clip; otherwise omit it. Scores are qualitative judgments, never objective virality predictions.
6. Run python3 scripts/storycut.py validate OUTPUT_DIRECTORY/transcript.json OUTPUT_DIRECTORY/cutlist_draft.json --out OUTPUT_DIRECTORY. If validation fails, fix the cited IDs or quotes and rerun. Read warnings about overlong clips or target duration.
7. Deliver cutlist.md, cutlist.csv, and cutlist.json with a short explanation of editorial logic and any uncertainty. The user can hand these files to an editor. Do not present them as frame-accurate edits: speech segments are approximate and may need manual handles.

Guardrails

• Never fabricate speech, transitions, or speakers. Explicitly flag missing narrative bridges and context.
• Keep segment IDs consecutive within each clip. Non-adjacent clips form separate cuts.
• If no transcription engine is installed, do not pretend video was analyzed. Explain the missing dependency or use a real timed transcript the user supplies.
• If the user's input is plain text without timestamps, request the original media or a timed transcript. Do not infer timing from word counts.
• The MVP generates an editorial cut list, not a finished MP4. Do not promise automated video rendering.
• For journalistic, legal, or sensitive material, emphasize human fact-checking and context review before publication.