explainer-studio 0.1.5__py3-none-any.whl

explainer_studio-0.1.5.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: explainer-studio
+Version: 0.1.5
+Summary: Command-line studio for narrated explainer videos (HyperFrames + Kokoro TTS + ffmpeg)
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: kokoro-onnx>=0.6.1
+Requires-Dist: misaki>=0.9
+Requires-Dist: num2words>=0.5
+Requires-Dist: numpy>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: soundfile>=0.12
+Requires-Dist: spacy<3.9,>=3.8
+Description-Content-Type: text/markdown
+
+# Explainer Studio
+
+[![CI](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeMountWSWS/explainer-studio/actions/workflows/ci.yml)
+
+A command-line studio for narrated explainer videos in the style of [wsws.org](https://www.wsws.org).
+You write a script in Markdown. The studio narrates it with local TTS, aligns every word to the audio,
+and turns each scene into a [HyperFrames](https://www.npmjs.com/package/hyperframes) HTML composition
+that is timed to the narration. It then renders a mastered 1920×1080 MP4 for YouTube, with captions
+and chapter markers.
+
+```
+script.md ──► narration (Kokoro, local; or ElevenLabs) ──► word timings (Whisper)
+          ──► scenes/<id>.html (HyperFrames + GSAP, timed to cues) ──► cached per-scene renders
+          ──► out/<slug>.mp4  (−14 LUFS)  +  out/<slug>.srt  +  out/<slug>.chapters.txt
+```
+
+# Installation
+
+## Requirements
+
+- Linux (developed on Arch with an AMD GPU; the render uses Chromium's GPU capture)
+- [uv](https://docs.astral.sh/uv/), with Python 3.12 or 3.13 (`kokoro-onnx` doesn't support 3.14 yet)
+- Node.js with `npx`. The HyperFrames CLI is fetched on demand at the version pinned in `tools/studio/common.py`.
+- ffmpeg and Chromium
+- Optional: an ElevenLabs API key in `.env` (`ELEVENLABS_API_KEY=…`) for cloud narration
+
+The first `sync` downloads the Kokoro-82M model to `~/.cache/hyperframes/tts` and spaCy's
+`en_core_web_sm` to `~/.cache/hyperframes/spacy`.
+
+# Usage
+
+Making a video with the studio is a loop of writing and listening. You write the script as plain
+Markdown, and the studio reads it aloud, works out exactly when each word is spoken, and hands those
+timings to your scenes so the visuals move in step with the voice. Change a sentence and only that
+sentence is re-recorded and only the affected scenes are re-rendered, so you can refine a five-minute
+video in seconds rather than starting over. Everything runs from one command, `uv run studio`, and
+nothing leaves your machine unless you choose cloud narration.
+
+## Install
+
+With the [requirements](#requirements) in place, either install the `studio` command from PyPI or
+clone the repository.
+
+**From PyPI**, to make videos in a folder of your own:
+
+```bash
+uv tool install explainer-studio   # or run it without installing: uvx --from explainer-studio studio …
+mkdir my-videos && cd my-videos
+studio new my-video "My Video"
+```
+
+The folder you run `studio` in becomes the workspace. It holds `episodes/`, `out/` and `.env`, and
+`studio` finds it from any subdirectory (or set `STUDIO_ROOT`). The house style (`brand/`) and scene
+templates ship with the package. To customise them, copy `brand/` or `templates/` from this repository
+into the workspace, and the studio uses your copy instead. Music beds and voice clips go in the
+workspace's `brand/music/` and `brand/voices/`. Use `studio` wherever this README says `uv run studio`.
+
+**From a clone**, to work on the studio itself or to use the example episodes:
+
+```bash
+git clone git@github.com:JoeMountWSWS/explainer-studio.git
+cd explainer-studio
+uv sync
+```
+
+Run commands from the repository root (or any folder below it). Confirm the install with
+`uv run studio --help`. The first `sync` of an episode downloads the Kokoro voice model and the
+spaCy English model, so it takes a little longer than later runs.
+
+## Quick start
+
+```bash
+uv run studio new my-video "My Video"   # scaffold episodes/my-video/
+$EDITOR episodes/my-video/script.md     # write the script
+uv run studio sync my-video             # narrate, align, stub scene files, write index.html
+uv run studio status my-video           # words, estimated vs actual length, cues per scene
+# design each episodes/my-video/scenes/<id>.html
+uv run studio preview my-video          # HyperFrames Studio in the browser, with narration
+uv run studio check my-video            # lint, layout and contrast audits (must pass)
+uv run studio render my-video --draft   # quick review copy -> out/my-video-draft.mp4
+uv run studio render my-video           # final -> out/my-video.mp4 + .srt + .chapters.txt
+uv run studio thumbnail my-video        # out/my-video-thumbnail.jpg
+uv run studio voices my-video           # audition Kokoro voice blends -> out/voice-samples/
+```
+
+Only scenes that have changed are re-rendered. Changing a paragraph of narration re-synthesises
+that paragraph and nothing else, and re-times the visuals that depend on it.
+
+## Writing a script
+
+```markdown
+---
+title: The Paris Commune
+voice: bf_emma*0.6 + bf_isabella*0.4
+speed: 0.85
+---
+## hook: Seventy-two days
+> template: title
+
+In the spring of 1871, the working class took power in a major city. {sub} This is the story of the Paris Commune.
+```
+
+Each `## id: Chapter title` heading is a scene and a YouTube chapter. `> template:` chooses the
+starting pattern for the scene file (`title`, `stat`, `quote`, `points`, `outro`, `blank`). Other `>`
+lines are visual notes and are never spoken. `{name}` marks a cue that the scene can animate on,
+and `{pause 1.5}` inserts a pause.
+
+The full documentation is at <https://joemountwsws.github.io/explainer-studio/>. [AGENTS.md](AGENTS.md) is the reference for coding agents: every front-matter setting, voice choice, the rules for
+authoring scenes, the render pipeline and known problems. Read [brand/frame.md](brand/frame.md)
+before designing scenes.
+
+## Layout
+
+| Path | What it is |
+| --- | --- |
+| `tools/studio/` | The Python CLI (`uv run studio …`) |
+| `brand/` | House style shared by every episode: design spec, CSS, fonts, GSAP, pronunciations |
+| `templates/` | Starter script, scene patterns and thumbnail |
+| `episodes/<slug>/` | One HyperFrames project per video. `script.md` is the source of truth |
+| `docs/` | The documentation site (MkDocs), including notes such as British ElevenLabs voices |
+| `out/` | Rendered deliverables (gitignored) |
+
+Worked examples: `episodes/demo-paris-commune` (Kokoro, 38s) and `episodes/demo-elevenlabs`
+(the same script narrated by ElevenLabs).
+
+## Working with coding agents
+
+The studio is designed to be driven by Claude Code or another coding agent. `AGENTS.md` (loaded
+through `CLAUDE.md`) gives the agent the conventions it needs, the HyperFrames skills cover the
+composition format and motion, and the `make-explainer-video` skill
+(`.claude/skills/make-explainer-video/`) walks Claude through the whole workflow. Start `claude` in
+the repository root and ask for a video, or run `/make-explainer-video`. See
+[Working with a coding agent](https://joemountwsws.github.io/explainer-studio/coding-agents/).

explainer_studio-0.1.5.dist-info/RECORD

@@ -0,0 +1,37 @@
+studio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+studio/build.py,sha256=TslXn0NCOPXE8YiedKuSoQ8KSBi_96Z1xSPIno8wt3E,8272
+studio/chatterbox_worker.py,sha256=uH2PcWBmP3Ku9019deLTEfPxclILWgukJqB-gYyOGMg,3725
+studio/cli.py,sha256=4EqdOkoKxURH0H8uFm91QvO-RX0Lx2ntk3tymq6aGy4,12504
+studio/common.py,sha256=BFBDD9uamIOVKgAfFBCRoIuzn-p7SS51xwoB9LgqBmo,6796
+studio/music.py,sha256=InOhFZp0jW-v9dMVzTqFfJxEnHreyIrR7cP2LheGhJI,2986
+studio/render.py,sha256=MZq3X9BkofIpKOTN9yJjBXVADULddG-STcWwmGMnyLw,12888
+studio/script.py,sha256=XFDvKpvfcnnIGDwxae1NRM5haeYNnrTZ1QVtx2rO7hQ,5137
+studio/voice.py,sha256=xAN8vbr5NVZ1A4AomKYSHhismpuw1m7UtvzKOzOY4Qc,27223
+studio/data/templates/script.md,sha256=ctxlYiVCUodAkc7tO_BiBvPoooOF2fGmrbb878oypoQ,2236
+studio/data/templates/thumbnail.html,sha256=aDwi-sxGCoIiKc7Xogu2PpbANrr5D0P1pZFap7y657Q,1317
+studio/data/templates/scenes/blank.html,sha256=SEmzt9jLiIkUo7JqnXGpsjEZFp8GQp-W2UMzMhjhCJQ,2071
+studio/data/templates/scenes/outro.html,sha256=h5FSTDl6czgwQJ6YAWDmM_O_etUp7LdaUT6NxaTljSE,2386
+studio/data/templates/scenes/points.html,sha256=HRaVC28g_uQilSs1Z2RdoNxOGUMFGDk2QKW9EB85iSU,2795
+studio/data/templates/scenes/quote.html,sha256=MYhwmmNopGVEY08QEpzbHVPDz_wj3bMq-RS6nsRdk8w,1953
+studio/data/templates/scenes/stat.html,sha256=JbV25BGypTDotK7mjOHRYzl89-xFp-SwJ-tqC5_JVYk,3001
+studio/data/templates/scenes/title.html,sha256=9wAI9GjJL7YzLpQQl9JYFJNNkEJ5eUGCPfHMrfkj8CE,2191
+studio/data/brand/brand.css,sha256=PogQXVQihSt443q6l3egFKkdaTbHW2adl3J62vIvCEw,4632
+studio/data/brand/fonts/JetBrainsMono.ttf,sha256=SHFaQuwkLCHp8CaSiR4UfQIimaUuSNXkE-GpQhk__to,187208
+studio/data/brand/fonts/OFL-JetBrainsMono.txt,sha256=sv5eiYdZTp_9HSylKi9dc-uDNSQ4k8XWJUta1pJpWR0,4399
+studio/data/brand/fonts/OFL-PTSerif.txt,sha256=3fMRwo3fWlrZdHZJg3NGtnvtnTVnicMHK7J9vOSeUU0,4434
+studio/data/brand/fonts/OFL-SourceSans3.txt,sha256=CXRnhyh6KJMjsOw8_00aSoATMbgrcgfB4Yb10mYZo5I,4579
+studio/data/brand/fonts/PTSerif-Bold.ttf,sha256=A4unM2vX6hTxKtFVvtUaQ0XKxRUyddUh3sO6BAIcUm4,339996
+studio/data/brand/fonts/PTSerif-BoldItalic.ttf,sha256=8AN4i6CJgesJiLNVem8iSlPatJwg4oPot01a88Rm-L4,337580
+studio/data/brand/fonts/PTSerif-Italic.ttf,sha256=9X6V_53IVpGjsuGT8gKNs29mY5OaRsD8TyhtYYuAt84,375356
+studio/data/brand/fonts/PTSerif-Regular.ttf,sha256=pJUfreBv-PCbdnOqgf-2WozUCeJNMomm3GcLxN2iVXo,359048
+studio/data/brand/fonts/SourceSans3-Bold.ttf,sha256=jRaSttx_uzPM1nqY_md_YdGsx_QfcAAgeiSi9-CJOYg,379420
+studio/data/brand/fonts/SourceSans3-Italic.ttf,sha256=OeOrBczXy5SQfDEAW7W-wdVDLwsJait4KXbiF6VA62w,395372
+studio/data/brand/fonts/SourceSans3.ttf,sha256=BC_izAuTPjKEENesvQqmoYc9ylrvgYdfS8IUsIglx7k,646340
+studio/data/brand/frame.md,sha256=zfa_Ry2vYkB_Tr0FN6XQOl2_uw59yWbKVIzpkx8kkOo,5626
+studio/data/brand/pronunciations.yaml,sha256=Zd7uMM7N1I0PxuxEBZneCCtQ8aCtc7ppC6mYZuqscms,418
+studio/data/brand/vendor/gsap.min.js,sha256=wXS_zlOnKUGNV6ithiXnJHx5OiL--OKFHjz6PenNgoA,72779
+explainer_studio-0.1.5.dist-info/METADATA,sha256=hCwJL2Za7FBRNS-DTHKpZx4-UnXHn93gYWPI2MkfGeI,7090
+explainer_studio-0.1.5.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+explainer_studio-0.1.5.dist-info/entry_points.txt,sha256=gyRQqzO1R9OGry73U8LLCD6Yl1eh2kxLWzHXyVTQwvk,43
+explainer_studio-0.1.5.dist-info/licenses/LICENSE,sha256=W3y-R_D5tZ6ip9FM-tw-4wc9hbTv0yps-B_UUH_0CD4,2110
+explainer_studio-0.1.5.dist-info/RECORD,,

explainer_studio-0.1.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

explainer_studio-0.1.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+studio = studio.cli:main

explainer_studio-0.1.5.dist-info/licenses/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+Copyright (c) 2026 World Socialist Web Site
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+-------------------------------------------------------------------------------
+Scope
+
+The MIT licence above covers the studio software and its documentation:
+tools/, templates/, brand/brand.css, brand/frame.md, brand/pronunciations.yaml,
+docs/, the .github/ workflows, pyproject.toml, README.md, AGENTS.md and CLAUDE.md.
+
+It does NOT cover editorial content. Everything under episodes/ and scripts/
+(scripts, narration audio, timings, scene designs, thumbnails and the videos
+made from them) is Copyright (c) 2026 World Socialist Web Site, all rights
+reserved.
+
+Third-party files keep their own licences:
+  - brand/fonts/: PT Serif, Source Sans 3 and JetBrains Mono, SIL Open Font
+    License 1.1 (see the OFL-*.txt files alongside them).
+  - brand/vendor/gsap.min.js: GSAP, GreenSock Standard License
+    (https://gsap.com/standard-license), as stated in the file header.
+  - episodes/*/assets/media/: photographs, maps and footage remain under the
+    terms of their original sources, credited on screen where they are used.

studio/build.py

@@ -0,0 +1,196 @@
+"""Turn script + narration into a HyperFrames project: timing, scene stubs, index.html."""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+import shutil
+from pathlib import Path
+
+from .common import BRAND, FORMATS, HF_VERSION, ROOT, TEMPLATES, die, info
+from .script import Script
+
+TIMING_RE = re.compile(r"(/\* <studio:timing> \*/)(.*?)(/\* </studio:timing> \*/)", re.S)
+
+
+def frames(seconds: float, fps: int) -> int:
+    return int(round(seconds * fps))
+
+
+def compute_timing(script: Script, vo: dict[str, dict]) -> dict:
+    """Lay scenes end to end on whole frames. Scene-local times throughout, except `start`."""
+    fps = int(script.setting("fps"))
+    fmt = str(script.setting("format"))
+    if fmt not in FORMATS:
+        die(f"unknown format '{fmt}' (have: {', '.join(FORMATS)})")
+    width, height = FORMATS[fmt]
+    pad_in, pad_out = float(script.setting("pad_in")), float(script.setting("pad_out"))
+    t_frames, scenes = 0, []
+    for sc in script.scenes:
+        rec = vo[sc.id]
+        has_vo = rec["duration"] > 0
+        lead = pad_in if has_vo else 0.0
+        need = lead + rec["duration"] + (pad_out if has_vo else 0.0)
+        dur_f = max(frames(need, fps), frames(sc.min_duration, fps))
+        scenes.append({
+            "id": sc.id,
+            "title": sc.title,
+            "template": sc.template,
+            "start": t_frames / fps,
+            "duration": dur_f / fps,
+            "voStart": lead,
+            "voEnd": round(lead + rec["duration"], 3),
+            "cues": {k: round(v + lead, 3) for k, v in rec["cues"].items()},
+            "paragraphs": [round(p + lead, 3) for p in rec["paragraphs"]],
+        })
+        t_frames += dur_f
+    return {"fps": fps, "format": fmt, "width": width, "height": height,
+            "duration": t_frames / fps, "scenes": scenes}
+
+
+def sync_brand(ep: Path) -> None:
+    """Copy the studio's shared look into the episode (edit brand/, not these copies)."""
+    dst = ep / "assets" / "brand"
+    dst.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(BRAND / "brand.css", dst / "brand.css")
+    shutil.copy2(BRAND / "vendor" / "gsap.min.js", dst / "gsap.min.js")
+    shutil.copytree(BRAND / "fonts", dst / "fonts", dirs_exist_ok=True)
+    shutil.copy2(BRAND / "frame.md", ep / "frame.md")
+
+
+def stub_scene(ep: Path, script: Script, scene: dict, size: tuple[int, int]) -> bool:
+    path = ep / "scenes" / f"{scene['id']}.html"
+    if path.exists():
+        return False
+    tpl = TEMPLATES / "scenes" / f"{scene['template']}.html"
+    if not tpl.exists():
+        choices = ", ".join(p.stem for p in (TEMPLATES / "scenes").glob("*.html"))
+        die(f"scene '{scene['id']}': unknown template '{scene['template']}' (have: {choices})")
+    text = tpl.read_text()
+    text = text.replace("__ID__", scene["id"])
+    text = text.replace("__TITLE__", html.escape(scene["title"]))
+    text = text.replace("__EPISODE__", html.escape(str(script.meta.get("title", "Untitled"))))
+    text = text.replace('data-width="1920" data-height="1080"', f'data-width="{size[0]}" data-height="{size[1]}"')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+    info(f"  new scene file scenes/{scene['id']}.html (from {scene['template']} template)")
+    return True
+
+
+def inject_timing(ep: Path, scene: dict) -> None:
+    path = ep / "scenes" / f"{scene['id']}.html"
+    text = path.read_text()
+    data = {k: scene[k] for k in ("duration", "voStart", "voEnd", "cues", "paragraphs")}
+    data["duration"] = round(data["duration"], 4)
+    block = f"\n          const T = {json.dumps(data)};\n          "
+    new, n = TIMING_RE.subn(lambda m: m.group(1) + block + m.group(3), text, count=1)
+    if n == 0:
+        info(f"  warning: scenes/{scene['id']}.html has no /* <studio:timing> */ block; cues not updated")
+        return
+    if new != text:
+        path.write_text(new)
+
+
+def _host(scene: dict, start: float, size: tuple[int, int]) -> str:
+    sid = scene["id"]
+    return (
+        f'      <div id="scene-{sid}" data-composition-id="scene-{sid}" data-composition-src="scenes/{sid}.html"\n'
+        f'           data-start="{start:.4f}" data-duration="{scene["duration"]:.4f}" data-track-index="1"\n'
+        f'           data-track-kind="graphics" data-width="{size[0]}" data-height="{size[1]}"></div>'
+    )
+
+
+def page(title: str, duration: float, body: str, size: tuple[int, int]) -> str:
+    w, h = size
+    return f"""<!doctype html>
+<!-- GENERATED by `studio sync` from script.md. Do not edit: changes are overwritten. -->
+<html lang="en" data-resolution="{'portrait' if h > w else 'landscape'}">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width={w}, height={h}" />
+    <title>{html.escape(title)}</title>
+    <script src="assets/brand/gsap.min.js"></script>
+    <link rel="stylesheet" href="assets/brand/brand.css" />
+    <style>
+      * {{ margin: 0; padding: 0; box-sizing: border-box; }}
+      html, body {{ width: {w}px; height: {h}px; overflow: hidden; background: #ffffff; }}
+      #root {{ position: relative; width: 100%; height: 100%; overflow: hidden; }}
+    </style>
+  </head>
+  <body>
+    <div id="root" data-composition-id="main" data-start="0" data-duration="{duration:.4f}" data-width="{w}" data-height="{h}">
+{body}
+    </div>
+    <script>
+      window.__timelines["main"] = gsap.timeline({{ paused: true }});
+    </script>
+  </body>
+</html>
+"""
+
+
+def write_index(ep: Path, script: Script, timing: dict) -> None:
+    size = (timing["width"], timing["height"])
+    parts = [_host(s, s["start"], size) for s in timing["scenes"]]
+    for s in timing["scenes"]:
+        if s["voEnd"] > s["voStart"]:
+            parts.append(
+                f'      <audio id="vo-{s["id"]}" src="audio/vo/{s["id"]}.wav" data-start="{s["start"] + s["voStart"]:.4f}" '
+                f'data-duration="{s["voEnd"] - s["voStart"]:.4f}" data-track-index="10" data-volume="1"></audio>'
+            )
+    music = script.setting("music")
+    if music:
+        ext = Path(music).suffix
+        dst = ep / "assets" / f"music{ext}"
+        src = next((p for p in (ep / music, ROOT / music) if p.exists()), ROOT / music)
+        if not src.exists():
+            die(f"music file not found: {src}")
+        shutil.copy2(src, dst)
+        vol = round(10 ** (float(script.setting("music_db")) / 20), 4)
+        parts.append(
+            f'      <audio id="music" src="assets/music{ext}" data-start="0" data-duration="{timing["duration"]:.4f}" '
+            f'data-track-index="11" data-volume="{vol}"></audio>'
+        )
+    (ep / "index.html").write_text(page(str(script.meta.get("title", "Untitled")), timing["duration"], "\n".join(parts), size))
+
+
+def render_shell(ep: Path, scene: dict, timing: dict) -> Path:
+    """A temporary root page hosting one scene at t=0 (silent), so scenes render independently."""
+    shell = ep / f"_render_{scene['id']}.html"
+    size = (timing["width"], timing["height"])
+    shell.write_text(page(scene["id"], scene["duration"], _host(scene, 0.0, size), size))
+    return shell
+
+
+def ensure_project_files(ep: Path) -> None:
+    pkg = ep / "package.json"
+    pkg.write_text(json.dumps({
+        "name": ep.name,
+        "private": True,
+        "type": "module",
+        "scripts": {
+            "dev": f"npx --yes hyperframes@{HF_VERSION} preview",
+            "check": f"npx --yes hyperframes@{HF_VERSION} check",
+        },
+    }, indent=2) + "\n")
+    hfj = ep / "hyperframes.json"
+    if not hfj.exists():
+        hfj.write_text(json.dumps({
+            "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
+            "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
+            "paths": {"blocks": "compositions", "components": "compositions/components", "assets": "assets"},
+            "media": {"autoProxy": True},
+        }, indent=2) + "\n")
+
+
+def build(ep: Path, script: Script, vo: dict[str, dict]) -> dict:
+    ensure_project_files(ep)
+    sync_brand(ep)
+    timing = compute_timing(script, vo)
+    for s in timing["scenes"]:
+        stub_scene(ep, script, s, (timing["width"], timing["height"]))
+        inject_timing(ep, s)
+    write_index(ep, script, timing)
+    (ep / "timing.json").write_text(json.dumps(timing, indent=1))
+    return timing

studio/chatterbox_worker.py

@@ -0,0 +1,96 @@
+"""Chatterbox TTS worker, run by voice.Chatterbox in its own uv environment (torch, numpy<2).
+
+Not part of the studio package's imports: Chatterbox pins torch and numpy<2, which can't share
+the studio venv. Usage:
+
+    python chatterbox_worker.py turbo|standard
+
+Then one JSON request per stdin line:
+    {"text", "out", "ref" (path or null for the built-in voice), "exaggeration", "cfg_weight", "temperature", "seed"}
+and one JSON reply per stdout line: {"ok": true, "sr": 24000} or {"error": "..."}.
+Everything else the libraries print goes to stderr.
+"""
+
+import json
+import os
+import sys
+import traceback
+
+# Keep library chatter off the reply channel: replies go to a private copy of fd 1, and fd 1 itself
+# (what native code and child processes write to) is pointed at stderr.
+replies = os.fdopen(os.dup(1), "w", buffering=1)
+os.dup2(2, 1)
+sys.stdout = sys.stderr
+
+
+def reply(obj: dict) -> None:
+    replies.write(json.dumps(obj) + "\n")
+    replies.flush()
+
+
+def quiet(bar: type) -> type:
+    """A tqdm subclass that never draws."""
+
+    class Quiet(bar):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **{**kwargs, "disable": True})
+
+    return Quiet
+
+
+def main() -> None:
+    kind = sys.argv[1] if len(sys.argv) > 1 else "turbo"
+    import soundfile as sf
+    import torch
+
+    torch.set_num_threads(os.cpu_count() or 4)
+    if kind == "turbo":
+        from chatterbox.tts_turbo import ChatterboxTurboTTS as Model
+    elif kind == "standard":
+        from chatterbox.tts import ChatterboxTTS as Model
+    else:
+        reply({"error": f"unknown chatterbox_model '{kind}' (choose: turbo, standard)"})
+        return
+    model = Model.from_pretrained(device="cpu")
+    # Mute per-step progress bars during generation (left on above for the first-run download).
+    # A subclass, not a partial, so class attributes (tqdm.write, isinstance) keep working.
+    for mod in list(sys.modules.values()):
+        bar = getattr(mod, "tqdm", None) if (getattr(mod, "__name__", "") or "").startswith("chatterbox") else None
+        if isinstance(bar, type):
+            mod.tqdm = quiet(bar)
+    builtin, current = model.conds, None
+    reply({"ok": True, "ready": kind, "sr": model.sr})
+
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            req = json.loads(line)
+            ref = req.get("ref")
+            exaggeration = float(req.get("exaggeration", 0.5))
+            if ref != current:
+                # Conditioning on a clip is the slow part; do it once per voice, not per sentence.
+                # Keyed on the clip alone: standard's generate() re-applies exaggeration on every call,
+                # and Turbo has no emotion input (hp.emotion_adv is False), so it takes no exaggeration.
+                if ref and kind == "standard":
+                    model.prepare_conditionals(ref, exaggeration=exaggeration)
+                elif ref:
+                    model.prepare_conditionals(ref)
+                else:
+                    model.conds = builtin
+                current = ref
+            torch.manual_seed(int(req.get("seed", 0)))
+            kwargs = {"temperature": float(req.get("temperature", 0.8))}
+            if kind == "standard":
+                kwargs.update(exaggeration=exaggeration, cfg_weight=float(req.get("cfg_weight", 0.5)))
+            with torch.inference_mode():
+                wav = model.generate(req["text"], **kwargs)
+            sf.write(req["out"], wav.squeeze(0).cpu().numpy(), model.sr)
+            reply({"ok": True, "sr": model.sr})
+        except Exception as e:
+            traceback.print_exc()
+            reply({"error": f"{type(e).__name__}: {e}"})
+
+
+if __name__ == "__main__":
+    main()