npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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

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

Needs 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 would

An 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:

  1. 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.
  2. 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.
  3. 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 repeat

Captions

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 captioned

caption 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 later

Cloud 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 style

karaoke (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.mp4

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

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

  • assign takes timeline time by default (what you see in frame); it labels the source words behind that moment, so a repeated take is labelled in every repetition. --source takes source time.
  • Only one caption is on screen at a time: in crosstalk the groups alternate, each in its speaker's colour.
  • captions --cloud draws one colour: the cloud renderer does not know about speakers.
  • check warns about words with no speaker, speakers with a second or two in total (usually diarization noise: speakers merge) and unused definitions.
  • speakers and mainSpeaker are fields of the project, so apply can patch them with set-project. From exec, relabel by time with core.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-preview
p7 [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 chuva to guarda-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 free S<n>, and the main speaker is set to whoever talks to the camera only when the project has none.
  • --censor also asks for the profanity actually said and writes it as c**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; --model takes 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/--to for longer ones). Use --save-reply f.json to keep the model's answer and --reply f.json to 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 results

normalize 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 cut

The 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, muted

Clients

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

Sound

omsv audio p.omsv                                   # LUFS of every clip, as heard
omsv audio p.omsv --voice -16 --music-level -22 --duck 10

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

One 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 n2

check lists the open notes too.

Stems

omsv separate reel.mp4 --out stems     # reel.vocals.wav, reel.instrumental.wav

The 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 | logout

Credentials 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 picture

A 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 (or OMSV_RENDERER=ffmpeg) forces the ffmpeg path; so do its own options, --x264, --preset, --crf, --hw and --hw-decode.
  • --native (or OMSV_RENDERER=native) fails instead of falling back.
  • The encoder runs at constant quality: 0.7 by default and 0.8 with --final. --quality q picks another, --bitrate 12M an average bitrate. --ffmpeg --final is still x264 slow crf 17, for a smaller file.
  • --from/--to render 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_DIR moves it), capped by OMSV_CACHE_GB (default 20) with least-recently-used eviction; omsv cache ls|clear|gc manages it. Temp dirs are removed after each render. The preview cache is keyed by the timeline hash, so editing the project invalidates it. The first frame/grid/wave after 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 ffmpeg lacks drawtext; 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 --to therefore decodes wider than you asked and keeps only the words whose centre lands in your window, and find measures a second time in a short window around each hit. Trust a boundary that agrees with pauses, not one the model asserts alone.