@omelhorsite/video-cli
v0.6.0
Published
omsv - command line editor for .omsv video projects, built on @omelhorsite/video-sdk: create, inspect, edit, transcribe, caption and render from the terminal, and keep projects in the omelhorsite cloud.
Maintainers
Readme
@omelhorsite/video-cli
omsv: create, inspect, edit, transcribe, caption and render .omsv video
projects from the terminal, and keep them in the omelhorsite cloud. Built for
agents as much as for people: you never need to watch the video, because the
CLI draws frames and contact sheets as PNG.
bun add -g @omelhorsite/video-cli
omsv new p.omsv --width 1080 --height 1920 --fps 30 --name "Promo"
omsv add-asset p.omsv clip1.mov clip2.mp4 music.m4a logo.png
omsv grid p.omsv sheet.png # look at the timeline
omsv render p.omsv out.mp4 --finalNeeds Bun and ffmpeg in PATH. On Apple Silicon,
render uses a native renderer compiled with swiftc on first use (see
"Rendering on a Mac"). frame, grid, wave
and text rendering rasterise through qlmanage, so image output is macOS
only. Transcription goes to the omelhorsite cloud when you are signed in
(omsv cloud login); --local uses whisper-cli (brew install whisper-cpp)
and a model in ~/.cache/whisper-models/ instead.
Para agentes
omsv brief imprime o guia para agentes (o fluxo de edicao, as regras, um
topico por assunto: omsv brief --list). Vem com o pacote, por isso bate
sempre com a versao instalada. Para o Claude Code basta uma skill de duas
linhas que diga para correr omsv brief antes do primeiro comando.
The project file
A project is one .omsv file: a ZIP with the timeline and all of its media
inside, portable and self-contained.
project.omsv
├── manifest.json { "format": "omsv", "schema": 1, "savedAt": ... }
├── timeline.json the Project (asset paths relative: assets/...)
└── assets/<id>-<name> embedded media (stored uncompressed)unzip works, but prefer the CLI: it extracts media to a content-addressed
workspace, resolves paths, validates and packs again on save. Plain JSON
projects from before the format existed are accepted by every command.
Commands
new <out.omsv> [--width 1080] [--height 1920] [--fps 30] [--name s]
add-asset <p.omsv> <media...> embed media files in the project
add-color <p.omsv> <name> <RRGGBB> solid-colour image asset (flashes, backgrounds)
add-flash <p.omsv> --at 8.0 flash transition; --at is the CUT, not the start
[--duration 0.5] [--sound <assetId>] [--sound-volume 1] [--punch] [--wave]
asset-grid <p.omsv> <assetId> <out.png> contact sheet of a RAW asset [--every s] [--from --to]
inspect <p.omsv> [--json] summary; --json prints the raw Project
validate <p.omsv> [--json] structural checks; exit 1 on errors
transcribe <p.omsv> <assetId> words into the project, in source time
[--from s] [--to s] [--lang pt] [--model f.bin] [--at "23.4,28.6"]
[--cloud] [--plain] [--local] cloud per-word timings (default when signed in);
--plain: cue timings; --local: whisper.cpp
caption <p.omsv> [--lang pt] caption from the EDIT: transcribe what is heard
[--render f.mp4] [--size 320] [--dict fixes.json]
caption-style <p.omsv> [preset] caption look: karaoke | box; prints the style
find <p.omsv> <assetId> <phrase> where it is said, and where to cut to remove it
[--json] [--fresh] [--lang pt]
pauses <p.omsv> <assetId> pauses measured in the audio, threshold from it
[--from s] [--to s] [--min 0.06] [--noise-db -35] [--json]
at <p.omsv> <m:ss.s> timeline -> source: which file and which second of it plays there
at <p.omsv> <asset> <m:ss.s>... source -> timeline, or the cut that removed it
words <p.omsv> <asset> <1:08-1:12> words with MEASURED times and what lies between them
cut <p.omsv> <asset> <1:09-1:11>... remove source ranges; every boundary lands between two words
[--dry] [--exact] [--window 0.6] [--no-verify] [--voice on|off] [--json]
keep <p.omsv> <4521:0:00.9-1:09.25>... build the video track from source ranges, in order
[--file f.txt] [--asset id] [--track id] [--dry] [--exact] [--json]
check <p.omsv> [--fix] [--json] cuts that clip a word (in or out) and speech with no caption;
[--no-captions] --fix moves the cuts into silence; exit 1 on bad ones
dict <p.omsv> [--use client] [--set "key=value"]... [--rm key]... [--shared] caption spelling rules
models [align|voice] optional models for cutting (word alignment, voice separation)
normalize <media...> [--out dir] HDR to SDR, rotation, size and speech level; progress and ETA
[--width 1080] [--height 1920] [--lufs -16] [--peak -1] [--quality 70] [--jobs 2] [--x264] [--crf 18]
overlay <p.omsv> <image|video|assetId>... --at 0:28 pictures as cards over the speaker, with a shutter click
[--to 0:35 | --dur 4 | --each 0.78] [--source asset:t] [--in 13] [--scale .9] [--y .45] [--no-sound]
lib [ls | show c | add <file...> --client c --as outro|shutter|music | style c | set c | rm c name]
recipe <client> <p.omsv> apply a client's library: caption style, dictionary, shutter, outro
audio <p.omsv> [--voice -16] [--music-level -22] [--duck 10] loudness per clip, targets, ducking
color <p.omsv> <clipId...|--asset id|--all> [--exposure] [--contrast] [--saturation] [--warmth]
notes <p.omsv> [add "text" --at 0:28 | done <id> | reopen <id> | rm <id>] change requests
separate <media> [--out dir] [--from s] [--to s] vocals and instrumental stems
captions <p.omsv> <out.mp4> --cloud omelhorsite karaoke captions over the render
apply <p.omsv> --ops '{"ops":[...]}' declarative edits by id
exec <p.omsv> <script.ts> [--args '{...}'] arbitrary TypeScript with save()
render <p.omsv> <out.mp4> [--final] [--from s] [--to s] [--quality q | --bitrate 12M]
[--review] [--no-timecode] half size, ~3 Mbit/s, running time burned top-left,
and next to it the source file and its time (4521 1:09.2)
[--ffmpeg | --native] [--x264] [--hw] [--preset] [--crf]
cache <ls|clear|gc> [--only kinds] the on-disk cache (OMSV_CACHE_GB, OMSV_CACHE_DIR)
frame <p.omsv> <out.png> --t 3.2 one composed frame at t seconds
grid <p.omsv> <out.png> [--every s] [--cols n] [--cell px | --width px] [--per-page 48]
wave <p.omsv> <out.png> waveform of the final mix
open <p.omsv> open in the desktop app
pack <legacy.json> <out.omsv> embed referenced media into a zip
cloud login | logout | whoami | ls | push <p.omsv> | pull <id|name>
faces detect <p.omsv> [assetId...] people in the footage (Vision, Mac): ids F1.., contact sheet
faces blur <p.omsv> F3 [F5] | --all | --all-except F1 | --none [--style pixelate]
blur track <p.omsv> [assetId] --t s --box x,y,w,h [--label s] follow an object both ways
blur paper <p.omsv> [assetId] --from s --to s a sheet of paper outlined on every frame (no tracker)
blur box <p.omsv> [assetId] --from s --to s --box x,y,w,h | --poly ... a region that does not move
blur image <photo> -o <out.jpg> [--box ... | --poly ...] the same on a still picture
blur detect <p.omsv> [assetId] --t s [--text] [--documents] candidates on one frame
blur list | on | off | style | add | remove | clear | check <p.omsv> ...Every command takes paths, never stdin, and writes where you point it.
Seeing
frame, grid and wave composite the real timeline (layers, transforms,
opacity, fades, text, effects, captions) through a cached low-resolution
preview, so they are cheap to call while you iterate: edit, grid, look at
the PNG, repeat. Grid labels are index assetName tSECONDS. Before choosing
in-points on a raw clip, asset-grid shows one frame per second of it.
The captions are there because the thing most likely to be wrong is the text:
a caption under an image that covers it, or an image that lands on top of the
caption. At the default preview size they show where the band sits; --size
1080 makes the words readable, for checking the spelling without a render.
Editing
Declarative, by id (get ids from inspect --json):
omsv apply p.omsv --ops '{"ops":[
{"op":"set-clip","id":"CLIP_ID","patch":{"start":2.5,"duration":3}},
{"op":"split-clip","id":"CLIP_ID","at":3.2},
{"op":"set-project","patch":{"name":"new name"}}
]}'Ops: set-project, add-track (video|audio|text), remove-track,
add-clip, set-clip, split-clip (linked audio splits too), remove-clip.
A set-clip patch merges transform field by field; other fields replace.
Or with a script, for anything the ops cannot say:
import type { Project } from "@omelhorsite/video-sdk";
export default async ({ project, core, save, args }: {
project: Project;
core: typeof import("@omelhorsite/video-sdk");
save: () => Promise<void>;
args: unknown;
}) => {
const clip = project.tracks.flatMap((t) => t.clips).find((c) => c.kind === "text");
if (clip && clip.kind === "text") clip.text = "new text";
await save();
};Nothing is saved unless the script calls save().
Placement
A visual clip's transform is { x, y, scale, opacity }: x/y are the
centre in normalised coordinates (0..1) and scale multiplies the size the
asset gets when fitted inside the frame. To fill the frame, scale =
max(projW/fitW, projH/fitH); a 16:9 source in a 1080x1920 project fits to
1080x607, so filling the height is scale ~= 3.16, then pan with x. Check
with frame; never leave a face cut off.
blurBehind and shadow on a clip take a fraction of the project width, so
they survive the low-resolution preview.
The flash
The one full-screen effect: a pale glow grows from the lower left, blows the
frame out to white for an instant and recedes, while the image takes a zoom
punch. --at is the cut; the transition wraps around it and the shutter
sound fires exactly there. Fades on the clips either side should be zero.
Cutting
Times people send refer to the original files, not to the edit. Work in source time and let the tool translate:
omsv at p.omsv 1:22 # timeline 1:22.00 -> 4521 1:27.35 (clip s4) "amanhã"
omsv at p.omsv 4521 1:15 # 4521 1:15.00 is not on the timeline: cut between 1:13.50 and 1:23.15
omsv words p.omsv 4521 1:08.5-1:12 # each word with measured times, and a pause / glued join after it
omsv cut p.omsv 4521 1:09-1:11.5 1:13.5-1:23
omsv cut p.omsv 4521 --from-text "se não gostam da praça" --to-text "mudem"
omsv keep p.omsv 4521:0:00.9-1:09.25 4521:1:11.58-1:13.5 4522:0:00.7-0:14.05
omsv keep p.omsv '4521:"Olá a todos"-"até amanhã"' '4522:"Partilhem"-fim'
omsv apply-instructions p.omsv pedido.txt # the client's own messages -> proposed cuts; --apply
omsv hear p.omsv 4521 64.4-65.1 + 65.8-67.5 # listen to a window, or to pieces glued as the cut wouldAn asset is named by id, file name or the digits of the file name. cut
removes ranges and closes up every track; keep lays an edit list back to
back and keeps overlays pinned to the source moment they sat on. Each
boundary is reported with the word kept and the word dropped on its side:
corte 1: 4521 1:09.00-1:11.50 -> 1:09.300-1:11.595
fim 4521 1:09.00 -> 1:09.300 (+0.300) fica "amanhã" | sai "e" [pausa 40 ms] ouvido: ok
inicio 4521 1:11.50 -> 1:11.595 (+0.095) sai "depois" | fica "como" [pausa 30 ms]A cut is only safe between two words, and neither the transcriber's timings nor the silences alone say where that is: the timings are guesses, glued end to end and often a word off, and the sound also drops inside words — the closure of a /t/, /p/ or /k/ is silence, a /v/ or /lh/ is a dip, while a final /s/ is quiet but is speech. So every boundary is placed in three steps:
- Measure the level every 10 ms against a noise floor that follows the recording, with high-frequency energy counted as speech (fricatives). Pauses and the dips between glued words are candidates.
- Match each gap between two transcribed words to one candidate, by
dynamic programming: close to where the words are, as deep as possible,
never across a long pause, and with the sound on each side agreeing with
the letters (a word starting with s starts bright). Candidates left over
are inside a word and are never cut. With the alignment model installed
(
omsv models align, Portuguese) the words are first force-aligned to the audio, which puts them within 20-50 ms instead of 100-400. - Listen where it is not obvious (no clear pause): each side of the cut is transcribed alone, padded with silence, and must end or start with the whole word. With the rest of the sentence around it a model completes a clipped word ("priva-" becomes "privada"); alone it cannot. A boundary that fails is replaced by the next one that passes.
When there is music under the voice, the pauses are measured on the voice
separated from it (omsv models voice); the system sound classifier decides
when. A request that already falls in a measured pause of 80 ms or more stays
there and is never sent to the listening step: a wide pause leaves no doubt,
and a failed listen there says more about the listener. A pause of 160 ms or
more is always a boundary, even when the transcriber glued the words on both
sides together. Any boundary that ends up more than 0.15 s from the request is
reported as !! MEXEU, with the reason. --exact cuts where you say.
Quoted phrases are better anchors than rounded times: --from-text cuts from
the start of one phrase, --to-text resumes where another starts
(--through-text drops it too); the times only pick the occurrence. The
phrase is looked up in the captions, and its edge is checked against the
same word as the recognizer hears it: when they disagree, the report shows
both and says which one the sound supports.
A request over a restart ("fomos ao mercado ... ao mer- ... mercado central")
does not remove both attempts: when the range covers a word or words said
twice in a row, or a cut-off word said again in full, the proposal keeps the
first attempt whole and resumes at the first new word (or keeps the second
when the first was cut off), as one cut. --literal cuts what was asked.
apply-instructions reads the client's messages as they came (lists, quoted
lines, times in the original file, quoted phrases) and turns every cut
request into a proposal with the word left on each side and a confidence.
It only shows; --apply cuts.
hear pads each piece with silence (at least 2 s in all), glues several
pieces with a short gap, prints the level in ASCII and what each engine
hears: the omelhorsite cloud, the system recognizer, and Gemini through
OpenRouter only with --gemini (the audio leaves the machine).
After every cut the caption words near each join are put back on the speech
that stayed: a cloud timing that fell in the removed part used to drop a word
that is still heard. check looks at every join in the edit and reports the
ones that clip a word — the out-point that cuts a tail, the in-point that
catches the tail of the previous take — short islands (under 0.6 s between two
cuts of the same file, almost always the remains of a hesitation), words the
recognizer hears in a kept piece that no caption covers, and joins where the
recognizer and the captions disagree. --fix shows each correction with the
word on each side before and after and applies only with --yes; it never
moves a join that sits in a measured pause. --ack 4521:1:48.95 records a
join checked by ear in the project so it stops being reported.
pauses and find remain for looking at the raw audio:
omsv pauses p.omsv <assetId> --from 24 --to 25
omsv find p.omsv <assetId> --fresh "para a comunidade" # every occurrence: takes repeatCaptions
Caption from the edit, not from the raw material:
omsv caption p.omsv --lang pt # transcribes the cut, stores it in source time
omsv render p.omsv out.mp4 # comes out captionedcaption renders the timeline, transcribes what is actually heard, and maps
each word back through the clip that carries it. The words still live in the
.omsv in source time, so cutting, trimming or reordering afterwards
never invalidates them.
Transcribing the raw material also works and is what transcribe does, but it
breaks as soon as a sentence is said twice: the model folds the attempts into
one and its timings cannot say which of them survived the edit. The result is
words missing at one join and words at another that nobody says.
omsv transcribe p.omsv <assetId> --lang pt # cloud, per-word timings
omsv transcribe p.omsv <assetId> --plain --lang pt # cloud text transcriber, cue timings
omsv transcribe p.omsv <assetId> --local # whisper.cpp, offline
omsv add-asset p.omsv clip.mp4 --transcribe --lang pt # start the cloud job now, wait laterCloud results are cached in ~/.cache/omsv/transcripts, keyed by the audio
itself (16 kHz mono PCM of the window) plus language and mode: the same audio
in another project, or after re-embedding, comes back instantly. --transcribe
on add-asset or normalize starts the job and returns; the next
transcribe of that audio only waits for what is left. The job state (queue,
progress, machine, time left) goes to stderr. Cloud commands can run in
parallel: only the token refresh is serialized, through a lock file next to
the credentials.
Spelling rules belong in the project's caption dictionary, applied every time captions are drawn, so a new transcription gets them too:
omsv dict p.omsv --use acme # this client's shared rules
omsv dict p.omsv --shared --set 'portugu[êe]s(a|es|as)?=portuguez$1'
omsv dict p.omsv --set 'merda=m**da'
omsv dict p.omsv --set '4º=IV'A key is a word or a phrase, matched ignoring case, accents and punctuation,
or a pattern with groups. The value takes the capitals of what it replaces;
an empty value deletes; a phrase merges its words ("dar te=dar-te").
Shared rules live in ~/.config/oms-video/dict/<name>.json and are merged
under the project's own whenever it opens. caption --dict fixes.json
still rewrites the stored words once, for names a model always gets wrong.
transcribe --at "23.43,28.62" crosses the transcript with the measured
pauses and says where to cut instead. Use it before choosing a cut.
captions --cloud renders the project without captions, sends it to the
omelhorsite captions renderer with the timeline's words and the project's
caption style, and downloads the captioned mp4. With an OAuth sign-in the
render has to stay under 64 MiB; raise --crf if it does not.
To edit the text without transcribing again, change
project.captions[].words with exec; the timings stay.
The style's fontFamily has to be installed on the machine, not merely
named: nothing refuses a font that is missing, the next family in the list is
drawn instead, and the only symptom is letterforms that no longer match videos
rendered elsewhere. A warning is printed when the first family is not found.
Styles
omsv caption-style p.omsv box # highlight box instead of a highlight colour
omsv caption-style p.omsv # prints the effective stylekaraoke (the default) colours the active word. box keeps every word white
and puts the active one on a rounded blue box, in Poppins, with a soft shadow
and no outline. The box pops: it enters at 95% of its size, settles in about
0.1 s and shrinks back the same way before the highlight moves on; only the
box scales, the text stays still. Every field of the preset can be changed
afterwards with apply (set-project with a captionStyle patch): highlight
is the box colour, boxPadX/boxPadY/boxRadius are fractions of the font
size, boxPop and boxPopTime shape the animation. The box style needs
Poppins installed. captions --cloud does not draw the box: it renders the
colour highlight on the server.
strokeScale is the visible outline, as a fraction of the font size; the
text is laid out with the font's own metrics, so a word is as wide as the font
says it is.
Speakers
Words carry a speaker ("S1", "S2", ...) in source time, like their
timings, so it follows them through cuts and reorders. A word with no speaker
belongs to the main speaker, so projects that never heard of speakers render
exactly as before. The main speaker uses the style's own highlight; every
other speaker gets an accent of their own (the box colour, or the active-word
colour in karaoke), taken from a palette or from speakers set --color. A
caption group never mixes speakers: it breaks where the speaker changes.
omsv caption p.omsv --lang pt --speakers 2
omsv speakers p.omsv # who is who: samples + frame hints
omsv frame p.omsv s.png --t 16.8 # look at the face
omsv speakers set p.omsv S2 --name Mulher --main
omsv speakers transcript p.omsv # read it, fix what detection got wrong
omsv speakers assign p.omsv S1 --from 14.0 --to 15.2
omsv speakers merge p.omsv S3 S2
omsv render p.omsv out.mp4Detection is local and optional. It runs sherpa-onnx through uv (or through
the Python in OMSV_PYTHON, which needs sherpa-onnx and numpy) and needs
two models:
mkdir -p ~/.cache/omsv-models/diarization && cd ~/.cache/omsv-models/diarization
curl -L https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-segmentation-models/sherpa-onnx-pyannote-segmentation-3-0.tar.bz2 | tar xj
mv sherpa-onnx-pyannote-segmentation-3-0/model.onnx segmentation.onnx
curl -L -o embedding.onnx https://github.com/k2-fsa/sherpa-onnx/releases/download/speaker-recongition-models/nemo_en_titanet_small.onnxPass --num: guessing the number of people is where it goes wrong. Detection
is a draft and is wrong in crosstalk and shouting. Manual assignments are
locked, and a new detection (without --force) keeps them. Re-running caption
or transcribe keeps the labels as well.
assigntakes timeline time by default (what you see inframe); it labels the source words behind that moment, so a repeated take is labelled in every repetition.--sourcetakes source time.- Only one caption is on screen at a time: in crosstalk the groups alternate, each in its speaker's colour.
captions --clouddraws one colour: the cloud renderer does not know about speakers.checkwarns about words with no speaker, speakers with a second or two in total (usually diarization noise:speakers merge) and unused definitions.speakersandmainSpeakerare fields of the project, soapplycan patch them withset-project. Fromexec, relabel by time withcore.assignSpeaker(project, { speaker: "S2", from: 14, to: 15.2, time: "timeline" }).
Reviewing captions with a model
Word timings from a transcriber are usually precise; the text and the speakers
are what go wrong in a crowd or when people talk over each other (a phrase
heard as another, a repeated line invented over silent footage, two speakers
swapped). caption-review sends a light render of the edited timeline to a
multimodal model through OpenRouter and asks, per
phrase, for the corrected text, who says it, and whether anybody says it at all.
export OPENROUTER_API_KEY=sk-or-... # or one line in ~/.config/oms-video/openrouter.key (0600)
omsv caption-review p.omsv --from 0 --to 30 # shows the diff, writes nothing
omsv caption-review p.omsv --from 0 --to 30 --apply
omsv caption-review p.omsv --hint "street confrontation, crowd shouting" --censor
omsv caption-review p.omsv --model google/gemini-3.1-pro-previewp7 [00:14.03-00:15.20] S1 -> S2
sem [-a-] [-organizacao-]{+autorizacao+}
p9 [00:21.40-00:22.80] S1 REMOVIDA (sem fala)
[-Ele-] [-esta'-] [-irritado?-]- The model never decides timing. Its text is aligned word by word onto the
words the project already has (accents, case and punctuation ignored): words
that match keep their time, new words share the gap between their neighbours
(with no gap, a neighbour lends at most half of its time; one word that becomes
several shares its own span among them by length), a dropped word
gives its time to the word that absorbs it (
guarda chuvatoguarda-chuva), words it did not hear are dropped, and phrases it flags as not said are removed. Footage used twice on the timeline is reviewed at every position; a phrase that repeats source words already rewritten by another is left as it is, with a warning. A phrase never spans a cut, so new words land only in footage that is on the timeline. Written back in source time, locked speakers untouched unless--force; labelled words become locked. - Speakers come back with a short description of the person, stored on the
project speaker (
description). A speaker only appears when a word carries it. They are mapped onto the project's existing speakers when it is the same person, new ones get the next freeS<n>, and the main speaker is set to whoever talks to the camera only when the project has none. --censoralso asks for the profanity actually said and writes it asc**alho(first letter,**, what follows the third letter). Words that were already censored are written out for the model and masked again.- Default model
google/gemini-3.8-flash;--modeltakes any OpenRouter model that accepts video. A 30 s window should cost about a cent or less (an estimate, not measured: roughly 9k prompt tokens at the model's listed price). The cost the API reports is printed. - The video is a 360x640, 12 fps proxy with no burned captions, sent inline as
base64 (limit 12 MB: use
--from/--tofor longer ones). Use--save-reply f.jsonto keep the model's answer and--reply f.jsonto apply it later, offline.
Privacy: the footage and its audio are uploaded to OpenRouter and the model's
provider. Nothing else in omsv does that; the command only runs when you
type it, and it says what it is sending before it does. Do not use it on
material that must not leave the machine.
caption-censor p.omsv [--words a,b | --list f.txt] [--apply] does just the
masking, locally, with a built-in Portuguese list or yours.
Media from a phone
add-asset warns when a file is HDR or carries a rotation matrix, because
neither shows up until the first render: one clip arrives on its side, the
next arrives washed out because an HLG curve was read as bt709.
omsv normalize *.MOV --out ready # then add-asset the resultsnormalize converts HDR to SDR, applies the rotation for good, fits the video
inside a box without changing its proportions, outputs limited-range BT.709
(full-range input would keep the render off the fast path), and levels the
speech. The level is a plain gain, not compression, and the peak ceiling wins
over the loudness target: better a clip slightly low than a mix touching
0 dBFS. The HDR conversion is a transfer-function change, which is right for
the HLG that phones record and clips highlights on PQ.
The size only ever goes down: a source smaller than the box (a 720x1280
outro) is kept as it is, since the render fits every clip to the frame
anyway. On Apple Silicon the encoder is the Mac's H.264 at constant quality
(--quality 70, measured at the quality and size of x264 crf 18 with a
quarter of the CPU), two files at a time; --x264 or --crf use software.
Overlays
omsv overlay p.omsv comment.jpg --at 0:28 --to 0:35
omsv overlay p.omsv poster.png --source clip1:27.25 --to 35.25 # source time, follows the cutThe card preset: a track of its own above the video, scaled to fit within
90% of the width and 55% of the height, centred at y 0.45, the background
blurred behind it (blurBehind 0.03), a soft shadow (0.015) and 0.06 s
fades, plus a quiet shutter click (volume 0.22) on a Sfx track. The click
is one asset shared by every card: the client's (see Clients below) or
synthesised on first use, so no sample licence comes with it; --sound
uses an asset of yours instead. The blur and the shadow follow the card's
fades, so the first and last frames never show a blurred plate with no card.
omsv overlay p.omsv a.jpg b.jpg c.jpg --at 9 --each 0.78 # a burst, each scaled on its own
omsv overlay p.omsv clip.mp4 --at 33 --to 44 --in 13 # a video card from second 13, mutedClients
What a client always gets lives once in ~/.config/oms-video/lib/<client>/
(or OMSV_LIB_DIR), outside every project: an outro, a shutter, approved
music, a caption style, a caption dictionary and the rules an editor should
know. omsv recipe <client> p.omsv applies it.
omsv lib add outro.mp4 --client acme --as outro
omsv lib add click.wav --client acme --as shutter
omsv lib style acme box --highlight '#e30613'
omsv lib set acme --dict acme --shutter-volume 0.22 --rule "..."
omsv recipe acme p.omsvSound
omsv audio p.omsv # LUFS of every clip, as heard
omsv audio p.omsv --voice -16 --music-level -22 --duck 10Loudness is measured once per file (EBU R128, momentary, cached) and the
targets live in the project, so trimming or moving a clip never measures
again. --voice gives every voice the same integrated loudness; a clip's
volume still trims on top (--reset-volume puts them back at 1).
--duck lowers the music by that many dB wherever someone speaks, with
short ramps, and lets it back up in the gaps. Both renderers share the same
mix.
Colour
omsv color p.omsv --all --exposure 0.08 --saturation 0.18 --warmth 0.2One map per clip on the video signal, the same in both renderers. Values are small: 0.1 is already visible.
Notes
omsv notes add p.omsv "music too loud here" --at 1:05 --author client
omsv notes add p.omsv "I look pale" --source clip1:30 # follows the cut
omsv notes p.omsv # what is left
omsv notes done p.omsv n2check lists the open notes too.
Stems
omsv separate reel.mp4 --out stems # reel.vocals.wav, reel.instrumental.wavThe MDX-Net model UVR-MDX-NET-Inst_HQ_3 (67 MB, in
~/.cache/omsv-models/separation/; the error message says where to get it)
run by uv with onnxruntime. On Apple Silicon it runs on CoreML, about 15 s
per minute of audio against about 88 s on the CPU, with the same result.
Cloud
omsv cloud login # device flow: shows a code and a link, opens the browser
omsv cloud ls # projects in the account's oms-video/ folder
omsv cloud push p.omsv # the whole file; replaces one with the same name
omsv cloud pull <id|name> # the whole file back
omsv cloud whoami | logoutCredentials live in ~/.config/oms-video/credentials.json with mode 0600.
--client-id and --base-url (or OMS_VIDEO_CLIENT_ID, OMS_VIDEO_BASE_URL)
point at another registration or another server. Do not run two cloud
commands at once: the refresh token rotates, and the second process is left
holding the old one.
Hiding faces and objects
omsv faces detect p.omsv # every person in the parts the timeline uses; writes p-caras.png
omsv faces blur p.omsv --all-except F1 # or: F3 F5, --all, --none; --style pixelate
omsv blur detect p.omsv --t 12.3 # text and documents on that frame, as ready --box values
omsv blur track p.omsv --t 12.3 --box 0.61,0.43,0.05,0.02 --label plate
omsv blur paper p.omsv img_1 --from 23 --to 33 # a sheet held in a hand, found again on every frame
omsv blur check p.omsv check.png --dense # every frame where the region moves fast, holes flagged
omsv blur image photo.jpg -o out.jpg # a still pictureA sheet of paper is segmented frame by frame (paper colour, then shape, with the person around it), and each frame hides the union of the outlines a few frames either side, so a missed frame does not flash. The margin around it never enters a face it does not cover. The native renderer draws outlines exactly; the ffmpeg path reads them as a quarter-size mask the CLI writes.
Detection runs Apple's Vision framework (faces, and the body pose to follow a
head that turns away) in a small Swift program compiled on first use, like
the renderer. What it finds is stored in source time, so it follows every cut.
A box that was not seen at that instant is held, moving and growing, and the
check grid frames those cells in yellow. Fix a box by hand with
omsv blur add <id> --t s --box x,y,w,h, or mark a person as gone with
--none. Both renderers draw the blur; the native one at no measurable cost.
Rendering on a Mac
On Apple Silicon, render draws the project with a small native renderer:
the hardware video decoder, the GPU and the hardware H.264 encoder, fed by
the SDK's renderPlan. It produces the same picture as the ffmpeg path,
frame for frame, several times faster and with a fraction of the CPU and
memory. Its source is in native/ and is compiled with swiftc the first
time it is needed (a few seconds), into
the native kind of the cache (~/.cache/omsv/native/<hash>/); the hash
covers the sources and the compiler, so an update rebuilds it. swiftc comes
with the Command Line Tools (xcode-select --install).
render --review is for watching and quoting times: the same layout at half
the size (1080x1920 becomes 540x960), about 3 Mbit/s, and the running time
(mm:ss.s) burned top-left; --no-timecode leaves it out. The native
renderer decodes the original media; sources with an alpha channel make it
fall back to ffmpeg, which keeps them transparent. The ffmpeg fallback renders the same scaled project, without the
timecode (and so does --review with ffmpeg-only flags such as --hw). With --from/--to the label shows project
time, and it is drawn over the flash so it stays readable during transitions.
Whatever the native renderer cannot draw falls back to ffmpeg on its own,
with one line on stderr saying why: rotated video, HDR or full-range video,
a non-integer frame rate, an effect other than the flash, a fade shorter than
half a frame, a source AVFoundation cannot decode, a missing swiftc, or any other
failure of the native path. The JSON render prints says which
renderer ran ("renderer") and, after a fallback, why ("fallback").
--ffmpeg(orOMSV_RENDERER=ffmpeg) forces the ffmpeg path; so do its own options,--x264,--preset,--crf,--hwand--hw-decode.--native(orOMSV_RENDERER=native) fails instead of falling back.- The encoder runs at constant quality: 0.7 by default and 0.8 with
--final.--quality qpicks another,--bitrate 12Man average bitrate.--ffmpeg --finalis still x264slowcrf 17, for a smaller file. --from/--torender natively, sound included.- The audio mix is the SDK's
compileAudio(the same filters as the ffmpeg path), encoded with AudioToolbox and cached by its inputs in~/.cache/omsv/audio; it runs while the caption band is built. The caption band is the one the ffmpeg path uses, re-wrapped once as ProRes 4444 next to it in the cache, because AVFoundation does not decode qtrle.
bun test renders small synthetic projects both ways (sources at 25, 30
and 60 fps, in-points, starts and durations off the frame grid, a
--from/--to window, blur behind, shadow, fades, text, box captions, a flash)
and requires an SSIM of at least 0.97 between them, frame counts and audio
included. They measure about 0.996.
Speed
A render exists so someone can look at it. Measured on a 150 s 1080x1920 project (20 cuts, two zooms, three overlays with blur behind and shadow, four flashes, box captions) on an M3:
| | ffmpeg path | native |
|---|---|---|
| warm caches | 50 s, 254 s of CPU, 3.0 GB | 25 s, 5 s of CPU, 0.1 GB |
| one cut moved | 56 s | 30 s |
| --final | 326 s (x264 slow) | 25 s |
| cold caches | 84 s | 69 s |
| --from 30 --to 40 | 2.6 s | 3.1 s |
The native renderer is bound by the hardware encoder (about 200 frames per
second at 1080x1920), and it leaves the CPU free. A cold render is dominated
by rasterising the caption states, which both paths share. --from/--to
renders only the window that changed. On the ffmpeg path the bottleneck is the
filter graph, not the encoder; --x264 forces software encoding, --preset
or --crf imply x264, and --hw-decode decodes sources that probe as
decodable on the hardware (no wall-time gain measured, not bit-exact, never
for alpha). Caption rasters are cached per SVG, so moving a cut only
rasterises the states it created.
Gotchas
- A render writes to
<dest>.part-<pid>and renames at the end. Never point two renders at the same destination. - Everything cached (extracted media, caption rasters, caption strips,
audio mixes, previews, probes, the compiled native renderer) lives in
~/.cache/omsv(OMSV_CACHE_DIRmoves it), capped byOMSV_CACHE_GB(default 20) with least-recently-used eviction;omsv cache ls|clear|gcmanages it. Temp dirs are removed after each render. The preview cache is keyed by the timeline hash, so editing the project invalidates it. The firstframe/grid/waveafter an edit pays a low-resolution render; repeats are instant. - Assets inside the zip are stored uncompressed on purpose: saving is disk-copy fast and re-zipping never degrades anything.
- Homebrew's
ffmpeglacksdrawtext; that is fine, text is rasterised to PNG overlays. - A speech model's timings drift over long audio — half a second after two
minutes is normal — and it stretches the first and last word of whatever
window you give it out to the edges.
transcribe --from --totherefore decodes wider than you asked and keeps only the words whose centre lands in your window, andfindmeasures a second time in a short window around each hit. Trust a boundary that agrees withpauses, not one the model asserts alone.
