ReMapping — rendering productions and configuring outputs

How to inspect, preview, render, verify and configure productions in the ReMapping folder. Every command below assumes you start in the project root:

cd /Users/ramiyarheydari/Documents/Remapping

In one line. Work down the pipeline in order — validate → film inspect → still → preview → draft → render → verify. Everything from still onwards writes files; everything before it only reports.

What a production contains

Each production is a self-contained film folder:

productions/reference/
├── production.toml      # Production and output settings
├── src/film.py          # Film, scenes, animation, narration scripts
├── assets/              # Imported media: audio, images, video, etc.
├── takes/               # Recorded narration takes
├── voice/lexicon.toml   # Pronunciation choices
├── outputs/             # Delivered video, subtitles, manifests, stems, logs
└── .remapping/jobs/     # Render jobs and checkpoints

The production folder is the argument to every command:

uv run remapping <command> productions/reference

Inspect before rendering

Validate the production

uv run remapping production validate productions/reference

Checks that production.toml, the film entry point, the media declarations and the production rules are valid. Run this first when a production is new or after changing configuration.

List the film structure

uv run remapping film list productions/reference

Shows sequences and scenes — the way to find the scene IDs used by targeted stills and renders.

Inspect the planned film

uv run remapping film inspect productions/reference

Shows planned scene durations, frame ranges, transitions and narration state. This is the best pre-render check when you want to understand what the film will actually produce.

Plan without rendering

uv run remapping plan productions/reference

Validates and writes a FilmPlan without creating video frames — it catches planning problems early, before any render time is spent.

Render one still image first

A still is the fastest way to check composition, typography, safe areas and one specific moment.

uv run remapping still productions/reference --scene equation --time 8

• --scene equation selects one scene.
• --time 8 renders at eight seconds into that scene.

Three worked examples:

uv run remapping still productions/reference --frame 600

Renders one image from the complete reference film at global frame 600. At the reference film's 60 fps authoring rate that is roughly ten seconds in. Use it when you know the exact frame you want.

uv run remapping still productions/reference --frame 600 --show-safe-area --show-anchors

The same frame with diagnostic overlays: --show-safe-area draws the protected title/text area (confirming important text is not too close to the edge), and --show-anchors draws the named anchor points used by layout and animation. This is a debugging image, not a clean final still.

uv run remapping still productions/reference --time 5 --output check.png

Renders one image at five seconds into the film and names the file check.png. Use --time when elapsed time is easier to think in than frame counts. The output goes to the production's output area unless another allowed path is supplied.

The three render modes

Preview — fastest visual check

uv run remapping preview productions/reference
uv run remapping preview productions/reference --output first-look.mp4

A quick, non-certified diagnostic movie using preview-540p30, one worker, and the default filename.

Draft — a complete review version

uv run remapping draft productions/reference

A non-certified, low-cost full-film review version using review-1080p30.

Render — verified delivery

uv run remapping render productions/reference --draft-timing --workers auto

The full renderer. It plans the film, renders contiguous frame ranges, encodes segments, joins them, mixes audio, verifies the delivered file, and only then writes it to outputs/.

Render command options

uv run remapping render productions/reference [options]

Common examples

Fast 540p diagnostic render:

uv run remapping preview productions/reference

Full reference render with estimated narration timing and separate audio stems:

uv run remapping render productions/reference \
  --draft-timing \
  --workers auto \
  --stems

Render only two scenes for review:

uv run remapping render productions/reference \
  --draft-timing \
  --scene title \
  --scene equation \
  --output selected-scenes.mp4

Render a vertical preview production with its vertical profile:

uv run remapping render productions/three-d-to-two-d \
  --profile vertical-preview-540x960 \
  --draft-timing \
  --workers auto

A final output, after narration is fully recorded and approved:

uv run remapping render productions/reference \
  --profile final-1080p60 \
  --workers auto \
  --stems

Where rendered files go

For the reference production:

productions/reference/outputs/
├── reference.mp4                  # Main delivered video
├── reference.manifest.json        # Exact record of inputs/settings/output
├── reference.srt                  # Subtitle file, when generated
├── stems/                         # Optional separate audio buses
│   ├── reference.narration.wav
│   ├── reference.music.wav
│   ├── reference.sfx.wav
│   ├── reference.generated.wav
│   ├── reference.video.wav
│   └── reference.master.wav
└── logs/                          # Render/report logs

The exact main filename depends on the film ID, the selected profile/container, and --output.

Verify an existing video

uv run remapping verify productions/reference/outputs/reference.mp4

Reads the delivered video and reports duration, codec, size, pixel format, frame rate and audio-stream count.

To check it against a known built-in profile's technical contract:

uv run remapping verify productions/reference/outputs/reference.mp4 \
  --profile final-1080p60

Generate subtitles

uv run remapping subtitles productions/reference

Creates outputs/reference.srt from the narration plan. With no recorded takes it uses planned/estimated timing.

uv run remapping subtitles productions/reference \
  --output captions.srt \
  --profile final-1080p60

Output configuration in production.toml

Every production has a production.toml. In productions/reference/production.toml the base render configuration is:

[render]
profile = "final-1080p60"
design_size = [1920, 1080]
fps = "60"
codec = "h264"
load = 0.2
seed = 0

Design size vs delivery size

These are different concepts, and confusing them is the usual cause of a refused render:

design_size    = [1920, 1080]   → how artwork is authored
output profile = 960 × 540      → fast preview delivery
output profile = 3840 × 2160    → 4K delivery

Output profiles

A profile defines the complete delivery contract: size, frame rate, container, codec, pixel format, colour metadata, bitrate/rate control, audio, and encoder settings.

uv run remapping profile list
uv run remapping profile list --family youtube
uv run remapping profile list --size 2160p --hdr
uv run remapping profile list --codec prores
uv run remapping profile show youtube-2160p60-hdr
uv run remapping profile encoders

• profile list finds available profiles; --family, --size, --hdr and --codec filter it.
• profile show displays every setting in one profile.
• profile encoders reports what this machine can actually encode.

A documented high-frame-rate family does not exist yet — that is implementation request 3.

Create a custom output profile

Define it in the production's production.toml:

[output_profiles.my-delivery]
size = [2560, 1440]
fps = "60"
container = "mp4"
codec = "hevc"
pixel_format = "yuv420p"
colour_primaries = "bt709"
transfer = "bt709"
matrix = "bt709"
range = "limited"
purpose = "1440p web delivery"

[output_profiles.my-delivery.rate_control]
mode = "vbr"
target_bps = 16000000
max_bps = 24000000

[output_profiles.my-delivery.encoder]
preset = "slow"

Then render with it:

uv run remapping render productions/reference \
  --profile my-delivery \
  --draft-timing \
  --workers auto

Jobs, interrupted renders and recovery

Render jobs are saved under .remapping/jobs/.

uv run remapping job list productions/reference
uv run remapping job status productions/reference --job JOB_ID
uv run remapping render productions/reference --resume JOB_ID

• job list lists past and current jobs, and whether each can resume.
• job status shows a job's history, settings, output and errors.
• --resume continues a compatible interrupted job. It refuses if the source inputs or the requested settings have changed — which is the correct behaviour, not an obstacle.

If a render only fails in parallel, test with a single worker:

uv run remapping render productions/reference --draft-timing --workers 1

The recommended workflow

For a production with no final narration takes yet, in order:

uv run remapping production validate productions/reference
uv run remapping film inspect productions/reference
uv run remapping still productions/reference --scene title --time 1
uv run remapping preview productions/reference
uv run remapping draft productions/reference
uv run remapping render productions/reference --draft-timing --workers auto --stems
uv run remapping verify productions/reference/outputs/reference.mp4
uv run remapping subtitles productions/reference

For a final narrated production, add the voice-recording and approval workflow before the last render. A final render requires every narration line to have a current take and the approvals the project demands. The proposed interface for that recording pass is implementation request 1.

Key practical notes