AGENT SKILL

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.

License 许可
MIT
最近更新
2026-07-30
Stars
★ 7
Forks
4

01 前言 Front Matter

name
video-review-os
license
MIT
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.

03 SKILL.md 正文

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

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.

04 同仓库更多 Skills