---
name: "video_versioning_pipeline"
description: "Turn one locked video edit into every deliverable: mezzanine master, platform-specific cuts, review proxies, team-safe naming, checksum manifests, and archive practice. Use when a finished cut needs to become a full set of exports instead of a single file."
metadata: { "includeInPrompt": true }
---

# Video Versioning Pipeline

## Purpose

A finished edit is not a deliverable; it is the raw material for deliverables.
This skill runs the pipeline that takes a locked master and produces the whole
set: the archival master, every platform cut, review proxies, plus the naming,
checksums, and delivery notes that let a team hand files off without confusion.
One render of the master, then everything else derives from it, so nothing is
rendered twice.

## Workflow

### 1. Lock the master first

No versioning work starts until picture is locked and audio is mixed. Export
the mezzanine master ONCE from the timeline:

- Codec: ProRes 422 (or DNxHR HQX) at source resolution and frame rate.
  Visually lossless, editable, the single source of truth.
- Audio: stereo mix at broadcast level for the primary platform, plus a
  -14 LUFS / -1 dBTP pass for social platforms that normalize on upload.
- Everything downstream is a transcode or crop of this file. If a cut changes,
  re-render the master and bump the version, never patch a derived file by hand.

### 2. Build the deliverable matrix

List every (cut x platform x aspect) you need BEFORE encoding anything. Common
rows are in `references/platform-specs.md`. A typical matrix:

| Cut | Platforms | Aspect |
|---|---|---|
| Main cut | YouTube, website | 16:9 |
| Main cut | Instagram feed, X, LinkedIn | 1:1 or 4:5 |
| Short cut (under 60s) | TikTok, Reels, Shorts | 9:16 |
| Trailer / teaser | All | as needed |

If a version exists only as a maybe, cut it. Each row is real encode time.

### 3. Derive cuts, do not re-render

- Downscales only: never upscale resolution. Source 1080p stays 1080p or goes down.
- Aspect changes: center-crop or reframe per shot, never squish. For 9:16, keep
  critical content inside the platform safe zones (see platform-specs.md).
- Encode recipe for web deliverables: H.264 High Profile, VBR 8-15 Mbps at
  1080p, AAC audio, MP4 container, `-movflags +faststart` so playback starts
  before the file finishes downloading.
- Burn timecode into review proxies only, never into client deliverables.

### 4. Name everything with the grammar

`PROJECT_CUT_vNN_PLATFORM_RATIO.ext`

Examples: `BrandLaunch_main_v02_YouTube_16x9.mp4`,
`BrandLaunch_trailer_v02_TikTok_9x16.mp4`,
`BrandLaunch_master_v02_ProRes422_4K.mov`

Rules: zero-padded version numbers, one platform per file (a file that goes to
two platforms gets rendered twice or is clearly a shared export), date stamp
only on reference cuts, never spaces. Use the `bin/deliverables.py plan`
command to generate the full filename set from a matrix so the spelling is
machine-consistent.

### 5. QC every file against its row

For each output, verify with ffprobe: resolution, frame rate, codec, container,
duration within tolerance, audio present. Spot watch-through on the real
deliverable at least for the first file of each platform. Then run the checksum
step; a file that fails QC never enters the manifest.

### 6. Manifest and delivery note

- Write a SHA-256 checksum manifest covering every deliverable (see the
  `bin/deliverables.py manifest` command). Ship the manifest with the files.
- Write a delivery note (README.md next to the files): filename, platform,
  resolution, codec, duration, intended use. This one page prevents most
  client back-and-forth.
- The recipient verifies with `bin/deliverables.py verify`. A checksum mismatch
  means the file did not arrive intact; resend, do not patch.

### 7. Archive the master, not the exports

Keep: the master file, the project/timeline files, the source media (or a
verified proxy set if the source is too big to keep online), and the manifest.
Deliverables are regenerable from the master, so they are the first thing you
may delete when space gets tight. Archive is cold storage plus a tested
restore path, not a folder named "old".

## Output Contract

When the skill completes a run, the working directory contains:

- `master/`: the mezzanine master, named per the grammar.
- `deliverables/`: every platform cut, named per the grammar.
- `proxies/`: review copies with timecode burn-in (when requested).
- `DELIVERY.md`: the delivery note listing every file and its spec.
- `CHECKSUMS.sha256`: manifest covering deliverables + master.
- `archive/`: project files and anything cold, or a pointer to cold storage.

## Operating Rules

1. Master renders once per version. Version bumps are the only legal reason to
   re-render the master.
2. Never upscale. Downscale or stay at source resolution.
3. Never ship an un-QC'd file. ffprobe checks are cheap; re-exports are not.
4. No file enters a manifest without passing QC.
5. Naming grammar is machine-generated, not typed by hand.
6. Review proxies and client deliverables are different tracks; burn-in never
   appears in a deliverable.
7. When a platform's published specs disagree with `references/platform-specs.md`,
   the platform wins; update the reference file with the date and source URL.