Tags: music

Apply a refined cinematic / Fuji-inspired color grade to video files using presets or custom parameters.

Requirements

• Python 3.11+ (uses built-in tomllib; tested on 3.14)
• FFmpeg (required for H.264 encoding + audio preservation)
  • macOS: brew install ffmpeg
  • Linux: apt install ffmpeg or pacman -S ffmpeg
  • Windows: ffmpeg.org

Features

• Preset system — Save and reuse grading configurations in presets.toml
• Soft film-like contrast (S-curve)
• Natural warmth with selective cool-tone desaturation
• Elliptical vignette
• Optional real .cube 3D LUT support
• Automatic H.264 encoding + audio preservation (via FFmpeg)
• Simple CLI with short alias support

Install

cd cinematic-grade
uv sync

Optional short alias (add to ~/.zshrc or ~/.bashrc):

alias cg='cinematic-grade'
# or if you prefer staying with uv run:
# alias cg='uv run cinematic-grade'

Quick Start

List Available Presets

cg --list-presets
# or
uv run cinematic-grade --list-presets

Use a Preset

# Default preset is "subtle" (soft lifestyle look)
cg input.mp4 output.mp4

# Explicit presets
cg input.mp4 output.mp4 --preset subtle
cg input.mp4 output.mp4 --preset warm
cg input.mp4 output.mp4 --preset chris
cg input.mp4 output.mp4 --preset strong
cg input.mp4 output.mp4 --preset movie

Override Preset Parameters

# Use warm preset but boost saturation
cg input.mp4 output.mp4 --preset warm --saturation 1.20

# Use strong preset but reduce LUT strength
cg input.mp4 output.mp4 --preset strong --lut-strength 0.50

Presets

Presets are defined in presets.toml.
Main LUT: classic_chrome_sRGB.cube (Fujifilm Classic Chrome)
Default preset: subtle

Recommended Starting Points

# Soft lifestyle / travel footage (default)
cg input.mp4 output.mp4

# Warm intimate (guitar, cozy rooms, soft light)
cg input.mp4 output.mp4 --preset chris

# General cinematic
cg input.mp4 output.mp4 --preset warm

# Heavier film look
cg input.mp4 output.mp4 --preset strong

Usage Without / Beyond Presets

# Full custom grade
cg input.mp4 output.mp4 \
  --lut classic_chrome_sRGB.cube \
  --lut-strength 0.45 \
  --warmth 1.13 \
  --saturation 1.12 \
  --contrast 1.06 \
  --black-lift 0.07 \
  --vignette 0.09 \
  --cool-desat 0.08

Parameter Reference

Processing Order

1. LUT (base look)
2. Black lift
3. Contrast (S-curve)
4. Warmth
5. Saturation + cool desaturation
6. Vignette

The numeric controls (warmth, contrast, etc.) fine-tune the result after the LUT is applied.

Audio Normalization

Every export runs a two-pass loudnorm by default:

1. Measure — ffmpeg analyzes the source audio’s integrated loudness, true peak, and loudness range (EBU R128).
2. Apply — those measured values are fed back in with linear=true, producing a single flat gain adjustment rather than a dynamic, sample-by-sample one.

This brings clips to a consistent, comparable loudness across a project without pumping/ducking during quiet vs. loud passages — the recorded dynamics and tonal character are preserved, just leveled.

# Default: normalize to -12 LUFS, 256k AAC
cg guitar_take.mp4 output.mp4 --preset chris

# Louder target, tighter true-peak ceiling
cg guitar_take.mp4 output.mp4 --preset chris --loudness-target -14 --true-peak -1.0

# Skip normalization entirely, keep original levels
cg guitar_take.mp4 output.mp4 --preset chris --no-normalize

Note: two-pass loudnorm only stays purely linear if the correction needed is modest. If a source clip is unusually quiet or has very large dynamic swings, ffmpeg may fall back to its dynamic algorithm for that clip even with linear=true on. There’s no clean way to detect this from the exit code — if a specific clip’s audio sounds off after normalization, this is the first thing to check.

LUTs

Additional Fuji LUTs:
https://github.com/abpy/FujifilmCameraProfiles/tree/master/cube%20lut
(use the *_sRGB.cube versions)

Creating Custom Presets

Edit presets.toml and add a new section:

[presets.my_look]
description = "Custom grade"
lut = "classic_chrome_sRGB.cube"
lut_strength = 0.55
warmth = 1.13
saturation = 1.15
contrast = 1.09
black_lift = 0.05
vignette = 0.10
cool_desat = 0.10

Then use it:

cg input.mp4 output.mp4 --preset my_look

Batch Processing

#!/bin/bash
PRESET=${1:-subtle}
OUTPUT_DIR=${2:-./graded}

mkdir -p "$OUTPUT_DIR"

for video in *.mp4; do
  echo "Grading: $video"
  cg "$video" "$OUTPUT_DIR/${video%.mp4}_graded.mp4" --preset "$PRESET"
done

chmod +x batch_grade.sh
./batch_grade.sh              # uses default (subtle)
./batch_grade.sh chris        # warm intimate
./batch_grade.sh warm         # warmer cinematic
./batch_grade.sh strong       # stronger film look

Technical Notes

• Output format: Final file is H.264 + AAC with +faststart (immediately playable in most players and IDEs).
• Audio preservation: Original audio is muxed automatically when FFmpeg is available.
• Intermediate: A temporary silent video is created during processing and deleted afterwards.
• Quality: Default CRF 18 (good balance of quality vs file size). Lower CRF = higher quality / larger files.

Troubleshooting

Presets not loading

• Make sure presets.toml is in the project root
• Run cg --list-presets to verify

Audio missing / unplayable file

• Install FFmpeg (brew install ffmpeg on macOS)

LUT not found

• Check that the .cube file exists in the project root
• Verify the filename in presets.toml

File Structure

cinematic-grade/
├── pyproject.toml
├── presets.toml
├── classic_chrome_sRGB.cube   # Main LUT
├── eterna_sRGB.cube
├── provia_sRGB.cube
├── movie_film.cube
├── README.md
└── cinematic_grade/
    ├── __init__.py
    ├── cli.py
    └── grade.py

Also see 2026-07-26: Recording and 2026-07-26: Guitar