vidfix is a CLI-first media toolkit for developers, testers, creators — or anyone who just needs a file in the right shape. Tell it the fps, length, size, codec or format you want; it makes the file, then proves it.

What it does

No commands to learn

uvx vidfix

Run it with no arguments and vidfix asks what you want — no install, no syntax:

• Arrow keys, not typing. Every question is a menu, and every choice says what it means. Need something not listed? Pick other… and type it.
• Mistakes are caught on the spot. A bad answer is re-asked right there; the wizard never offers a choice the chosen format can't make.
• You see it before it runs. A summary box, then run, run & open, or cancel.
• You learn the one-liner. The equivalent command is printed for next time, and the full path of the saved file when it's done.

$ vidfix
╭─ vidfix ────────────────────────────╮
│ exact-spec media · no syntax needed │
╰─────────────────────────────────────╯
✓ Step 1 · What do you want to do?  generate
✓ Step 2 · Generate  video
? Step 3 · Output file (↑↓ to move, enter to pick)
 ❯ test.mp4    plays everywhere
   test.mov    Apple / editing
   test.mkv    holds anything
   test.webm   web video
   ...
   other…      type your own value

✓ Step 3 · Output file  fixture.mp4
✓ Step 6 · fps  30
✓ Step 7 · Duration  10s
✓ Step 8 · Resolution  1080p
✓ Step 11 · Audio channels  5.1
...
╭─ Ready to generate ───────────╮
│ pattern         smpte         │
│ fps             30            │
│ duration        10s           │
│ audio channels  5.1           │
│ resolution      1080p         │
│ output          fixture.mp4   │
╰───────────────────────────────╯
equivalent command: vidfix generate --pattern smpte --fps 30 --duration 10s --audio-layout 5.1 --res 1080p -o fixture.mp4

✓ Step 18 · Go ahead?  run & open
✓ wrote fixture.mp4
  location: /Users/you/clips/fixture.mp4

No arrow keys (a pipe, CI, a basic terminal)? The same questions come as a numbered list — answer 2, the name, or your own value.

Use it from Python

Same features, one import, the same spec forms as the command line:

from vidfix import convert, generate, verify, probe

generate("fixture.mp4", fps="59.94", duration="30s", res="720p")
info = probe("fixture.mp4")           # MediaInfo (pydantic)
result = verify("fixture.mp4", duration=30.0)
assert result.passed

Every function takes str or Path, frame rates as "29.97", 29.97 or Fraction(30000, 1001), and raises vidfix.VidfixError with a readable message when something can't be done.

Install

uvx vidfix                  # run instantly, nothing to install
pip install vidfix          # or keep it (or: uv tool install vidfix)

uvx vidfix@latest           # newest release with uvx
pip install -U vidfix       # upgrade with pip (or: uv tool upgrade vidfix)
vidfix --version            # which version you have

Everything vidfix needs is built in. Plain uvx vidfix may reuse a copy it downloaded earlier — add @latest to be sure you're on the newest release. What changed: CHANGELOG.md.

It refuses to write a broken file

Every output format has real limits — codecs it can hold, channel counts, frame rates, how many audio tracks fit. vidfix knows them. Impossible combinations stop before anything runs, with one plain sentence instead of a wall of log:

$ vidfix generate -o clip.webm --codec h264
error: .webm files can't hold h264; use one of: vp9.

$ vidfix attach clip.mp4 --audio en.wav --audio hi.mp3 -o out.flv
error: .flv holds at most 1 audio track(s); you attached 2. Use .mkv/.mp4/.mov.

$ vidfix generate -o surround.mp3 --audio-layout 5.1
error: .mp3 audio holds at most 2 channels; you asked for 6.

The wizard goes one step further: it simply never offers a choice the chosen format can't make.

Commands

Every command has --help. The same options are in the wizard.

Handy on every command that writes a file: --open opens the result when it's done. python -m vidfix works too. (probe and matrix still work as old names for info and variants.)

vidfix convert — exact-spec transforms

vidfix convert in.mp4 --fps 60 --res 1080p -o out.mp4
vidfix convert in.mp4 --fps 60 --smooth -o out.mp4          # motion-interpolated 30→60
vidfix convert in.mp4 --duration 10s -o out.mp4             # trim: instant stream copy
vidfix convert in.mp4 --duration 10s --precise -o out.mp4   # frame-accurate re-encode
vidfix convert in.mp4 --duration 60s --extend-mode loop -o out.mp4
vidfix convert in.mp4 --preset df60 -o out.mp4              # 59.94 = exact 60000/1001
vidfix convert in.mp4 --audio-layout 5.1 -o out.mp4         # remix audio to 5.1

Trims with an unchanged codec are stream-copied (instant, no quality loss). Resolution changes pad with black bars to preserve aspect ratio (--stretch to disable). Drop-frame rates are handled as exact rationals (30000/1001), never lossy floats.

vidfix generate — synthetic fixtures from nothing

vidfix generate -o bars.mp4 --fps 59.94 --duration 30s --res 1080p
vidfix generate -o count.mp4 --pattern testsrc --timecode    # running timecode overlay
vidfix generate -o df.mp4 --preset df30 --timecode           # drop-frame HH:MM:SS;FF burn-in
vidfix generate -o red.mp4 --pattern solid:red --audio none
vidfix generate -o surround.mp4 --audio-layout 5.1           # 6-channel audio
vidfix generate -o tone.wav --duration 3s --audio-layout left  # audio-only file
vidfix generate -o card.png --res 1080p --text "SCENE 1"     # still test card

Patterns: smpte, color-bars, testsrc, gradient, solid:COLOR. Audio: 440Hz tone (default), silence, none — any layout from mono to 7.1, or left/right for channel-identification checks.

The output extension picks the media kind: video (.mp4, .mov, …), audio-only (.wav, .mp3, .m4a, .flac, .ogg, .opus, .aac), or a still picture (.png, .jpg, .jpeg, .webp, .bmp, .tiff).

vidfix verify — spec assertions for CI

vidfix verify out.mp4 --fps 60 --duration 30s --res 1280x720 --codec h264
vidfix verify out.mp4 --fps 29.97 --json | jq .passed

Prints a pass/fail table per property; exit code 0/1.

vidfix info — metadata at a glance

vidfix info clip.mp4             # rich table
vidfix info clip.mp4 --json      # jq-friendly

$ vidfix info clip.mp4
 type          mp4 video
 duration      30.03 seconds
 resolution    1080p (1920x1080)
 fps           29.970 (df30, 30000/1001)
 video codec   h264
 color format  standard (yuv420p)
 bitrate       1200 kb/s
 audio         aac · stereo (left+right) · normal quality (44100 Hz)

Everything reads in plain words, with the technical value kept in brackets — 1080p (1920x1080), stereo (left+right), normal quality (44100 Hz). Broadcast rates get their preset name (df30, pal25, film24, …). --json gives every raw value for scripts.

vidfix caption — burn text into a video

vidfix caption in.mp4 --text "Take 42" -o out.mp4
vidfix caption in.mp4 --text "INTRO" --position top --color yellow -o out.mp4
vidfix caption in.mp4 --text "3..2..1" --start 0 --end 3 -o out.mp4
vidfix caption in.mp4 --text "corner" --position top-right -o out.mp4
vidfix generate -o clip.mp4 --text "TEST CLIP"      # caption a generated video too
vidfix convert in.mp4 --text "SUBTITLE" --position bottom -o out.mp4   # or while converting

Positions form a 3×3 grid: top-left, top, top-right, left, center, right, bottom-left, bottom (default), bottom-right. The same caption options are available on caption, generate, and convert. In caption, audio is re-encoded to whatever the output container accepts.

vidfix attach — mux audio and/or subtitles onto a video

vidfix attach clip.mp4 --audio track.m4a -o out.mp4                 # add an audio track
vidfix attach clip.mp4 --audio en.wav --audio hi.mp3 -o out.mkv     # two audio tracks
vidfix attach clip.mp4 --subs subs.srt -o out.mkv                   # soft subtitle track
vidfix attach clip.mp4 --subs subs.srt --burn -o out.mp4           # burn subtitles into the picture
vidfix attach clip.mp4 --audio track.m4a --subs subs.srt -o out.mkv # all at once

The video is stream-copied (no re-encode, no quality loss) whenever the output can hold it cleanly; otherwise — burned subtitles, a codec the output can't hold, or .avi/.mpg on either side — it is re-encoded so the file always plays. Repeat --audio to add several tracks (one per file, in order) — it works on any video, including a vidfix generate clip. .flv holds only one audio track; use .mkv/.mp4/.mov for more. Soft subtitles need a .mp4/.mov/.mkv/.webm output — for other containers use --burn.

vidfix format — any picture or video to any format

vidfix format clip.mov -o clip.mp4      # container conversion
vidfix format clip.mp4 -o clip.gif      # palette-optimized gif
vidfix format photo.png -o photo.webp   # image conversion
vidfix format clip.mp4 -o thumb.jpg     # first-frame thumbnail
vidfix format clip.mp4 -o audio.mp3     # extract the audio track
vidfix format take.wav -o take.flac     # audio to another audio format

The output extension picks the format — the only option is -o, --output (required). Video targets: mp4, mov, mkv, webm, avi, m4v, ts, mxf, mpg, ogv, flv, wmv, 3gp, gif. Picture targets: png, jpg, webp, bmp, tiff. Audio targets (from a video or another audio file): wav, mp3, m4a, flac, ogg, opus, aac. generate and convert write the same video containers, each with a codec that plays in it.

vidfix variants — variant grids in parallel

vidfix variants in.mp4 --fps 30,60 --res 720p,1080p -o out/
# → variants/in_30fps_720p.mp4, in_30fps_1080p.mp4, in_60fps_720p.mp4, ...

Exit code is 1 if any variant fails. vidfix info takes just the file and --json; vidfix preset list / preset show NAME take no options.

Presets

vidfix preset list
vidfix preset show df30
vidfix generate -o pal.mp4 --preset pal25 --timecode

Built-in broadcast rate family:

Plus broadcast-1080i (25 fps, 1920x1080) and web-720p (30 fps, 720p, h264). With --timecode, DF presets burn semicolon drop-frame notation and NDF/PAL/film presets colon notation, matching broadcast convention. Aliases (alias: pal25) work in user presets too. Add your own in ~/.config/vidfix/presets.yaml; explicit flags always override.

vidfix vs moviepy vs raw FFmpeg

Use moviepy to edit videos, raw ffmpeg for full control, vidfix for exact-spec media, quick conversions, and CI checks with zero setup.

CI usage

- name: Verify rendered output specs
  run: |
    pip install vidfix
    vidfix verify build/output.mp4 --fps 60 --duration 30s --res 1280x720

Development

uv sync                                   # install with dev deps
uv run pytest                             # unit + integration tests
uv run pytest -m "not integration"        # fast tests only
uv run ruff check . && uv run mypy        # lint + strict types

License

MIT — free to use, modify and distribute for any purpose, including commercial use and client work. Keep the copyright notice with any copy you pass on. Contributions are welcome via pull request.