Skip to main content

Get started

MMRecode is distributed as a Cargo application. You need a working Rust toolchain with Cargo available.

Install MMRecode​

Install the current release from crates.io:

cargo install mmrecode

After installation, the mmrecode command is available from your Cargo binary directory. The default build enables wgpu composition and automatically falls back to the CPU compositor when no compatible adapter is available.

For a deliberately CPU-only compatibility build:

cargo install mmrecode --no-default-features

The default GPU path uses a three-slot asynchronous wgpu readback ring for video-plus-MMFX monitor frames. Scene evaluation, decoded-frame conversion, and final terminal transfer are still CPU operations.

mmrecode --help

Choose a terminal​

MMRecode is a full-screen terminal editor, not a command that launches a separate GUI. For the richest moving-video preview, use Kitty or Ghostty; both support the Kitty graphics protocol used by MMRecode's direct RGB preview path.

MMRecode detects terminal capabilities automatically:

  • Kitty and Ghostty: direct Kitty graphics.
  • iTerm2: native inline images.
  • Sixel-capable terminals: Sixel image output.
  • Other true-color terminals: portable 24-bit Unicode half-block rendering.

The fallback keeps the editor usable in terminals without an image protocol, although native image protocols provide the clearest and most efficient preview.

Inspect a media file​

The inspect command recognizes the format and reports typed structure:

mmrecode inspect input.jpg
mmrecode inspect input.m2v

Decode MPEG-2 Video​

Decode a checked-in elementary stream to YUV4MPEG2:

mmrecode decode input.m2v output.y4m

Open the terminal editor​

Run the application without a subcommand:

mmrecode

The editor opens with an Untitled project. Its command prompt and visual workspace are available before media is imported.

Untitled > import projects/output.ts as Clip0
Untitled > save as MyFilm

Use help for the concise vocabulary and man <command> for detailed command help.

Press Tab until the timeline is focused, then use Space to play or pause the complete project. One project clock crosses sequential MPEG-2/H.264 clips, black gaps, and MMFX scenes. Opened clip decoders are reused and the next cut is pre-rolled so playback does not synchronously reopen media at each edit. The clock and keyboard remain responsive when rendering is late: preview work drops obsolete images instead of slowing time. The monitor title reports measured view/decode frame rates and conversion/send latency. Terminal images use a bounded proxy—up to 960×540 with Kitty and 800×450 with fallback protocols—while export always uses the project’s full resolution. Kitty sessions use the compatible temporary-file transfer path by default. Experimental POSIX shared-memory transfer can be enabled with MMRECODE_KITTY_SHM=1 for protocol testing, but should not be used as the normal editor path until capability negotiation is implemented.

Preview supported media​

mmrecode preview input.ts

Terminal preview selects Kitty graphics, Sixel, iTerm2 images, or a portable 24-bit half-block renderer according to terminal capability. The monitor reports the selected delivery protocol.

Render an MMFX scene​

mmrecode render-mmfx lower-third.mmfx output.png
mmrecode render-mmfx motion-layout.mmfx frame-23.png --frame 23 --frames 60

The command renders through the typed parser, deterministic font/image resource handling, text shaping, layout, exact local-frame animation, vector coverage, and linear-light CPU compositor. See the Scene language reference and rendered examples.

Current expectations​

MMRecode is under active development and its capabilities continue to grow quickly. See Project status for current format coverage. Contributors can find the source and development instructions in the GitHub repository.