Skip to content

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

fix(skill): documentary scripts after review

yzr88c8ed76e694
diff --git a/.claude/skills/papermorph/scripts/commons.py b/.claude/skills/papermorph/scripts/commons.py
index 9830948..f8c5da0 100644
--- a/.claude/skills/papermorph/scripts/commons.py
+++ b/.claude/skills/papermorph/scripts/commons.py
@@ -8,17 +8,21 @@
python3 commons.py get "File:Title.ogg" m1-folia --audio --out books/<book>/music # the file's extension is added
Only public domain and CC0 are downloaded: the licence (Commons' LicenseShortName) must start with "public domain",
-"cc0" or "pd" (PDM-owner counts), else the script refuses. Each download appends a row to the sources log
-(--sources, default OUT/SOURCES.tsv): file, Commons title (and page), licence. Pictures wider than 1800 px, TIFF,
-DjVu and PDF come as an 1800 px rendering (--page picks a page of a scan); recordings come as the original file.
-Previews skip the licence check: they are for looking, not for the film.
+"cc0" or "pd" (PDM-owner counts), else the script refuses. A file with restrictions (trademarked, personality rights)
+is downloaded with a WARN: free to copy is not free to show a logo or a living person. Each download writes a row to
+the sources log (--sources, default OUT/SOURCES.tsv; a new download of the same name replaces its row): file, Commons
+title (and page), licence, author, file page URL, restrictions. Commons serves only standard widths: JPEG, PNG, GIF and
+WebP up to 1920 px come as the original, wider ones as a 1920 px rendering; SVG, DjVu and PDF come as a 1920 px
+rendering (--page picks a page of a scan), TIFF as the largest standard width it has (1280 px for a 1500 px TIFF).
+The name's extension must be the served one (.png for an SVG; leave it off to have it added). Recordings come as the
+original file. Previews (small thumbs) skip the licence check: they are for looking, not for the film.
Recordings: a composition can be centuries old while a recording of it is still protected. Commons marks some
1950s-60s recordings (Karajan, Walter) public domain under EU rules; in the US they are protected until 2067, so
avoid them. Safe: recordings their performers released (PDM-owner, CC0), Musopen, and US government band recordings
(US Marine Band, Air Force bands).
"""
-import argparse, json, os, re, sys, urllib.parse, urllib.request
+import argparse, html, json, os, re, subprocess, sys, urllib.error, urllib.parse, urllib.request
API = "https://commons.wikimedia.org/w/api.php"
UA = {"User-Agent": "papermorph/1.0 (https://github.com/DozenTwelve/Papermorph)"} # Commons asks for a contact
@@ -30,55 +34,93 @@ def api(**p):
def fetch(url, path, timeout=120):
- with urllib.request.urlopen(urllib.request.Request(url, headers=UA), timeout=timeout) as r, open(path, "wb") as f:
- f.write(r.read())
+ with urllib.request.urlopen(urllib.request.Request(url, headers=UA), timeout=timeout) as r:
+ data = r.read() # all of it first: a broken download leaves no half file
+ with open(path, "wb") as f:
+ f.write(data)
ok = lambda lic: bool(re.match(r"(public domain|cc0|pd)", lic.strip(), re.I))
licence = lambda ii: ii.get("extmetadata", {}).get("LicenseShortName", {}).get("value", "?")
-strip = lambda s: re.sub(r"<[^>]+>", "", s or "")[:70]
-IMG = dict(prop="imageinfo", iiprop="url|size|extmetadata|mime", iiurlwidth=1800)
+meta = lambda ii, k: ii.get("extmetadata", {}).get(k, {}).get("value", "")
+strip = lambda s, n=70: re.sub(r" (?=[,.;:])", "", " ".join(html.unescape(re.sub(r"<[^>]+>", " ", s or "")).split()))[:n]
+IMG = dict(prop="imageinfo", iiprop="url|size|extmetadata|mime", iiurlwidth=1920)
AUD = dict(prop="imageinfo", iiprop="url|size|extmetadata|mime|mediatype")
+RAW = ("image/jpeg", "image/png", "image/gif", "image/webp") # served as the original up to 1920 px
+VECTOR = ("image/svg+xml", "image/vnd.djvu", "application/pdf") # rendered at 1920 px whatever their nominal size
+NOTE = "(a PD composition is not a PD recording: check the performer and year, see --help)"
def search(q, n, audio):
d = api(generator="search", gsrsearch=q + (" filetype:audio" if audio else ""), gsrnamespace=6, gsrlimit=n or (15 if audio else 12), **(AUD if audio else IMG))
- for p in sorted(d.get("query", {}).get("pages", {}).values(), key=lambda p: p.get("index", 0)):
+ pages = [p for p in d.get("query", {}).get("pages", {}).values() if p.get("imageinfo")]
+ if not pages:
+ print("no results")
+ for p in sorted(pages, key=lambda p: p.get("index", 0)):
ii = p["imageinfo"][0]; lic = licence(ii); tag = "OK" if ok(lic) else "XX"
if audio:
- print(f"{tag} {ii.get('duration', 0):6.0f}s [{lic}] {p['title']} | {strip(ii.get('extmetadata', {}).get('Artist', {}).get('value'))}")
+ print(f"{tag} {ii.get('duration', 0):6.0f}s [{lic}] {p['title']} | {strip(meta(ii, 'Artist'))}")
else:
- print(f"{tag} {ii['width']}x{ii['height']} [{lic}] {p['title']}")
+ print(f"{tag} {ii['width']}x{ii['height']} [{lic}] {p['title']}{' (' + meta(ii, 'Restrictions') + ')' if meta(ii, 'Restrictions') else ''}")
if audio:
- print("(a PD composition is not a PD recording: check the performer and year, see --help)", file=sys.stderr)
+ print(NOTE, file=sys.stderr)
def get(title, name, out, sources, page, audio):
- params = AUD if audio else dict(IMG, iiurlparam=f"page{page}-1800px") if page else IMG
+ params = AUD if audio else dict(IMG, iiurlparam=f"page{page}-1920px") if page else IMG
p = next(iter(api(titles=title, **params)["query"]["pages"].values()))
- if "imageinfo" not in p:
+ if not p.get("imageinfo"):
sys.exit(f"no such file: {title}")
- ii = p["imageinfo"][0]; lic = licence(ii)
+ ii = p["imageinfo"][0]; lic = licence(ii); mime = ii.get("mime", "?")
if not ok(lic):
sys.exit(f"REJECT licence {lic}")
+ if audio and ii.get("mediatype") != "AUDIO":
+ sys.exit(f"{title} is {mime}, not a recording")
+ if not audio and not (mime in RAW or mime in VECTOR or mime == "image/tiff"):
+ sys.exit(f"{title} is {mime}, not a picture" + (" (a recording? add --audio)" if ii.get("mediatype") == "AUDIO" else ""))
if audio:
- url = ii["url"]; name += os.path.splitext(urllib.parse.urlparse(url).path)[1]
- else:
- url = ii.get("thumburl") if ii["width"] > 1800 else ii["url"]
- if page or ii["mime"] in ("image/tiff", "image/vnd.djvu", "application/pdf"):
- url = ii["thumburl"]
+ url = ii["url"]
+ elif mime in RAW and ii["width"] <= 1920 and not page:
+ url = ii["url"]
+ elif not ii.get("thumburl"):
+ sys.exit(f"Commons gave no rendering of {title}")
+ else: # the API's thumb width is unreliable (a PDF page came at 500 px): ask for 1920 px where it can be drawn
+ url = ii["thumburl"]
+ if mime in VECTOR:
+ url = re.sub(r"/((?:lossy-|lossless-)?page\d+-)?\d+px-(?=[^/]*$)", r"/\g<1>1920px-", url, 1)
+ ext = os.path.splitext(urllib.parse.urlparse(url).path)[1].lower().replace(".jpeg", ".jpg")
+ base, want = os.path.splitext(name)
+ if audio or not want:
+ name += ext
+ elif want.lower().replace(".jpeg", ".jpg") != ext:
+ sys.exit(f"Commons serves {title} as {ext}: name it {base}{ext}")
+ rights = meta(ii, "Restrictions")
+ if rights:
+ print(f"WARN {title} is restricted ({rights}): the licence covers the copyright only; do not show it as a brand or a person's endorsement", file=sys.stderr)
os.makedirs(out, exist_ok=True)
path = os.path.join(out, name)
fetch(url, path, 300 if audio else 120)
- with open(sources or os.path.join(out, "SOURCES.tsv"), "a", encoding="utf-8") as f:
- f.write(f"{name}\t{p['title']}{f' (page {page})' if page else ''}\t{lic}\n")
- print("saved", path, *([] if audio else [ii["width"], ii["height"]]), lic, url)
+ log = sources or os.path.join(out, "SOURCES.tsv")
+ rows = [l for l in open(log, encoding="utf-8")] if os.path.exists(log) else []
+ rows = [l for l in rows if l.split("\t", 1)[0] != name] # a new download of a name replaces its row
+ rows.append("\t".join([name, p["title"] + (f" (page {page})" if page else ""), lic,
+ strip(meta(ii, "Artist") or meta(ii, "Credit"), 200) or "?", ii.get("descriptionurl", ""), rights]) + "\n")
+ with open(log, "w", encoding="utf-8") as f:
+ f.writelines(rows)
+ if audio:
+ print("saved", path, lic, url); print(NOTE, file=sys.stderr)
+ else: # the saved file's own size (ffprobe reads pictures too)
+ wh = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "stream=width,height", "-of", "csv=p=0:s=x", path],
+ capture_output=True, text=True).stdout.strip()
+ print("saved", path, wh or "?", lic, url)
def preview(titles, out):
os.makedirs(out, exist_ok=True)
for i, t in enumerate(titles):
- ii = next(iter(api(titles=t, prop="imageinfo", iiprop="url", iiurlwidth=700)["query"]["pages"].values()))["imageinfo"][0]
+ ii = (next(iter(api(titles=t, prop="imageinfo", iiprop="url|mime", iiurlwidth=700)["query"]["pages"].values())).get("imageinfo") or [{}])[0]
+ if not ii.get("thumburl") or not (ii["mime"] in RAW or ii["mime"] in VECTOR or ii["mime"] == "image/tiff"):
+ print("no picture:", t, file=sys.stderr); continue
fn = os.path.join(out, f"{i}.jpg"); fetch(ii["thumburl"], fn); print(fn, t)
@@ -89,6 +131,11 @@ g = sub.add_parser("get"); g.add_argument("title"); g.add_argument("name"); g.ad
g.add_argument("--sources", help="sources log (default OUT/SOURCES.tsv)"); g.add_argument("--page"); g.add_argument("--audio", action="store_true")
v = sub.add_parser("preview"); v.add_argument("titles", nargs="+"); v.add_argument("--out", required=True)
a = ap.parse_args()
-if a.cmd == "search": search(a.query, a.n, a.audio)
-elif a.cmd == "get": get(a.title, a.name, a.out, a.sources, a.page, a.audio)
-else: preview(a.titles, a.out)
+try:
+ if a.cmd == "search": search(a.query, a.n, a.audio)
+ elif a.cmd == "get": get(a.title, a.name, a.out, a.sources, a.page, a.audio)
+ else: preview(a.titles, a.out)
+except urllib.error.HTTPError as e:
+ sys.exit("Commons rate limited this; retry later" if e.code == 429 else f"HTTP {e.code} {e.reason}: {e.url}")
+except (urllib.error.URLError, TimeoutError) as e:
+ sys.exit(f"network error: {getattr(e, 'reason', e)}")
diff --git a/.claude/skills/papermorph/scripts/eleven.py b/.claude/skills/papermorph/scripts/eleven.py
index 4ebb52b..e45b0c2 100644
--- a/.claude/skills/papermorph/scripts/eleven.py
+++ b/.claude/skills/papermorph/scripts/eleven.py
@@ -2,29 +2,34 @@
"""Narration with OpenRouter's ElevenLabs voices; marks and caption cues from local word alignment (faster-whisper).
uv run --with faster-whisper --with numpy python eleven.py content/<book>/ch01/narration.en.json site/<book>/ch01/audio/en
- ... [--model elevenlabs/eleven-v4] [--voice george] [--only beat,beat]
+ ... [--model elevenlabs/eleven-v4] [--voice george] [--only beat,beat] [--dry] [--ledger books/<book>/art/costs.tsv]
Same input and output as tts.py: the narration file's beats with [[mark]] tags in, <beat>.mp3 and timings.js
({dur, marks, cues} per beat) out, so the page cannot tell the two apart. The voice and model come from the
narration file ("voice", "model"), else from the flags (default george, eleven-v4); OpenRouter offers 21 preset
-voices. A beat may be {"speaker": name, "text": ...} with the speaker's "voice" under the file's "voices", as in tts.py.
+voices. A beat may be {"speaker": name, "text": ...} with the speaker's "voice" under the file's "voices", as in tts.py,
+and a "sub": a line in another language, whose subtitle is its one caption cue, shown even with captions off (forced);
+Whisper detects that line's language.
ElevenLabs returns no word timings, so each clip is transcribed locally (faster-whisper base.en, or base for another
language, from the file name narration.<lang>.json; the first run downloads the model) and the script's words are
matched to the heard words in order; each [[mark]] is the start of the word after it, and there is one caption cue per
-sentence and per clause after a colon. Audio is decoded with ffmpeg, not PyAV (faster-whisper's PyAV version clashes). Needs ffmpeg.
+sentence and per clause after a colon ("Mr." and "e.g." do not end one, as in tts.py). Audio is decoded with ffmpeg, not PyAV (faster-whisper's PyAV version clashes). Needs ffmpeg.
v4 audio tags such as [cackles] or [whispers] act: they are performed, not read aloud, and left out of captions.
-Price: about $0.00008 per character (about $0.65 for a ten-minute film); the run prints its estimate.
+Price: about $0.00008 per character (about $0.65 for a ten-minute film). Before paying, the run prints the characters
+it will synthesize and their estimated cost; --dry stops there. --ledger appends the run's estimate to the ledger
+paint.py writes (OpenRouter reports no cost for speech).
Each beat's clip is cached beside the narration as .eleven/<beat>.<hash>.mp3 (hash of model, voice and text), so
-moving marks or rerunning never pays twice. --only regenerates the listed beats and leaves the others' mp3 (perhaps
-levelled since) and timings as they are. The key is read from ~/.config/openrouter/key or $OPENROUTER_API_KEY.
+moving marks or rerunning never pays twice. --only takes the listed beats again (a fresh, paid take, even with the
+text unchanged) and leaves the others' mp3 and timings as they are. A clip levelled in place (level.py) is kept by
+later runs until its take changes: .eleven/takes.json records which take each output clip was copied from.
+The key is read from ~/.config/openrouter/key or $OPENROUTER_API_KEY.
"""
-import argparse, hashlib, json, pathlib, re, subprocess, sys, urllib.error, urllib.request
-import numpy as np
+import argparse, datetime, hashlib, json, pathlib, re, subprocess, sys, urllib.error, urllib.request
from paint import key
-from tts import split_marks, mark_times, duration, write_atomic
+from tts import ABBREV, split_marks, mark_times, duration, write_atomic
TAG = re.compile(r"(?<!\[)\[[^\[\]]+\](?!\])") # a v4 audio tag, not a [[mark]]
PRICE = 0.00008 # USD per character
@@ -32,7 +37,9 @@ PRICE = 0.00008 # USD per character
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("narration"); ap.add_argument("out")
ap.add_argument("--model"); ap.add_argument("--voice")
-ap.add_argument("--only", default="", help="comma-separated beats to regenerate")
+ap.add_argument("--only", default="", help="comma-separated beats to take again")
+ap.add_argument("--dry", action="store_true", help="print what would be synthesized and its cost, then stop")
+ap.add_argument("--ledger", help="tab-separated cost log to append the estimate to, e.g. books/<book>/art/costs.tsv")
a = ap.parse_args()
spec = json.loads(pathlib.Path(a.narration).read_text(encoding="utf-8-sig"))
model = a.model or spec.get("model", "elevenlabs/eleven-v4")
@@ -40,53 +47,74 @@ lang = pathlib.Path(a.narration).stem.split(".")[-1]
out = pathlib.Path(a.out); out.mkdir(parents=True, exist_ok=True)
cache = pathlib.Path(a.narration).parent / ".eleven"; cache.mkdir(exist_ok=True)
only = set(filter(None, a.only.split(",")))
+if only - spec["beats"].keys():
+ sys.exit(f"--only: no beat {', '.join(sorted(only - spec['beats'].keys()))}")
def speak(text, voice, dst):
body = json.dumps({"model": model, "input": text, "voice": voice, "response_format": "mp3"}).encode()
+ k = key()
req = urllib.request.Request("https://openrouter.ai/api/v1/audio/speech", body,
- {"Authorization": f"Bearer {key()}", "Content-Type": "application/json"})
+ {"Authorization": f"Bearer {k}", "Content-Type": "application/json"})
try:
data = urllib.request.urlopen(req, timeout=300).read()
except urllib.error.HTTPError as e:
- sys.exit(f"{e.code} {e.read().decode(errors='replace')[:500]}")
+ sys.exit(f"{e.code} {e.read().decode(errors='replace').replace(k, '***')[:500]}")
if not data.startswith(b"ID3") and not (data[:1] == b"\xff" and len(data) > 1 and data[1] & 0xE0 == 0xE0):
sys.exit(f"not audio: {data[:300]!r}")
dst.write_bytes(data)
norm = lambda w: re.sub(r"\W", "", w.lower())
-asr = None
+asr = {}
tf = out / "timings.js"
old = {}
if tf.exists():
t = tf.read_text(encoding="utf-8"); old = json.loads(t[t.index("{"):t.rindex("}") + 1])
-timings, spent = {}, 0
+tk = cache / "takes.json" # output clip -> the cached take it was copied from
+takes = json.loads(tk.read_text()) if tk.exists() else {}
+beats = []
for beat, raw in spec["beats"].items():
voice = spec["voices"][raw["speaker"]]["voice"] if isinstance(raw, dict) else a.voice or spec.get("voice", "george")
+ sub = raw.get("sub") if isinstance(raw, dict) else None # a foreign line's subtitle, its one cue
raw = raw["text"] if isinstance(raw, dict) else raw
clean, marks = split_marks(raw) # clean keeps audio tags: they go to the voice
+ cached = cache / f"{beat}.{hashlib.sha1(f'{model}|{voice}|{clean}'.encode()).hexdigest()[:12]}.mp3"
+ fresh = beat in only if only else not cached.exists() # --only takes its beats again, cached or not
+ beats.append((beat, voice, sub, clean, marks, cached, fresh))
+todo = sum(len(b[3]) for b in beats if b[6])
+print(f"{sum(b[6] for b in beats)} beats to synthesize, {todo} characters, about ${todo * PRICE:.2f}", flush=True)
+if a.dry:
+ sys.exit()
+if a.ledger and todo:
+ led = pathlib.Path(a.ledger); led.parent.mkdir(parents=True, exist_ok=True)
+ with led.open("a", encoding="utf-8") as f: f.write(f"{datetime.date.today()}\t{a.out}\t{model}\ttts{todo}c\t{todo * PRICE:.4f}\n")
+timings, spent = {}, 0
+for beat, voice, sub, clean, marks, cached, fresh in beats:
if only and beat not in only and beat in old:
timings[beat] = old[beat]; continue # --only leaves the other beats alone
- cached = cache / f"{beat}.{hashlib.sha1(f'{model}|{voice}|{clean}'.encode()).hexdigest()[:12]}.mp3"
- if not cached.exists():
- if only and beat not in only:
- continue
+ if not fresh and not cached.exists():
+ print(f"{beat}: WARNING not in {tf} and not cached, left out: run without --only to make it", file=sys.stderr); continue
+ if fresh:
speak(clean, voice, cached); spent += len(clean); print(beat, "synthesized")
- mp3 = out / f"{beat}.mp3"; mp3.write_bytes(cached.read_bytes())
- if asr is None:
+ mp3 = out / f"{beat}.mp3"
+ if fresh or not mp3.exists() or takes.get(str(mp3.resolve())) != cached.name: # else keep it: perhaps levelled since
+ mp3.write_bytes(cached.read_bytes()); takes[str(mp3.resolve())] = cached.name
+ m = "base" if sub or lang != "en" else "base.en"
+ if m not in asr:
+ import numpy as np
from faster_whisper import WhisperModel
- asr = WhisperModel("base.en" if lang == "en" else "base", device="cpu", compute_type="int8")
+ asr[m] = WhisperModel(m, device="cpu", compute_type="int8")
pcm = subprocess.run(["ffmpeg", "-v", "error", "-i", str(mp3), "-f", "f32le", "-ac", "1", "-ar", "16000", "-"],
capture_output=True, check=True).stdout
- segs, _ = asr.transcribe(np.frombuffer(pcm, np.float32), word_timestamps=True, language=lang)
+ segs, _ = asr[m].transcribe(np.frombuffer(pcm, np.float32), word_timestamps=True, language=None if sub else lang)
heard = [(norm(w.word), w.start) for s in segs for w in s.words if norm(w.word)]
# the script's words (audio tags blanked out, positions kept), matched to heard words in order with a small look-ahead
spoken = TAG.sub(lambda m: " " * len(m.group()), clean)
toks = [w for w in re.findall(r"\S+", spoken) if norm(w)]
times, j = [], 0
for w in map(norm, toks):
- k = next((k for k in range(j, min(j + 6, len(heard))) if heard[k][0] == w or heard[k][0].startswith(w[:4])), None)
+ k = next((k for k in range(j, min(j + 6, len(heard))) if heard[k][0] == w or len(w) >= 4 and heard[k][0].startswith(w[:4])), None)
times.append(None if k is None else heard[k][1]); j = j if k is None else k + 1
dur = duration(mp3)
for i, v in enumerate(times): # words Whisper merged or split: halfway between their known neighbours
@@ -96,12 +124,17 @@ for beat, raw in spec["beats"].items():
times[i] = round(prev + (nxt - prev) * .5, 3)
words = list(zip(times, toks))
# caption cues: one per sentence or clause after a colon (long documentary sentences), at its first word
- cues, i = [], 0
- for sent in re.split(r"(?<=[.?!:])\s+", re.sub(r"\s+", " ", TAG.sub("", clean)).strip()):
+ cues, i, sents = [], 0, []
+ for sent in re.split(r"(?<=[.?!:])\s+", re.sub(r"\s+", " ", TAG.sub(" ", clean)).strip()): # a tag parts words
+ if sents and ABBREV.search(sents[-1]): sents[-1] += " " + sent # "Mr. Lee", "e.g. a lot" go on
+ else: sents.append(sent)
+ for sent in sents:
n = len([w for w in sent.split() if norm(w)])
if n: cues.append([round(times[i], 3) if i < len(times) else 0, sent]); i += n
if cues: cues[0][0] = min(cues[0][0], .1)
- timings[beat] = {"dur": dur, "marks": mark_times(clean, marks, words), "cues": cues}
+ timings[beat] = {"dur": dur, "marks": mark_times(clean, marks, words), "cues": [[0, sub]] if sub else cues}
+ if sub: timings[beat]["forced"] = True
print(f"{beat}: {dur} s, {len(marks)} marks")
write_atomic(tf, "window.TIMINGS = " + json.dumps(timings, indent=1, ensure_ascii=False) + ";\n")
+write_atomic(tk, json.dumps(takes, indent=1))
print(f"{len(timings)} beats in {tf}; synthesized {spent} characters, about ${spent * PRICE:.2f}")
diff --git a/.claude/skills/papermorph/scripts/export.py b/.claude/skills/papermorph/scripts/export.py
index 9cbece0..07d0aae 100644
--- a/.claude/skills/papermorph/scripts/export.py
+++ b/.claude/skills/papermorph/scripts/export.py
@@ -6,8 +6,8 @@
The engine draws every frame as a pure function of the beat time, so frames are rendered by seeking, not by
recording playback: the video is exact and the same on every run. The sound is mixed the way the page plays it:
-each beat's clip from its `pre` on, and in a picture book the sfx() effects (cut at the end of their scene, as a
-scene change stops them) and the BGM tracks with their crossfades, ducking and MUSIC_OFF. Question beats (quick
+each beat's clip from its `pre` on, and in a film (a picture book or a documentary) the sfx() effects (cut at the end
+of their scene, as a scene change stops them) and the BGM tracks with their crossfades, ducking and MUSIC_OFF. Question beats (quick
checks and practice) are left out, and then the video ends on a card saying they are in the interactive lesson
(--link adds its address). Captions are not burned in: upload OUT/chNN.srt with the video. Needs ffmpeg; serve the
site over HTTP first.
@@ -80,7 +80,7 @@ async def main(a):
if errs:
sys.exit(f'page errors: {errs}')
info = await pg.evaluate("""({lang: CHAPTER.language || 'en', beats: BEATS.map(b => ({id: b.id, ask: !!b.ask, pre: b.pre || 0})),
- bgm: typeof BGM === 'undefined' ? [] : BGM.map(m => ({src: m.a.src, beats: m.beats, gain: m.gain, fade: m.fade || .8})),
+ bgm: typeof BGM === 'undefined' ? [] : BGM.map(m => ({src: m.a.src, beats: m.beats, gain: m.gain, fade: m.fade ?? .8})),
upInPre: window.MUSIC_UP_IN_PRE || false})""")
beats = [(i, x['id']) for i, x in enumerate(info['beats']) if not x['ask']]
info['sfx'] = []
@@ -132,7 +132,7 @@ async def main(a):
for f in range(n):
bid, t = frames_id[f], frames_t[f]
current = bid in m['beats'] and not frames_off[f]
- v = max(0.0, min(1.0, v + (1 if current else -1) / fps / m['fade']))
+ v = max(0.0, min(1.0, v + (1 if current else -1) / fps / m['fade'])) if m['fade'] > 0 else float(current) # 0: a cut
up = info['upInPre']
want = .7 if up and (up is True or bid in up) and t < beat_pre[bid] else .3
duck += max(-1 / fps, min(1 / fps, want - duck))
diff --git a/.claude/skills/papermorph/scripts/frames.py b/.claude/skills/papermorph/scripts/frames.py
index 1625683..29634f4 100644
--- a/.claude/skills/papermorph/scripts/frames.py
+++ b/.claude/skills/papermorph/scripts/frames.py
@@ -4,12 +4,13 @@
uv run --with pillow --with numpy python frames.py books/<book>/art/video/chained.mp4 chained --out site/<book>/img
... [--fps 12] [--side 560] [--cols 10] [--ink 243,237,224]
-Every frame is scaled to side x side, its paper made transparent and its lines drawn in --ink, then laid out in rows
-of --cols. Writes OUT/<name>-sheet.webp (quality 80) and adds <name>: {fw, fh, cols, n, fps} to OUT/frames.js
+Every frame is scaled to fit side x side with its aspect kept (a 16:9 clip makes 560 x 315 cells), its paper made
+transparent and its lines drawn in --ink, then laid out in rows of --cols. A WebP is at most 16383 px a side, so a sheet
+that would be larger stops the script first, saying how many frames fit. Writes OUT/<name>-sheet.webp (quality 80) and adds <name>: {fw, fh, cols, n, fps} to OUT/frames.js
(window.FRAMES), which the documentary kit's anim() plays on the beat clock. Needs ffmpeg. Keep clips short: a 5 s
clip at 12 fps and 560 px is about 4 MB.
"""
-import argparse, json, pathlib, subprocess
+import argparse, json, math, pathlib, subprocess
import numpy as np
from PIL import Image
from prep import CREAM, ink, rgb
@@ -20,17 +21,29 @@ ap.add_argument("--out", required=True, help="the book's img folder, e.g. site/<
ap.add_argument("--fps", type=int, default=12); ap.add_argument("--side", type=int, default=560); ap.add_argument("--cols", type=int, default=10)
ap.add_argument("--ink", type=rgb, default=CREAM, help="line colour r,g,b")
a = ap.parse_args()
-raw = subprocess.run(["ffmpeg", "-v", "error", "-i", a.src, "-vf", f"fps={a.fps},scale={a.side}:{a.side}", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
- capture_output=True, check=True).stdout
-fr = np.frombuffer(raw, np.uint8).reshape(-1, a.side, a.side, 3)
-n, cols = len(fr), a.cols; rows = -(-n // cols)
-sheet = Image.new("RGBA", (cols * a.side, rows * a.side), tuple(a.ink) + (0,))
+def run(cmd):
+ r = subprocess.run(cmd, capture_output=True)
+ if r.returncode: raise SystemExit(r.stderr.decode(errors="replace").strip() or f"{cmd[0]} failed")
+ return r.stdout
+info = json.loads(run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height:format=duration", "-of", "json", a.src]))
+w, h = info["streams"][0]["width"], info["streams"][0]["height"]
+fw, fh = (a.side, max(1, round(a.side * h / w))) if w >= h else (max(1, round(a.side * w / h)), a.side)
+cols = a.cols
+def fits(n): # a WebP is at most 16383 px a side
+ if cols * fw > 16383: raise SystemExit(f"{cols} columns of {fw} px exceed WebP's 16383 px: use --cols {16383 // fw} or less")
+ if -(-n // cols) * fh > 16383: raise SystemExit(f"{n} frames exceed WebP's 16383 px: at most {cols * (16383 // fh)} fit; shorten the clip or lower --fps or --side")
+fits(math.ceil(float(info["format"]["duration"]) * a.fps))
+raw = run(["ffmpeg", "-v", "error", "-i", a.src, "-vf", f"fps={a.fps},scale={fw}:{fh}", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"])
+fr = np.frombuffer(raw, np.uint8).reshape(-1, fh, fw, 3)
+n = len(fr); fits(n); rows = -(-n // cols)
+sheet = Image.new("RGBA", (cols * fw, rows * fh), tuple(a.ink) + (0,))
for i, f in enumerate(fr):
- sheet.paste(ink(f, a.ink), ((i % cols) * a.side, (i // cols) * a.side))
+ sheet.paste(ink(f, a.ink), ((i % cols) * fw, (i // cols) * fh))
out = pathlib.Path(a.out); out.mkdir(parents=True, exist_ok=True)
dst = out / f"{a.name}-sheet.webp"; sheet.save(dst, quality=80, method=5)
jf = out / "frames.js"
-data = json.loads(jf.read_text().split("=", 1)[1].rstrip().rstrip(";")) if jf.exists() else {}
-data[a.name] = {"fw": a.side, "fh": a.side, "cols": cols, "n": n, "fps": a.fps}
+t = jf.read_text() if jf.exists() else ""
+data = json.loads(t[t.index("{", t.index("window.FRAMES")):t.rindex("}") + 1]) if t else {}
+data[a.name] = {"fw": fw, "fh": fh, "cols": cols, "n": n, "fps": a.fps}
jf.write_text("window.FRAMES = " + json.dumps(data) + ";\n")
print(n, "frames ->", dst, round(dst.stat().st_size / 1e6, 2), "MB")
diff --git a/.claude/skills/papermorph/scripts/prep.py b/.claude/skills/papermorph/scripts/prep.py
index df04cfc..e2a5892 100644
--- a/.claude/skills/papermorph/scripts/prep.py
+++ b/.claude/skills/papermorph/scripts/prep.py
@@ -36,6 +36,8 @@ def ink(rgb, colour=CREAM):
def line(src, side, inset=0, colour=CREAM):
rgba = ink(Image.open(src).convert("RGB"), colour)
box = rgba.getchannel("A").point(lambda v: 255 if v > 40 else 0).getbbox()
+ if not box:
+ return None
if inset: # shave a printed plate mark off the edges of the ink box
dx, dy = int((box[2] - box[0]) * inset), int((box[3] - box[1]) * inset)
box = (box[0] + dx, box[1] + dy, box[2] - dx, box[3] - dy)
@@ -49,7 +51,7 @@ def print_(src, side, paper=CREAM, border=16, pad=40):
g = np.asarray(im.convert("L"), float) # trim a near-black scanner mat at the edges (never more than 6 % a side)
def edge(means):
n, lim = len(means), int(len(means) * .06)
- a = next((i for i in range(lim) if means[i] > 30), 0); b = next((i for i in range(lim) if means[n - 1 - i] > 30), 0)
+ a = next((i for i in range(lim) if means[i] > 30), lim); b = next((i for i in range(lim) if means[n - 1 - i] > 30), lim)
return a, n - b
(y0, y1), (x0, x1) = edge(g.mean(1)), edge(g.mean(0))
im = im.crop((x0, y0, x1, y1))
@@ -79,10 +81,13 @@ def main():
src, out = pathlib.Path(a.src), pathlib.Path(a.out)
out.mkdir(parents=True, exist_ok=True)
jf = out / "art.js"
- sizes = json.loads(jf.read_text().split("=", 1)[1].strip().rstrip(";")) if jf.exists() else {}
+ t = jf.read_text() if jf.exists() else ""
+ sizes = json.loads(t[t.index("{", t.index("window.ART")):t.rindex("}") + 1]) if t else {}
for name, f, mode, side, *rest in json.loads(pathlib.Path(a.list).read_text()):
if mode == "line":
im = line(src / f, side, rest[0] if rest else 0, rest[1] if len(rest) > 1 else a.ink)
+ if im is None:
+ print(f"{name}: WARNING no lines in {f} (is it dark lines on light paper?), skipped"); continue
elif mode == "print":
im = print_(src / f, side, a.paper)
else:
diff --git a/.claude/skills/papermorph/scripts/sfx.py b/.claude/skills/papermorph/scripts/sfx.py
index 4d87bac..fc89531 100644
--- a/.claude/skills/papermorph/scripts/sfx.py
+++ b/.claude/skills/papermorph/scripts/sfx.py
@@ -1,5 +1,5 @@
#!/usr/bin/env python3
-"""Sound effects for a picture book, synthesized with numpy (no samples): named recipes written as mono 44.1 kHz MP3s.
+"""Sound effects for a film, synthesized with numpy (no samples): named recipes written as mono 44.1 kHz MP3s.
uv run --with numpy python sfx.py site/<book>/ch01/audio/sfx knock door rain # these effects, OUT_DIR/<name>.mp3
uv run --with numpy python sfx.py site/<book>/ch01/audio/sfx all # every recipe
@@ -8,8 +8,9 @@
uv run --with numpy python sfx.py --selftest # checks the --recipes loading
Needs ffmpeg. Every file is faded (5 ms) and peak-normalised to -3 dBFS; each recipe is seeded by its name, so a name
-always renders the same sound. Play them from a chapter with sfx(beat, seconds, 'name', volume) (paper-cutout kit,
-shared.js), which plays them at half volume under the voices. Even out voices and effects afterwards with level.py.
+always renders the same sound. Play them from a chapter with sfx(beat, seconds, 'name', volume) (the engine's sfx(), in
+any film: a picture book or a documentary), which plays them at half volume under the voices. Even out voices and
+effects afterwards with level.py.
A book's own recipes: --recipes FILE.py (repeatable) imports FILE; every top-level function in it that takes no
required argument and whose name does not start with _ becomes a recipe (underscores in the name become hyphens; the
diff --git a/.claude/skills/papermorph/scripts/trace.py b/.claude/skills/papermorph/scripts/trace.py
index be49db2..809b252 100644
--- a/.claude/skills/papermorph/scripts/trace.py
+++ b/.claude/skills/papermorph/scripts/trace.py
@@ -23,7 +23,8 @@ ap.add_argument("--lines", help="lines.js to add or replace this drawing's entry
ap.add_argument("--name", help="its key in LINES (default: OUT's file name without .svg)")
a = ap.parse_args()
-im = Image.open(a.src).convert("L")
+src = Image.open(a.src).convert("RGBA") # transparent paper counts as white paper
+im = Image.alpha_composite(Image.new("RGBA", src.size, "white"), src).convert("L")
im = im.resize((a.width, round(im.height * a.width / im.width)), Image.LANCZOS)
ink = np.asarray(im) < 140
sk = skeletonize(ink)
@@ -81,7 +82,7 @@ if a.lines:
head, data = "// centreline traces of line drawings (trace.py)\n", {}
if lf.exists():
t = lf.read_text()
- head, data = t[:t.index("window.LINES")], json.loads(t[t.index("{"):t.rindex("}") + 1])
+ i = t.index("window.LINES"); head, data = t[:i], json.loads(t[t.index("{", i):t.rindex("}") + 1])
data[a.name or pathlib.Path(a.out).stem] = entry
lf.write_text(head + "window.LINES = " + json.dumps(data, separators=(",", ":")) + ";\n")
print(len(data), "drawings in", lf)
diff --git a/.claude/skills/papermorph/scripts/video.py b/.claude/skills/papermorph/scripts/video.py
index 03f9084..2e965c4 100644
--- a/.claude/skills/papermorph/scripts/video.py
+++ b/.claude/skills/papermorph/scripts/video.py
@@ -3,40 +3,55 @@
python3 video.py OUT.mp4 FIRST_FRAME.png "prompt" --model kwaivgi/kling-v3.0-std --ledger books/<book>/art/costs.tsv
... [--duration 5] [--resolution 720p] [--aspect 1:1]
+ ... --resume JOBID # the same command again: poll that job instead of paying for a new one
The still is the first frame; the clip has no sound. Then frames.py turns it into an ink-line sprite sheet, so it
plays on the beat clock like the rest of the film (pause, seek and export match, which a <video> would not).
Kling 3.0 std, 5 s, cost about $0.42 and kept an engraving's style; Veo 3.1 lite refused 1:1. A job takes minutes;
-the script polls every 20 s. The key is read from ~/.config/openrouter/key or $OPENROUTER_API_KEY.
+the script polls every 20 s for up to 15 minutes. A job that ends other than completed stops the script; a timeout or a
+lost connection prints the job id to --resume. The key is read from ~/.config/openrouter/key or $OPENROUTER_API_KEY.
Prints the cost OpenRouter reports and appends a row to the ledger (date, file, model, "video<N>s", cost), the same
ledger paint.py writes, so `python3 paint.py --total LEDGER` sums both.
"""
-import argparse, base64, datetime, json, mimetypes, pathlib, time, urllib.error, urllib.request
+import argparse, base64, datetime, json, mimetypes, pathlib, sys, time, urllib.error, urllib.request
from paint import key
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("out"); ap.add_argument("frame"); ap.add_argument("prompt")
ap.add_argument("--model", required=True); ap.add_argument("--duration", type=int, default=5); ap.add_argument("--resolution", default="720p")
ap.add_argument("--aspect", default="1:1")
+ap.add_argument("--resume", metavar="JOBID", help="poll this job (after a timeout or lost connection) instead of starting a new one")
ap.add_argument("--ledger", required=True, help="tab-separated cost log, e.g. books/<book>/art/costs.tsv")
a = ap.parse_args()
k = key()
H = {"Authorization": f"Bearer {k}", "Content-Type": "application/json"}
+jid = a.resume
+again = lambda: f"; the job may still finish: rerun with --resume {jid}" if jid else ""
def call(url, body=None):
try:
return urllib.request.urlopen(urllib.request.Request(url, json.dumps(body).encode() if body else None, H), timeout=300)
except urllib.error.HTTPError as e:
- raise SystemExit(f"{e.code} {e.read().decode(errors='replace').replace(k, '***')[:500]}")
-img = f"data:{mimetypes.guess_type(a.frame)[0] or 'image/png'};base64," + base64.b64encode(pathlib.Path(a.frame).read_bytes()).decode()
-body = {"model": a.model, "prompt": a.prompt, "duration": a.duration, "resolution": a.resolution, "aspect_ratio": a.aspect,
- "generate_audio": False, "frame_images": [{"type": "image_url", "image_url": {"url": img}, "frame_type": "first_frame"}]}
-jid = json.load(call("https://openrouter.ai/api/v1/videos", body))["id"]; print(a.model, "job", jid, flush=True)
+ raise SystemExit(f"{e.code} {e.read().decode(errors='replace').replace(k, '***')[:500]}{again()}")
+if not jid:
+ img = f"data:{mimetypes.guess_type(a.frame)[0] or 'image/png'};base64," + base64.b64encode(pathlib.Path(a.frame).read_bytes()).decode()
+ body = {"model": a.model, "prompt": a.prompt, "duration": a.duration, "resolution": a.resolution, "aspect_ratio": a.aspect,
+ "generate_audio": False, "frame_images": [{"type": "image_url", "image_url": {"url": img}, "frame_type": "first_frame"}]}
+ jid = json.load(call("https://openrouter.ai/api/v1/videos", body))["id"]
+print(a.model, "job", jid, flush=True)
+t0, fails = time.time(), 0
while True:
time.sleep(20)
- s = json.load(call(f"https://openrouter.ai/api/v1/videos/{jid}"))
- if s["status"] in ("completed", "failed"): break
-if s["status"] == "failed": raise SystemExit(f"failed: {s.get('error')}")
+ try:
+ s = json.load(call(f"https://openrouter.ai/api/v1/videos/{jid}"))
+ except (urllib.error.URLError, TimeoutError, ConnectionError, ValueError) as e: # the connection, not the job
+ fails += 1
+ if fails == 5: raise SystemExit(f"polling failed 5 times ({e}){again()}")
+ print("poll failed, retrying:", e, file=sys.stderr); continue
+ fails = 0
+ if s.get("status") in ("completed", "failed", "cancelled", "expired"): break
+ if time.time() - t0 > 900: raise SystemExit(f"still {s.get('status')} after 15 minutes{again()}")
+if s["status"] != "completed": raise SystemExit(f"{s['status']}: {s.get('error')}")
out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)
out.write_bytes(call(f"https://openrouter.ai/api/v1/videos/{jid}/content?index=0").read())
cost = (s.get("usage") or {}).get("cost", 0) or 0