Skip to content

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

feat(skill): CHROME browser choice, OpenAI painting, key redaction (#15)

Yuya Shimboria595b4b3066d
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index 3687595..b1c022f 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -37,7 +37,7 @@ site/<book>/ the static book (only this is delivered)
A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`); its `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`.
-`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`) and Playwright browsers (`uv run --with playwright playwright install chromium firefox`). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
+`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`) and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
## Pipeline
diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.md
index 994e7af..e8e668b 100644
--- a/.claude/skills/papermorph/references/painting.md
+++ b/.claude/skills/papermorph/references/painting.md
@@ -23,6 +23,7 @@ Money is the user's, so the user sets a ceiling and sees every cent:
- `paint.py` takes quality `low` or `medium` only. Try low first: in these books low was often good enough for the final set (about $0.02 a picture; medium about $0.02–0.03; high cost five times as much and, once used in a film, looked the same).
- Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider, not an estimate. OpenRouter refuses any image request when the balance is under one dollar.
+- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `OPENAI_API_KEY`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own: they like to see each stage.
## Credits and licences
diff --git a/.claude/skills/papermorph/scripts/bake_puppets.py b/.claude/skills/papermorph/scripts/bake_puppets.py
index 20a64c6..49f5488 100644
--- a/.claude/skills/papermorph/scripts/bake_puppets.py
+++ b/.claude/skills/papermorph/scripts/bake_puppets.py
@@ -16,6 +16,7 @@ every piece and then removes the files no chapter asked for. --url defaults to t
import argparse, base64, io, json, pathlib
from PIL import Image
from playwright.sync_api import sync_playwright
+from browsers import exe
READY = """async () => {
let n = -1; while (bakedJobs.size !== n) { n = bakedJobs.size; await Promise.all([...bakedJobs.values()]); await new Promise(r => setTimeout(r, 300)); }
@@ -34,7 +35,12 @@ def main():
got = {}
with sync_playwright() as p:
for kind in (p.chromium, p.firefox):
- b = kind.launch(); pg = b.new_page(viewport={'width': 1600, 'height': 900})
+ try:
+ b = kind.launch(**exe()) if kind is p.chromium else kind.launch()
+ except Exception as e: # Playwright's Firefox may not run on this system: the Chromium pieces still stand
+ if kind is p.chromium: raise
+ print(f'{kind.name} did not start, so Firefox bakes its own few pieces in the page:', str(e).splitlines()[0]); continue
+ pg = b.new_page(viewport={'width': 1600, 'height': 900})
for ch in sorted(d.name for d in site.glob('ch[0-9][0-9]')):
pg.goto(f'{url}{ch}/?bake', timeout=600000)
last = pg.evaluate('BEATS.length - 1')
diff --git a/.claude/skills/papermorph/scripts/bake_sets.py b/.claude/skills/papermorph/scripts/bake_sets.py
index 63b78bc..f493494 100644
--- a/.claude/skills/papermorph/scripts/bake_sets.py
+++ b/.claude/skills/papermorph/scripts/bake_sets.py
@@ -17,6 +17,7 @@ The sketches are a finished look on their own (free) and the composition referen
import asyncio, base64, io, json, pathlib, sys
from PIL import Image
from playwright.async_api import async_playwright
+from browsers import exe
JS = """async ([name, i, soft]) => {
const L = SETS[name]()[i], [x, y, w, h] = L.box, s = L.scale || 1;
@@ -33,7 +34,7 @@ async def main(sets_js, site, only, ref):
out = pathlib.Path(site) / 'img/sets'; old = out / 'sets.js'
man = json.loads(old.read_text().split('=', 1)[1].rstrip().rstrip(';')) if old.exists() else {}
async with async_playwright() as p:
- b = await p.chromium.launch(); pg = await b.new_page()
+ b = await p.chromium.launch(**exe()); pg = await b.new_page()
await pg.add_script_tag(path=str(pathlib.Path(sets_js).resolve()))
known = await pg.evaluate('Object.keys(SETS)')
if set(only) - set(known): sys.exit(f'not in {sets_js}: {sorted(set(only) - set(known))}')
diff --git a/.claude/skills/papermorph/scripts/browsers.py b/.claude/skills/papermorph/scripts/browsers.py
new file mode 100644
index 0000000..3eac141
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/browsers.py
@@ -0,0 +1,19 @@
+"""Which Chromium the scripts launch: Playwright's own, or the one $CHROME names.
+
+ from browsers import exe
+ b = await p.chromium.launch(**exe()) # or sync_api
+
+Set CHROME to an installed Chrome, Chromium, Brave or Edge where Playwright's own build does not run (some Linux
+distributions), e.g. CHROME=/snap/bin/brave. Such a browser also gets the flags a headless page needs there: no
+sandbox (containers), a shared-memory fallback, and sound without a click (the books play audio). Unset, nothing
+changes, so a review on one machine matches another's.
+"""
+import os
+
+ARGS = ["--no-sandbox", "--disable-dev-shm-usage", "--autoplay-policy=no-user-gesture-required"]
+
+
+def exe():
+ """kwargs for p.chromium.launch(...): $CHROME with its flags, or {} for Playwright's bundled browser."""
+ path = os.environ.get("CHROME")
+ return {"executable_path": path, "args": ARGS} if path else {}
diff --git a/.claude/skills/papermorph/scripts/check_blank.py b/.claude/skills/papermorph/scripts/check_blank.py
index 06d3929..27cb429 100644
--- a/.claude/skills/papermorph/scripts/check_blank.py
+++ b/.claude/skills/papermorph/scripts/check_blank.py
@@ -14,6 +14,7 @@ Otherwise it prints one line saying none were found. Exit status 1 when somethin
import argparse, asyncio, os, sys
from pathlib import Path
from playwright.async_api import async_playwright
+from browsers import exe
LIMIT = float(os.environ.get("LIMIT", "1.0"))
PROBE = r"""
@@ -41,7 +42,7 @@ PROBE = r"""
async def main(book: Path, chapters, url):
found = []
async with async_playwright() as p:
- browser = await p.chromium.launch()
+ browser = await p.chromium.launch(**exe())
pg = await browser.new_page(viewport={"width": 1600, "height": 960})
for ch in chapters:
await pg.goto(f"{url}{ch}/index.html?beat=0&t=0"); await pg.wait_for_timeout(300)
diff --git a/.claude/skills/papermorph/scripts/export.py b/.claude/skills/papermorph/scripts/export.py
index fe8d1cc..b4fb88b 100644
--- a/.claude/skills/papermorph/scripts/export.py
+++ b/.claude/skills/papermorph/scripts/export.py
@@ -16,6 +16,7 @@ import argparse, asyncio, functools, json, subprocess, sys, tempfile, wave
import numpy as np
from pathlib import Path
from playwright.async_api import async_playwright
+from browsers import exe
END_SECONDS = 4
FLAT = '#frame { border-radius: 0 !important; box-shadow: none !important; }' # square corners in the video
@@ -66,7 +67,7 @@ async def main(a):
out = Path(a.out); out.mkdir(parents=True, exist_ok=True)
scale = a.height / 900
async with async_playwright() as p:
- b = await p.chromium.launch()
+ b = await p.chromium.launch(**exe())
# The page fits a 1640 x 1000 frame at scale 1: the 1600 x 900 stage, rendered at the requested height.
pg = await b.new_page(viewport={'width': 1640, 'height': 1000}, device_scale_factor=scale)
errs = []
diff --git a/.claude/skills/papermorph/scripts/ledger.py b/.claude/skills/papermorph/scripts/ledger.py
new file mode 100644
index 0000000..cf3d371
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/ledger.py
@@ -0,0 +1,20 @@
+"""Sums for the paint scripts' 5-column TSV ledgers (date, file, model, quality, cost)."""
+import pathlib
+
+
+def rows(path):
+ """Parsed non-empty ledger rows: [date, file, model, quality, cost]."""
+ text = pathlib.Path(path).read_text(encoding="utf-8")
+ return [l.rstrip("\n").split("\t") for l in text.splitlines() if l.strip()]
+
+
+def print_total(path, note=""):
+ """Per-model and overall USD sums; note appends e.g. ', estimated'."""
+ rs = rows(path)
+ by = {}
+ for r in rs:
+ by[r[2]] = by.get(r[2], 0) + float(r[4])
+ tail = f" ({len(rs)} pictures{', ' + note if note else ''})"
+ for m, c in sorted(by.items()):
+ print(f"{m:40s} {c:8.4f} USD")
+ print(f"{'total':40s} {sum(by.values()):8.4f} USD{tail}")
diff --git a/.claude/skills/papermorph/scripts/paint.py b/.claude/skills/papermorph/scripts/paint.py
index ea85673..bf5541b 100644
--- a/.claude/skills/papermorph/scripts/paint.py
+++ b/.claude/skills/papermorph/scripts/paint.py
@@ -17,16 +17,9 @@ after a batch, so the spend is known.
"""
import argparse, base64, datetime, json, mimetypes, os, pathlib, sys, urllib.request, urllib.error
+from ledger import print_total
-def total(path):
- rows = [l.rstrip("\n").split("\t") for l in pathlib.Path(path).read_text(encoding="utf-8").splitlines() if l.strip()]
- by = {}
- for r in rows:
- by[r[2]] = by.get(r[2], 0) + float(r[4])
- for m, c in sorted(by.items()):
- print(f"{m:40s} {c:8.4f} USD")
- print(f"{'total':40s} {sum(by.values()):8.4f} USD ({len(rows)} pictures)")
-
+total = print_total
def key():
f = pathlib.Path("~/.config/openrouter/key").expanduser()
@@ -55,12 +48,14 @@ def main():
body["resolution"] = "2K"
if a.refs:
body["input_references"] = [{"type": "image_url", "image_url": {"url": f"data:{mimetypes.guess_type(r)[0] or 'image/png'};base64," + base64.b64encode(pathlib.Path(r).read_bytes()).decode()}} for r in a.refs]
+ k = key()
req = urllib.request.Request("https://openrouter.ai/api/v1/images", json.dumps(body).encode(),
- {"Authorization": f"Bearer {key()}", "Content-Type": "application/json"})
+ {"Authorization": f"Bearer {k}", "Content-Type": "application/json"})
try:
r = json.load(urllib.request.urlopen(req, timeout=600))
except urllib.error.HTTPError as e:
- raise SystemExit(f"{e.code} {e.read().decode()[:500]}")
+ err = e.read().decode(errors="replace").replace(k, "***")[:500] # redact the whole body, then trim
+ raise SystemExit(f"{e.code} {err}")
out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)
out.write_bytes(base64.b64decode(r["data"][0]["b64_json"]))
usage = r.get("usage") or {}
diff --git a/.claude/skills/papermorph/scripts/paint_openai.py b/.claude/skills/papermorph/scripts/paint_openai.py
new file mode 100644
index 0000000..79c35ba
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/paint_openai.py
@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""One picture from OpenAI's image API directly (no OpenRouter). Same CLI, ledger and spirit as paint.py.
+
+ python3 paint_openai.py OUT.png "prompt" [ref.png ...] [--ar 16:9] [--q low|medium] [--bg transparent]
+ [--model gpt-image-2.5-flare] [--env /path/to/.env] --ledger books/<book>/art/costs.tsv
+ python3 paint_openai.py --total books/<book>/art/costs.tsv # sum a ledger, per model and overall
+
+Aspect ratios map to OpenAI's sizes: 16:9 -> 1536x1024, 9:16 -> 1024x1536, otherwise 1024x1024.
+Reference pictures go through /v1/images/edits (multipart), no refs through /v1/images/generations (JSON).
+Quality is low or medium only: high costs several times as much and has never been needed; the script refuses it.
+The key is read from $OPENAI_API_KEY, else from --env FILE, else ~/.config/papermorph/.env.
+
+OpenAI's response reports usage tokens but not a USD cost, so the ledger records an estimate
+(about 0.02 USD per low picture, 0.05 per medium at 1536x1024) — check the invoice for exact numbers.
+Each call prints the usage and appends one line to the ledger (date, file, model, quality, cost).
+"""
+import argparse, base64, datetime, json, os, pathlib, sys, urllib.request, urllib.error
+
+API = "https://api.openai.com/v1"
+SIZES = {"16:9": "1536x1024", "9:16": "1024x1536", "1:1": "1024x1024"}
+EST = {"low": 0.02, "medium": 0.05, "high": 0.20}
+
+
+from ledger import print_total
+
+def total(path):
+ print_total(path, 'estimated')
+
+
+def env_value(v):
+ """An .env value: surrounding whitespace, then matching outer quotes, removed."""
+ v = v.strip()
+ if len(v) >= 2 and v[0] == v[-1] and v[0] in ('"', "'"):
+ v = v[1:-1]
+ return v
+
+
+def key(env):
+ if os.environ.get("OPENAI_API_KEY"):
+ return os.environ["OPENAI_API_KEY"]
+ for f in ([pathlib.Path(env)] if env else []) + [pathlib.Path("~/.config/papermorph/.env").expanduser()]:
+ if f.exists():
+ for line in f.read_text().splitlines():
+ if line.startswith("OPENAI_API_KEY="):
+ k = env_value(line.split("=", 1)[1])
+ if k: # skip empty lines, keep looking
+ return k
+ raise SystemExit("no key: set OPENAI_API_KEY or pass --env FILE with OPENAI_API_KEY=...")
+
+
+def post(url, key, data, headers):
+ req = urllib.request.Request(url, data, {"Authorization": f"Bearer {key}", **headers})
+ try:
+ return json.load(urllib.request.urlopen(req, timeout=600))
+ except urllib.error.HTTPError as e:
+ body = e.read().decode(errors="replace").replace(key, "***")[:500] # redact the whole body, then trim
+ raise SystemExit(f"{e.code} {body}")
+
+
+def multipart(fields, files):
+ b = "----papermorph" + os.urandom(8).hex()
+ def part(h, v): return f"--{b}\r\n{h}\r\n\r\n".encode() + (v if isinstance(v, bytes) else v.encode()) + b"\r\n"
+ body = b"".join(part(f'Content-Disposition: form-data; name="{k}"', v) for k, v in fields.items())
+ for name, fname, data in files:
+ body += part(f'Content-Disposition: form-data; name="{name}"; filename="{fname}"\r\nContent-Type: image/png', data)
+ return body + f"--{b}--\r\n".encode(), f"multipart/form-data; boundary={b}"
+
+
+def main():
+ if len(sys.argv) == 3 and sys.argv[1] == "--total":
+ return total(sys.argv[2])
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("out"); ap.add_argument("prompt"); ap.add_argument("refs", nargs="*")
+ ap.add_argument("--ar", default="16:9"); ap.add_argument("--q", default="medium", choices=["low", "medium", "high"])
+ ap.add_argument("--bg", default="auto", choices=["auto", "transparent", "opaque"])
+ ap.add_argument("--model", default="gpt-image-2.5-flare")
+ ap.add_argument("--env", default="", help="path to a .env file containing OPENAI_API_KEY=...")
+ ap.add_argument("--ledger", required=True, help="tab-separated cost log, e.g. books/<book>/art/costs.tsv")
+ a = ap.parse_args()
+ if a.q == "high":
+ raise SystemExit("quality high is refused: use low or medium")
+ k = key(a.env)
+ size = SIZES.get(a.ar, "1024x1024")
+ out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)
+
+ if a.refs:
+ fields = {"model": a.model, "prompt": a.prompt, "quality": a.q, "size": size}
+ if a.bg != "auto":
+ fields["background"] = a.bg
+ body, ctype = multipart(fields, [("image[]", pathlib.Path(r).name, pathlib.Path(r).read_bytes()) for r in a.refs])
+ r = post(f"{API}/images/edits", k, body, {"Content-Type": ctype})
+ else:
+ body = {"model": a.model, "prompt": a.prompt, "quality": a.q, "size": size, "output_format": "png"}
+ if a.bg != "auto":
+ body["background"] = a.bg
+ r = post(f"{API}/images/generations", k, json.dumps(body).encode(), {"Content-Type": "application/json"})
+
+ out.write_bytes(base64.b64decode(r["data"][0]["b64_json"]))
+ usage = r.get("usage") or {}
+ cost = (usage.get("cost") if isinstance(usage, dict) else None) or EST[a.q]
+ print(a.out, f"cost {cost} USD (est)", json.dumps(usage))
+ 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{a.model}\t{a.q}\t{cost:.4f}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.claude/skills/papermorph/scripts/shot.py b/.claude/skills/papermorph/scripts/shot.py
index 1496418..2e8f464 100644
--- a/.claude/skills/papermorph/scripts/shot.py
+++ b/.claude/skills/papermorph/scripts/shot.py
@@ -14,17 +14,19 @@ import argparse, asyncio
import sys
from pathlib import Path
from playwright.async_api import async_playwright
+from browsers import exe
from PIL import Image
async def main(a):
a.out.mkdir(parents=True, exist_ok=True)
async with async_playwright() as p:
- b = await p.chromium.launch()
+ b = await p.chromium.launch(**exe())
pg = await b.new_page(viewport={"width": 1600, "height": 960})
errs = []
pg.on("pageerror", lambda e: errs.append(str(e)))
- pg.on("console", lambda m: m.type == "error" and errs.append(m.text))
+ # a desktop browser ($CHROME) also asks the server for /favicon.ico, which is not the book's
+ pg.on("console", lambda m: m.type == "error" and not m.location.get("url", "").endswith("/favicon.ico") and errs.append(m.text))
base = f"{a.url}{a.chapter}/index.html"
await pg.goto(base + "?beat=0&t=0"); await pg.wait_for_timeout(500)
if errs:
diff --git a/.claude/skills/papermorph/scripts/strip.py b/.claude/skills/papermorph/scripts/strip.py
index 0955e45..91734d5 100644
--- a/.claude/skills/papermorph/scripts/strip.py
+++ b/.claude/skills/papermorph/scripts/strip.py
@@ -17,6 +17,7 @@ a row. Firefox by default: it is the slowest common browser and the one to judge
import argparse, asyncio, re, sys, tempfile
from pathlib import Path
from playwright.async_api import async_playwright
+from browsers import exe
from PIL import Image, ImageDraw
def sheet(ims, path, cols=4):
@@ -40,7 +41,7 @@ async def main(a):
out = Path(a.out); out.mkdir(parents=True, exist_ok=True)
tmp = Path(tempfile.mkdtemp()) / "f.png"
async with async_playwright() as p:
- b = await (p.firefox.launch(firefox_user_prefs={"media.autoplay.default": 0}) if a.browser == "firefox" else p.chromium.launch())
+ b = await (p.firefox.launch(firefox_user_prefs={"media.autoplay.default": 0}) if a.browser == "firefox" else p.chromium.launch(**exe()))
pg = await b.new_page(viewport={"width": 1600, "height": 960})
errs = []; pg.on("pageerror", lambda e: errs.append(str(e)))
await pg.goto(f"{a.url}{a.chapter}/?beat=0&t=0"); await pg.wait_for_timeout(800)