Grav1synth

Grain Synth analyzer and editor for AV1 files

Build

• Prerequisites:
  • ffmpeg headers
  • Rust compiler
• Pull the repo
• Run cargo build --release
• Copy the binary from target/release/grav1synth to wherever you want

Usage

grav1synth inspect my_encode.mkv -o grain_file.txt

Reads my_encode.mkv and outputs a film grain table file at grain_file.txt

grav1synth apply my_encode.mkv -o grainy_encode.mkv -g grain_file.txt

Reads my_encode.mkv, applies film grain from grain_file.txt, and outputs the video to grainy_encode.mkv.

grav1synth apply my_encode.mkv -o grainy_encode.mkv --iso 400 --chroma

Reads my_encode.mkv, generates photon-noise-based film grain at the strength given by --iso (up to 4294967295), and outputs the video to grainy_encode.mkv. By default grain is applied to the luma plane only; --chroma enables grain on chroma planes as well.

In both forms, if the input already has film grain headers the command will print a notice and skip processing — add --replace to overwrite existing grain instead. This makes it safe to use in automated workflows where you want to protect videos that already have grain while still applying grain to those that do not.

grav1synth remove my_encode.mkv -o clean_encode.mkv

Reads my_encode.mkv, removes all synthesized film grain, and outputs the video at clean_encode.mkv

grav1synth diff my_source.mkv denoised_source.mkv -o grain_file.txt

Compares my_source.mkv and denoised_source.mkv and generates a film grain table at grain_file.txt based on the difference between them. This will provide the most accurate estimation of source film grain.

Debug Tracing

To enable AV1 bitstream trace header output (similar to FFmpeg's trace_headers bitstream filter), set the RUST_LOG environment variable:

RUST_LOG=trace_headers=debug grav1synth inspect my_encode.mkv -o grain_file.txt

This outputs each parsed OBU field with its bit position, binary representation, and decimal value.

Known Issues

• There have been reports that certain videos will fail to apply film grain properly. This is likely related to aomenc's --keyframe-filtering=2.