datamosh

A programmatic datamoshing toolkit. It changes video at the raw AVI byte level without decoding: duplicated P-frames, deleted keyframes, reordered motion, corrupted macroblocks, and loop-stretched audio. Additional decode-required chroma subsampling and pixel sorting effects take a moshable .AVI as input and output, enabling them to be inserted anywhere in the chain. Effects are based on seeded, tunable randomness: a mosh run with identical inputs and the same seed will produce byte-identical results.

Cuts from a mosh made with this toolkit — click for the full video.

Three ways to use it, from easiest to most flexible:

1. The browser UI — sliders, presets, a drag timeline, and a preview player.
2. Recipes — small scripts you copy and tweak (see recipes/README.md).
3. The datamosh package — import the core functions and build your own pipelines.

For people who aren't smelly nerds and just want the .exe

Grab datamosh-setup-<version>.exe from the latest release and run it — no Python, no ffmpeg (a GPL build is bundled, license included), no admin rights (it installs per-user). Renders, media, and presets live in Videos\datamosh.

The installer isn't code-signed yet, so SmartScreen may warn on first run — click More info → Run anyway.

Everything below is for the CLI, the library, and other operating systems.

Setup (once)

Requirements: Python 3.10+, and ffmpeg on your PATH:

Then, from a clone of this repo:

# Windows
py -m venv .venv
.venv\Scripts\pip install -e ".[ui]"

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -e ".[ui]"

[ui] pulls in Gradio for the browser UI; leave it off for the library/CLI only.

Use

(Activate the venv first — .venv\Scripts\activate on Windows, source .venv/bin/activate elsewhere — or prefix commands with the venv path.)

Browser UI

datamosh-ui        # or: python app.py

then open http://127.0.0.1:7860:

To run in a native window instead of a browser tab install the [window] extra (pip install -e ".[window,dev]") and run datamosh-ui --window.

Command line (every knob is a flag; --help lists them all):

datamosh --source media/sample.avi --n 10 --seed 5
datamosh --preset "heavy bloom" --source media/sample.avi

Two extra verbs close the scripting loop: prepare pre-encodes a moshable AVI once (skipping the slow re-encode on every run), and inspect lists its keyframe sections — the (avi, index) entries a MoshScript addresses:

datamosh prepare media/sample.avi --gap 0.5 1.0 --seed 5
datamosh inspect output/sample_moshable.avi          # add --json for machines

Sharing your mosh — moshed AVIs confuse most players, so export turns one into an mp4, webm, or gif. It decodes the corrupt bytes directly: the export is a faithful recording of how ffmpeg plays the glitches.

datamosh export output/run.avi                       # mp4 next to the source
datamosh export output/run.avi --to gif --width 480  # looping gif
datamosh export output/run.avi clip.webm --start 4 --duration 6

Recipe (the copy-and-tweak workflow — start here if you want scripts):

python recipes/basic_mosh.py

Scripted (the deterministic timeline — exact sections, exact ops, same bytes every run):

python recipes/scripted_mosh.py

Project layout

datamosh/       the core package (parsing, effects, scene maps, pipeline, script, config)
datamosh/ui/    the Gradio UI package (needs the [ui] extra)
recipes/        copy-and-tweak example scripts
docs/           deeper docs: how the core works, how to write recipes
tests/          pytest suite (fixtures are generated -- no media in the repo)
app.py          `python app.py` shim for the UI (same as datamosh-ui)
mosh.py         `python mosh.py` shim for the CLI (same as datamosh)
media/          put source videos here (gitignored)
output/         every render, preview, and cache lands here (gitignored)

Key ideas:

• MoshConfig is the whole recipe. One object holds everything a render needs — source, output, and every effect knob. run_mosh(cfg) is the entire call. List every knob: python -c "import datamosh; datamosh.describe()"
• Same seed = same result. Fix the seed to iterate on the other knobs; change it to reroll. MoshScript goes further: per-op randomness is derived by hashing, so a saved script reproduces byte-identically.
• Any input format works. Sources are re-encoded to a canonical moshable AVI (MPEG-4 ASP, single keyframe, AC3 audio) before the byte surgery; only the mosh path itself is AVI-specific.
• First run on a new source is slow — a one-time scene-detection pass, cached in output/cache/ — then every later run is fast.
• Adding a tunable to datamosh/config.py automatically gives it a CLI flag and a UI slider; the bounds/help text live on the config field.
• The library is silent by default. It logs through the logging module (logger "datamosh"); scripts call datamosh.enable_console_logging() for the friendly per-clip render lines (every bundled recipe does), and embedders route logging.getLogger("datamosh") however they like. Long operations accept a progress(frac, msg) callback.

Going deeper:

• docs/core.md — how the core actually works: the chunk-list data model, what every module does, and the seed-reproducibility rules.
• docs/recipes.md — the recipe-writing guide, from a one-config script up to multi-pass splicing pipelines.

Contributing

Bug reports, effect ideas, and pull requests are welcome — see CONTRIBUTING.md for the dev setup and the two ground rules (effects must be rng-seedable, and the moshable-AVI shape is a contract).

License

MIT