# Video Review Os

> 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.

- Skill: `cgallic/video-review-os` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cgallic/video-review-os`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cgallic/video-review-os/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: cgallic (https://skillmd.com/u/cgallic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cgallic/video-review-os

---


# 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

1. **`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.
2. **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.
3. **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.
4. **Human overrides survive regeneration.** Corrections live in sidecars keyed by content
   hash (`tag_overrides.json`, `assembly_edits.json`), never by array index.
5. **No auto-publish, ever.** The pipeline ends at approved local renders and manual queue
   files. Do not add upload adapters or platform APIs.
6. **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

```bash
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.