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 . # or: pip install video-review-os
video-review-os init-config # writes config.toml with every option documented
Optional extras: [whisper] or [faster-whisper] for local transcription, [hosted]
for any HTTP provider. ffmpeg and ffprobe must be on PATH.
1---2name: video-review-os3description: 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.4license: MIT5---67# Video Review OS89A local-first video pipeline. Footage goes in; reviewable artifacts come out. Every10stage writes a JSON artifact you can read, and nothing is ever published.1112## Before anything else1314Run `video-review-os providers`. It prints every pluggable capability and which15implementation is active. **Nothing here is tied to a particular AI vendor** — transcription,16tagging, storyboard, copy, and visual perception are all named providers resolved from17`config.toml`. If the user asks to "use model X", that is a config edit18(`provider = "openai-compatible"` plus a `base_url`), never a code change.1920## The pipeline2122```23scan → ingest → transcribe → select-clips → scenes → perceive → tag24 → captions → silence → storyboard → assemble → render-assemblies → approve25```2627`video-review-os run-once` walks the whole thing over the watch folder. Individual28commands take a project id or path, so you can re-run one stage without redoing the rest.2930| Command | Writes | What it gives you |31| --- | --- | --- |32| `ingest <file>` | `source.json` | ffprobe facts + content hash |33| `transcribe <p>` | `transcript.json` | words with timings (+ optional speakers) |34| `select-clips <p>` | `clips.json` | candidate ranges with keep/trim/review/reject |35| `scenes <p>` | `scenes/`, `scenes.json` | representative stills per clip |36| `perceive <p>` | `perception.json` | visual attributes + subject-aware reframe window |37| `tag <p>` | `tags.json` | source bucket + per-clip topics and visual attributes |38| `captions <p>` | `captions/` | SRT/VTT shaped for readability |39| `assemble <p>` | `assemblies.json` | concrete multi-range edit drafts |40| `render-assemblies <p>` | `renders/` | single-pass MP4s |41| `dashboard` | `dashboard/` | static review surface (`serve` for the editor) |4243## Rules you must not break44451. **`reject` is radioactive.** A rejected clip is never assembled, rendered, or queued.46 Not via a library pin, not via a filter, not via an override.472. **Providers are never trusted.** Any hosted output is sanitized to known enum values48 and degrades to the deterministic fallback. A provider failure must never abort a run.493. **Approval is a signature.** Anything that changes what renders — a range, a card, a50 reframe window — changes `assembly_signature` and invalidates prior approvals. Never51 work around this to preserve an approval.524. **Human overrides survive regeneration.** Corrections live in sidecars keyed by content53 hash (`tag_overrides.json`, `assembly_edits.json`), never by array index.545. **No auto-publish, ever.** The pipeline ends at approved local renders and manual queue55 files. Do not add upload adapters or platform APIs.566. **Schema bumps.** Change an artifact's shape, bump its `schema_version`.5758## Working with the artifacts5960Read them; don't guess. `clips.json` has the decision and score per candidate,61`perception.json` has what the pixels showed, `tags.json` joins both. When a user asks62"why was this clip rejected", the answer is in `clips.json`'s gate reasons — quote it.6364For deeper work on specific areas, load the companion skills: `video-perception` for65visual analysis and reframing, `video-tagging` for tags, buckets, and library search.6667## Setup6869```bash70pip install -e . # or: pip install video-review-os71video-review-os init-config # writes config.toml with every option documented72```7374Optional extras: `[whisper]` or `[faster-whisper]` for local transcription, `[hosted]`75for any HTTP provider. ffmpeg and ffprobe must be on PATH.
cgallic