| name | video-review-os |
| description | Review, tag, cut, and reframe video with Video Review OS — a local-first pipeline that turns raw footage into reviewable clip drafts, edit assemblies, captions, and vertical renders. Use when the user wants to process footage, find a moment across their library, tag or bucket clips, build a short from existing material, fix caption timing, or reframe horizontal video for vertical. Also use when they mention raw/, projects/, clips.json, tags.json, perception.json, assemblies.json, or the review dashboard. |
| license | MIT |
Video Review OS
A local-first video pipeline. Footage goes in; reviewable artifacts come out. Every
stage writes a JSON artifact you can read, and nothing is ever published.
Before anything else
Run video-review-os providers. It prints every pluggable capability and which
implementation is active. Nothing here is tied to a particular AI vendor — transcription,
tagging, storyboard, copy, and visual perception are all named providers resolved from
config.toml. If the user asks to "use model X", that is a config edit
(provider = "openai-compatible" plus a base_url), never a code change.
The pipeline
scan → ingest → transcribe → select-clips → scenes → perceive → tag
→ captions → silence → storyboard → assemble → render-assemblies → approve
video-review-os run-once walks the whole thing over the watch folder. Individual
commands take a project id or path, so you can re-run one stage without redoing the rest.
| Command | Writes | What it gives you |
|---|
ingest <file> | source.json | ffprobe facts + content hash |
transcribe <p> | transcript.json | words with timings (+ optional speakers) |
select-clips <p> | clips.json | candidate ranges with keep/trim/review/reject |
scenes <p> | scenes/, scenes.json | representative stills per clip |
perceive <p> | perception.json | visual attributes + subject-aware reframe window |
tag <p> | tags.json | source bucket + per-clip topics and visual attributes |
captions <p> | captions/ | SRT/VTT shaped for readability |
assemble <p> | assemblies.json | concrete multi-range edit drafts |
render-assemblies <p> | renders/ | single-pass MP4s |
dashboard | dashboard/ | static review surface (serve for the editor) |
Rules you must not break
reject is radioactive. A rejected clip is never assembled, rendered, or queued.
Not via a library pin, not via a filter, not via an override.- Providers are never trusted. Any hosted output is sanitized to known enum values
and degrades to the deterministic fallback. A provider failure must never abort a run.
- Approval is a signature. Anything that changes what renders — a range, a card, a
reframe window — changes
assembly_signature and invalidates prior approvals. Never
work around this to preserve an approval.
- Human overrides survive regeneration. Corrections live in sidecars keyed by content
hash (
tag_overrides.json, assembly_edits.json), never by array index.
- No auto-publish, ever. The pipeline ends at approved local renders and manual queue
files. Do not add upload adapters or platform APIs.
- Schema bumps. Change an artifact's shape, bump its
schema_version.
Working with the artifacts
Read them; don't guess. clips.json has the decision and score per candidate,
perception.json has what the pixels showed, tags.json joins both. When a user asks
"why was this clip rejected", the answer is in clips.json's gate reasons — quote it.
For deeper work on specific areas, load the companion skills: video-perception for
visual analysis and reframing, video-tagging for tags, buckets, and library search.
Setup
pip install -e .
video-review-os init-config
Optional extras: [whisper] or [faster-whisper] for local transcription, [hosted]
for any HTTP provider. ffmpeg and ffprobe must be on PATH.
