Rendering, checking and previewing a project

Read this when you are about to look at, check or render a showtime project; when a render is slow, fails, or looks different from the preview; or when you need the exact flags and outputs of showtime render, check, snap, preview, server and retime.

The loop#

showtime new dom my-video -d 20     # or launch / film / short / data / tutorial; the whole timeline fits 20 s
showtime preview my-video            # player with scrubber and audio; reloads on save
showtime check my-video              # QA gate: fix every error, read every warning
showtime snap my-video               # contact sheet (look at it) or --at 2.5,7 for stills
showtime render my-video --preview   # quick 720p draft
showtime render my-video             # final: showtime-out/<title>-<timestamp>/final.mp4
showtime render my-video --job <job> # final into a job: <job>/final.mp4 (final-2.mp4 on a re-render)
showtime retime my-video -d 30       # change the length later: scenes, poster, mix and cues move together
showtime retime my-video --from-voice my-video/voice/timeline.json   # scene lengths from the narration

Every command has --help with examples, prints the paths it wrote, and takes --json for a machine-readable result. Errors end with a fix: line; add --debug for a stack trace.

showtime render <project>#

A project is a folder with showtime.json and index.html (or pass an .html file / --page).

Encode settings you ship with belong in showtime.json, so every re-render keeps them (flags still win; a draft --preview ignores the block):

"render": {"crf": 22, "x264_preset": "slow", "format": "png", "poster": "none"}

Keys: crf, x264_preset, format, quality, poster, poster_bake, settle, workers, lufs. A final more than twice the size of the previous final in the same folder gets a warning naming the settings that one used. A re-render next to an existing final.mp4 writes final-2.mp4 (an info line, not a warning). Over 20 MB, the summary prints the command for a size-capped copy (showtime deliver exports <file> --targets original --max-mb 20); grain, dust and noisy photo textures cost the most bitrate. A final above about 25 Mb/s (at 1080p) gets a hint too: that is almost always animated film grain (grainFps above 0 in a film look: 240 MB for 30 s), which static grain (grainFps: 0) or crf 18 shrinks.

What happens:

1. The project is served on 127.0.0.1 (random port). One headless Chrome/Edge/Chromium per worker opens the page with the render-mode runtime (virtual clock, seeded randomness, network blocked) and waits for ST.ready().
2. Frames are split into contiguous ranges. Each worker first replays (without capturing) the second before its range, then seeks every frame in order and captures it with the Chrome DevTools screenshot call. Missing or empty frames are captured again; a crashed browser is restarted up to twice, with a screenshot, the DOM and the console saved to work/diagnostics/.
3. One encode: H.264 High, yuv420p, BT.709 matrix with accurate rounding, BT.709/tv tags, no B-frames (first frame never freezes in picky players), keyframe every 2 s, +faststart.
4. Audio, prepared while frames are captured: ST.score rendered offline in its own page, plus the showtime.json audio (a mix spec goes to showtime audio mix; if that module is missing, a built-in mixer handles file tracks with start/offset/gain/fades/loop). Everything is cut to the rendered range, padded/trimmed to the exact video length, brought to the loudness target (plain gain when the peaks allow it, else gain into an oversampled limiter with at most 6 dB of limiting and a warning if the target is out of reach), encoded as AAC 192k in .m4a (keeps the encoder delay, so sync is exact), checked for true peak, and muxed without re-encoding video.
5. Poster: with a poster time, that frame is saved as poster.jpg and copied over frame 0 before the single encode (feeds and chat apps show frame 0), but only when it looks like the opening frame (--poster-bake auto). A poster over an opening that builds from empty would show as a one-frame flash on autoplay and on every loop, so it is not baked and the summary says why. The best default is a hook that is complete at t=0 with "poster": 0; for YouTube and other platforms that take a custom thumbnail, upload poster.jpg instead. Without a poster time, showtime deliver poster picks a sharp, representative frame for poster.jpg (not baked). qa WARNs poster_flash when frame 0 differs sharply from frame 1.
6. The result is probed (frame count, duration) and a report is written.

Output folder:

showtime-out/my-video-20260926-101500/
  final.mp4          (the draft is preview.mp4; .mov/.webm for --alpha; final-2.mp4 on a re-render)
  poster.jpg         (<stem>.poster.jpg for any other name)
  credits.txt        only when the mix or the project's CREDITS.txt/credits.txt lists CC-BY items
                     (<stem>.credits.txt for any other name; also written with -o)
  final.work/        the render's work folder: <stem>.work/ with --job or -o, work/ in a new job folder
    render.json      settings, browser, timings, capture fps, loudness, warnings, ffprobe summary, "log"
    logs/render.log  every ffmpeg command with its stderr, browser page errors, console errors and
                     warnings, blocked requests, HTTP errors >= 400, warnings, the failure stack
    video.mp4 (no audio), audio/{score,mix,combined,master}.wav + master.m4a,
    frames/ (with --keep-frames), diagnostics/ (after failures)

The summary ends with the output, poster, report (render.json) and log paths; after a failed or odd render, read render.log first (debugging-renders.md). A render whose output is under <job>/studio/ (an animatic: -o <job>/studio/media/animatic/<id>.mp4 --preview) is logged as a job event and recorded as the job's animatic, never as its latest preview or final; its work folder goes to <job>/work/renders/<name>.work/, so studio/ holds only media.

showtime check <project>#

Run it before every final render; a video is not ready while it reports errors. It loads the page exactly like the renderer and reports findings with the time they happen and a fix.

Outputs work/check/report.json and work/check/sheet.jpg (the sample frames with timestamps; look at it), and an estimate of the full render time (raised for <video> layers, which decode on every seek, and when the machine is busy). A still hold uses qa's rule (freeze_noise_db in runtime/thresholds.json): a few typed characters or a thin moving line do not count as motion. After layout-only fixes, re-check with --no-timeline (about half the time); run the full check again after timing changes. report.json also lists scenes (name, id, start, end of the top-level clips) and transitions (type, start, dur, from, to); review-pack uses them for per-scene frames. The hold thresholds live in runtime/thresholds.json, shared by check, retime and qa. Exit code 1 on errors (--strict: also on warnings). Useful flags: --samples N (default 9 + the last frame), --at 3.2,7.9, --no-timeline (skip the dense pass: faster), --no-determinism, --dead-air S (default 2.5).

How the determinism probe works: four frames are captured, re-captured after 150 ms of real time, and captured again after being reached in another order through the two previous frames (the way a render worker reaches them). Differences that only touch antialiased edges are reported as raster_noise (info); differences with solid changed areas are errors.

showtime snap <project | video>#

--at 1,2.5 writes work/snap/t0001.000s.png ... (full size; --width 960 to shrink, --format jpg). Each time snaps to the nearest frame; files keep the time you asked for, and the frame shown is printed when it differs (two times on one frame are both written and noted). Without --at it makes work/snap/sheet.jpg from 12 evenly spaced frames plus the last one (--count N, --every 1s, --cols, --thumb). Project stills are pixel-identical to the render. Another page (--page square.html) or size (--size 9:16) writes to work/snap-<page>[-<WxH>]/ (check likewise to work/check-...), so runs never overwrite each other. One still as a named file (a frame from a clip for the page): showtime snap clip.mp4 --at 7.5 --width 1920 -o media/map.jpg (--width also upscales, with a note).

A rendered video works too (a footage edit, the shipped final, an export), decoded with showtime's own ffmpeg: showtime snap <job>/final-3.mp4 --at 12.9,13.0 (output <job>/work/snap/<name>/). Before/after proof for a fix: showtime snap final-3.mp4 --at 4.2,9.5 --compare final-2.mp4 writes compare.jpg with the old frame left and the new one right (--compare also takes a project).

showtime preview <project>#

Serves the project on http://127.0.0.1:4800 (next free port) and opens the player in a Chrome or Edge app window (--browser default for the system browser, --no-open to only print the URL). From a terminal it runs until Ctrl+C; when started by an agent (output not a terminal) it goes to the background and the command returns: --status, --stop. The server answers only on 127.0.0.1 and only with its per-session key: give the user the printed link as is (it ends in k=...); a request without the key gets a 403 that says so, and --status prints the link again. Keyboard and audio: see stage-api.md. The audio mix is built into work/mix.wav first and rebuilt when showtime.json or audio files change.

showtime server <project> [--port N] [--watch] [--json] serves a project without the player (same mounts: /_st/, /_lib/<package>/, /_assets/; byte ranges; local connections only; the printed links carry the session key, --json gives key for the X-Showtime-Key header). Its page URL redirects to the preview player, so it is not a way to capture a static site: use showtime site capture --serve <dir> (capture.md); on a folder without showtime.json it says so and prints that command.

showtime retime <project> -d <seconds>#

Changes a project's length and moves the whole timeline with it; showtime new ... --duration N runs the same step. Scenes are the top-level clips (data-start/data-dur not inside another clip). Longer: each scene is stretched by new/old and everything inside a scene (component data-at, sound effects, voice lines, caption words, the poster) keeps its offset from the scene start, so animations keep their speed and scenes hold longer. Shorter: everything scales, including times inside scenes. audio/mix.json music sections follow the scene starts (a bed that ran to the end still does); canvas projects scale every number in the var CUE = {...} table (except cps) and adjust bpm so cues stay on bar lines. Files are edited in place: --dry-run (-n) prints the changes first, --json the report. A library or user music file that is too short gets a note: add "fit": true to its track. Never retime one scene by hand and leave the rest.

A scene stretched more than 1.5x gets a warning: it now holds still after its last animation (check flags holds of 2.5 s or more), so give it another beat or motion; canvas cue tables warn too, since everything runs slower. Retimed transitions never shrink below 0.35 s.

--from-voice <timeline.json> (from showtime voice script; the voice/ folder works too) sets the scene lengths from the narration instead of one length for all:

• Lines are matched to scenes by id (the line ## demo narrates <section id="demo">), else in order, else by --map hook=open,demo=bars (or a JSON file {"line": "scene"}); lines left out of the map join the scene of the line before them.
• Each narrated scene lasts --pad (default 0.3 s of picture before its first line) plus the slots of its lines (a slot runs to the next line's start, so it includes the pause). Scenes after the narration (an end card) keep their length; a scene with no line between narrated scenes is an error. --total 30 keeps the video 30 s long: the end card after the narration grows or shrinks to absorb the difference (a warning under 2.5 s, an error under 1 s), so you never hand-edit its data-dur. The report counts only values that really changed.
• Every line becomes its own voice track in audio/mix.json (vo-<id>, file voice/lines/NN-id.wav) at scene start + pad; music without ducking gets "duck": {"under": "voice"}; music sections, sound effects and the poster move with their scenes. A project without a mix gets audio/mix.json.
• It writes voice/captions.words.json (word times in the video) and points top-level caption layers at it with data-at="0" (--keep-captions leaves them alone).
• DOM projects only: canvas films keep their times in the cue table (copy the slot starts there).
• Re-running with the same timeline changes nothing; --dry-run shows the plan.

Speed#

Measured on a 6-core Intel i5-8500 (2018) with Chrome 154 and a Radeon Pro 570X, while other jobs were running:

Rules of thumb:

• A final render takes about 1-2x the video length at 1080p on a mid-range laptop. showtime check prints an estimate for the current project.
• Keep JPEG capture (default). PNG is only needed for --alpha (automatic) or pixel diffs.
• 2-3 workers is the sweet spot on 4-8 cores; more workers fight over the CPU and the GPU.
• --preview saves encode time and file size, not capture time: Chrome still draws each frame at full size. For a fast first look use showtime snap (seconds) and showtime preview (real time).
• What is slow to draw: backdrop-filter, large filter: blur() (above ~20px), many large box-shadows or masks, full-screen gradients with blur on top, thousands of DOM nodes, heavy WebGL shaders. check flags pages with many heavy effects. Blur a small layer and scale it up instead of blurring a full-screen one.
• Animate transform and opacity; they are cheap and smooth. Animating layout properties (width, top, font-size...) forces layout every frame and moves in whole pixels.
• Fonts: load them from /_lib/@fontsource/<family>/... or /_lib/@fontsource-variable/<family>/... (installed by setup), or from @font-face files in the project. Never rely on system fonts or web font URLs; check shows which fonts actually painted the text.
• Long videos: renders keep one browser per worker for the whole range; for videos longer than ~10 minutes, render in sections with --from/--to and join them with the editing tools.

Troubleshooting#

Platforms#

Works the same on macOS (Apple Silicon and Intel), Windows 10/11 and Linux: the scripts are Node, all processes are started with argument lists, paths go through path/pathlib, and ffmpeg is always the one resolved by showtime ($SHOWTIME_FFMPEG, then ~/.showtime/bin/ffmpeg(.exe), then a working one on PATH). The browser is the system Chrome, then Edge, then Chromium (version 120 or newer), then the Chrome Headless Shell that showtime setup installs when none is found (headless runs), then a full Chromium (showtime setup --with chromium, fetched automatically for --headed captures). Override with SHOWTIME_CHROME=/path; SHOWTIME_SYSTEM_BROWSER=0 ignores installed browsers. The headless shell draws the same frames as Chrome except the antialiasing of small text edges (bit-identical on the dom, data and short templates; 37-45 dB PSNR, under 1% of pixels, on the text-heavy film and tutorial templates, measured 2026-09-28); SHOWTIME_HEADLESS_SHELL=0 renders with full Chromium instead. GPU drawing uses Metal on macOS, Direct3D 11 on Windows and the default GL (SwiftShader fallback) on Linux; if the GPU path fails to start, rendering retries in software. Pixels can differ slightly between machines and GPUs (antialiasing), never in timing or layout.

View or edit this page on GitHub