Skip to main content
Export a replay to 60fps MP4 video with in-game audio using ffmpeg.

​
Usage

crimson replay render <replay_file> [OPTIONS]

​
Arguments

​
replay_file
Path
required
Replay file path (.crd).If a filename is provided without path, also searches base-dir/replays/

​
Options

​
--out
Path
Output video path.Default: <replay>.render.mp4Alias: -o
​
--width
int
Render width in pixels.Default: Use value from crimson.cfg
​
--height
int
Render height in pixels.Default: Use value from crimson.cfg
​
--fps
int
default:"60"
Output video frame rate.Must be ≥ 1.
​
--max-ticks
int
Stop after N ticks.Default: Full replayUseful for rendering highlights or testing.
​
--trace-rng
flag
Enable replay RNG trace mode during simulation.
​
--ffmpeg-bin
Path
ffmpeg executable path.Default: Discover from PATH
​
--crf
int
default:"16"
ffmpeg quality factor (libx264).
  • Lower = higher quality
  • Range: 0-51
  • Recommended: 16-23
  • Default: 16 (high quality)
​
--preset
string
default:"slow"
ffmpeg libx264 encoding preset.Options:
  • ultrafast — Fastest, largest file
  • superfast
  • veryfast
  • faster
  • fast
  • medium
  • slow — Default (good quality/size balance)
  • slower
  • veryslow — Slowest, smallest file
​
--pixel-format
string
default:"yuv420p"
ffmpeg output pixel format.Default: yuv420p (widest compatibility)
​
--overwrite
flag
Overwrite output if it already exists.Default: Fail if output exists
​
--audio
flag
default:"true"
Include in-game audio in output video.Use --mute-audio to disable.
​
--base-dir
Path
Base path for runtime files.Default: Per-user OS data directory
​
--runtime-dir
Path
Alias for --base-dir.
​
--assets-dir
Path
Assets root directory.Default: base-dirMissing .paq files are automatically downloaded.

​
Output

​
Progress Display

crimson replay render run.crd
Output: 
replay video: 100%|██████████| 36000/36000 [02:15<00:00, 265.43tick/s, frames=36000]
replay audio: 100%|██████████| 36000/36000 [00:45<00:00, 800.00tick/s]
ok: output=run.render.mp4 frames=36000 fps=60 resolution=1024x768 ticks=36000 elapsed_ms=600000 score_xp=125000 kills=1200

​
Success Message

Reports:
  • Output path
  • Frame count
  • FPS
  • Resolution
  • Replay statistics

​
Examples

​
Basic Render

crimson replay render survival-run.crd
# Creates: survival-run.render.mp4

​
Custom Output Path

crimson replay render run.crd --out highlight.mp4

​
High Quality 1080p

crimson replay render run.crd \
  --width 1920 \
  --height 1080 \
  --crf 18 \
  --preset slow

​
Fast Preview

crimson replay render run.crd \
  --crf 28 \
  --preset ultrafast \
  --max-ticks 6000  # First 100 seconds

​
Mute Audio

crimson replay render run.crd --mute-audio

​
Overwrite Existing

crimson replay render run.crd --overwrite

​
Custom ffmpeg Binary

crimson replay render run.crd --ffmpeg-bin /usr/local/bin/ffmpeg

​
4K High Quality

crimson replay render run.crd \
  --width 3840 \
  --height 2160 \
  --crf 20 \
  --preset veryslow

​
Encoding Quality

​
CRF Values

​
crf=0
lossless
Mathematically lossless (huge file size).
​
crf=16
high quality
Default. Near-perfect quality, reasonable size.
​
crf=20
good quality
Excellent quality, smaller size.
​
crf=23
balanced
ffmpeg default. Good quality/size balance.
​
crf=28
preview
Lower quality, fast encoding.
​
crf=35+
low quality
Visible artifacts, not recommended.

​
Preset Speed vs Quality

PresetEncoding SpeedFile SizeQuality
ultrafastVery fastLargeLower
fastFastMediumGood
mediumModerateMediumGood
slowSlowSmallHigh
veryslowVery slowSmallestHighest

​
Rendering Process

  1. Simulation — Headless simulation to pre-compute audio
  2. Video Pass — Render frames and pipe to ffmpeg
  3. Audio Pass — Encode audio stream
  4. Muxing — Combine video + audio into final MP4

​
Performance

Rendering speed depends on:
  • Hardware (CPU, GPU)
  • Resolution
  • ffmpeg preset
  • Replay complexity
Typical speeds:
  • ultrafast: 2-5x realtime
  • slow: 0.5-1x realtime
  • veryslow: 0.2-0.5x realtime
Example: 10-minute replay at slow preset takes ~10-20 minutes.

​
Audio Rendering

Audio includes:
  • Weapon sounds
  • Enemy sounds
  • Pickup sounds
  • Music (if enabled in game)
  • UI sounds
Audio is synchronized frame-perfectly with video.

​
Disable Audio

crimson replay render run.crd --mute-audio
# Video-only output

​
Error Handling

​
File Not Found

crimson replay render missing.crd
Output: 
replay file not found: ./missing.crd
Exit code: 1

​
Output Exists

crimson replay render run.crd --out existing.mp4
Output: 
replay render failed: output file exists: existing.mp4 (use --overwrite)
Exit code: 1

​
ffmpeg Not Found

crimson replay render run.crd
Output: 
replay render failed: ffmpeg not found in PATH
Exit code: 1 Install ffmpeg: 
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
winget install ffmpeg

​
File Size

Typical sizes for 10-minute 1080p replay:
CRFPresetSize
16slow~400MB
20slow~250MB
23medium~180MB
28fast~100MB
Higher resolutions increase size proportionally.

​
Use Cases

​
YouTube Upload

crimson replay render run.crd \
  --width 1920 \
  --height 1080 \
  --crf 18 \
  --preset slow \
  --out youtube-upload.mp4

​
Speedrun Submission

crimson replay render speedrun.crd \
  --crf 20 \
  --preset slow \
  --out proof.mp4

​
Twitter/Social Media

crimson replay render highlight.crd \
  --max-ticks 1800 \
  --crf 23 \
  --preset fast \
  --out twitter.mp4

​
Archival Quality

crimson replay render historic.crd \
  --crf 0 \
  --preset veryslow \
  --out lossless-archive.mp4

​
Dependencies

Requires:
  • ffmpeg — Video encoding
  • libx264 — H.264 codec (usually bundled with ffmpeg)
Verify installation: 
ffmpeg -version

​
Pixel Format Compatibility

Default yuv420p provides maximum compatibility:
  • Web browsers
  • Mobile devices
  • Video platforms (YouTube, Twitch)
  • Media players
For HDR or advanced use cases, use yuv444p or yuv420p10le.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us