Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

fix(skill): export.py writes limited-range BT.709 video

yzrf45ed519246f
diff --git a/.claude/skills/papermorph/references/core/publish.md b/.claude/skills/papermorph/references/core/publish.md
index a9ea895..376643d 100644
--- a/.claude/skills/papermorph/references/core/publish.md
+++ b/.claude/skills/papermorph/references/core/publish.md
@@ -44,5 +44,5 @@ It renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright st
- A lesson's question beats are left out and its video ends on a card pointing to the interactive lesson. In a film with `CHAPTER.film` they stay: each holds its picture for the beat's `hold` s with the music up at 70 %, as the page plays it while waiting, then the next beat plays as if the reader had acted ([documentary.md](../films/documentary.md#interactive-moments)). A picture book's point-and-read beat (`tapWords`, [picture-books/stories.md](../picture-books/stories.md#point-and-read)) holds instead while it shows each word beside its thing and says it, one every two seconds, with the music ducked under each word, plus a second at the end (a `hold` set on the beat still wins); a word whose clip is missing is named in the run's output and left silent.
- A mix that would clip is turned down as a whole, and the run says by how much; odd sizes are cut to even ones (an upright `--height 720` gives 404 × 720). The video is written beside the old one and renamed when done, so a failed run leaves an earlier `chNN.mp4` alone.
-- Frames are shot by `--jobs` browsers at once (default half the CPU threads, at most 8) on the GPU where there is one, and encoded on the first hardware H.264 encoder that works, else libx264; the run prints which. An 82 s upright short took 45 s on a 20-thread PC with an NVIDIA card, 1 min 22 s there with no GPU and libx264, and 3 min with one browser; `--height 720 --fps 10` makes a quick check copy.
+- Frames are shot by `--jobs` browsers at once (default half the CPU threads, at most 8) on the GPU where there is one, and encoded on the first hardware H.264 encoder that works, else libx264; the run prints which. The video is limited-range BT.709 H.264, tagged so (the frames are full-range JPEGs; a full-range MP4 played too bright in browsers, its paper ground off the page's), so a still from it matches the page. An 82 s upright short took 45 s on a 20-thread PC with an NVIDIA card, 1 min 22 s there with no GPU and libx264, and 3 min with one browser; `--height 720 --fps 10` makes a quick check copy.
- Video files are large (tens of megabytes for a 1080p episode, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
diff --git a/.claude/skills/papermorph/scripts/export.py b/.claude/skills/papermorph/scripts/export.py
index 3bc3526..18eeb3c 100644
--- a/.claude/skills/papermorph/scripts/export.py
+++ b/.claude/skills/papermorph/scripts/export.py
@@ -213,8 +213,15 @@ async def main(a):
codec, opts = encoder()
print(f'encoder {codec}, {a.jobs} browsers', flush=True)
enc = subprocess.Popen(['ffmpeg', '-v', 'error', '-y', '-f', 'image2pipe', '-framerate', str(a.fps), '-c:v', 'mjpeg',
- '-i', '-', '-i', str(wav), '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', # H.264 wants even sizes
- '-c:v', codec, '-pix_fmt', 'yuv420p'] + opts +
+ '-i', '-', '-i', str(wav),
+ # H.264 wants even sizes; the JPEG frames are full range, and a full-range MP4 plays too
+ # bright in some browsers: convert to limited range BT.709 and tag it so
+ '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2:in_range=pc:in_color_matrix=bt601'
+ ':out_range=tv:out_color_matrix=bt709,format=yuv420p',
+ '-c:v', codec, '-pix_fmt', 'yuv420p', '-color_range', 'tv', '-colorspace', 'bt709',
+ '-color_primaries', 'bt709', '-color_trc', 'bt709', # hardware encoders drop these, so also:
+ '-bsf:v', 'h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1'
+ ':video_full_range_flag=0'] + opts +
['-c:a', 'aac', '-b:a', '160k', '-shortest', str(part)],
stdin=subprocess.PIPE)
pages, more = [pg], []