Avenox Studio — operator router

The fast operator guide for a local-first, agent-operated video pipeline. Everything runs on your own machine: no cloud editor, no upload-to-render.

The human directs and approves quality; the agent runs the pipeline.

Setup

bash
export STUDIO_JOBS="$HOME/video/projects"   # heavy media lives here
export STUDIO_ROOT="/path/to/this/repo"     # scripts, templates, brand

Requirements: macOS (hardware encode via h264_videotoolbox; Apple Silicon for mlx-whisper), ffmpeg, python3, melt/MLT, Node (for HyperFrames). Most of this works on Linux with libx264 and a CUDA whisper build substituted in.

Operating principles

1. Media discipline. Heavy media NEVER in a cloud-synced folder — sync will

thrash on multi-GB intermediates and can corrupt in-flight writes. Jobs live in $STUDIO_JOBS/<job>/ (raw/ cut/ graphics/ audio/ outputs/). Your notes system holds only the brain: this system, the brand spec, edit.json plans.

1. Director loop. Produce a preview (graphics stills + a fast draft

render) → send for notes → only then final render. Never ship a final without sign-off. This is the single most important rule; an agent that renders finals unreviewed will burn hours on a rejected cut.

1. Brand is a hard constraint, not a suggestion. Read brand/frame.md

before making any graphic. Define it once and lock it. (The reference implementation is deliberately anti-"AI slop": premium editorial, warm paper + ink + a single accent, no neon/gradient/glassmorphism/3D-gloss.)

1. Format: YouTube 16:9 1080p60. Preset in brand/presets/youtube-16x9.json.
2. Finishing is hybrid. Auto-generate the draft; the same .mlt opens in

Kdenlive or Shotcut for hand-finishing. Don't try to automate taste.

1. Transcription defaults to LOCAL mlx-whisper with

whisper-large-v3-turbo — fast, free, and strong on non-English audio. Note that most LLM-routing proxies expose no whisper endpoint; if you go remote, use a dedicated speech API.

Scripts (scripts/)

| Script | Does | |---|---| | autocut.sh IN.mp4 [balanced\|aggressive\|conservative] | silence-cut → _cut.xml (Premiere) or --export variants | | transcribe.py IN.mp4 PREFIX | → transcript/PREFIX_timed.json + _narration.txt | | mltgen.py edit.json out.mlt --base <job-dir> | edit-list → MLT project (Kdenlive/Shotcut/melt) | | vrender.sh project.mlt out.mp4 [fast\|quality] | render (fast = HW draft, quality = CRF18 master) | | grabshot.sh | clipboard screenshot → disk | | slides2png.sh | legacy static slides — prefer HyperFrames | | remove-silence.py | standalone silence pass |

The 7 steps

1. Intake — copy raw → $STUDIO_JOBS/<job>/raw/. Confirm the brief and

which segments actually matter.

1. Rough cut — autocut.sh raw.mov balanced → cut/screen_cut.mp4;

transcribe.py for the script. Full recipe → avenox-roughcut skill.

1. Graphics — HyperFrames. Route via the hyperframes skill → usually

motion-graphics (short beats), faceless-explainer (concept stretches), or general-video. Read brand/frame.md first; render animated MP4s into graphics/. Full recipe → avenox-graphics skill.

1. Assemble — write edit.json (template in templates/edit.json) mixing

cut/*.mp4 + graphics/*.mp4 + music → mltgen.py edit.json project.mlt --base <job-dir>.

1. Captions — transcribe.py → .srt; apply brand/caption-corrections.json

(copy it from caption-corrections.example.json — a find/replace map for terms your ASR reliably mangles). Ship as YouTube CC, not burned-in.

1. Music — bed under everything, sidechain-duck under voice, target

~-14 LUFS. Track attribution in CREDITS.md.

1. Export — vrender.sh project.mlt draft.mp4 fast → director review →

vrender.sh … final.mp4 quality → prune scratch files.

Graphics quality bar

HyperFrames clips must obey brand/frame.md. Prefer type-driven, restrained, weighty motion. If a beat doesn't need motion, a clean static frame is fine — don't animate for the sake of animating.

Reference

• Rough cut: avenox-roughcut · Graphics: avenox-graphics
• HyperFrames skills: hyperframes (router), hyperframes-cli,

hyperframes-animation, hyperframes-creative, motion-graphics, faceless-explainer, general-video

• Brand spec: brand/frame.md (fill in from brand/frame.template.md)