talkthrough 0.1.0__tar.gz

talkthrough-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "talkthrough",
+  "owner": { "name": "Karan Bansal" },
+  "plugins": [
+    {
+      "name": "talkthrough",
+      "source": "./",
+      "description": "Turn any HTML page or PDF into a narrated walkthrough video of itself"
+    }
+  ]
+}

talkthrough-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "talkthrough",
+  "version": "0.1.0",
+  "description": "Turn any HTML page or PDF into a narrated walkthrough video of itself: real captures, a spotlight camera, a voiceover written only from the page's words, synced captions.",
+  "author": { "name": "Karan Bansal" },
+  "homepage": "https://github.com/amishah1998/talkthrough",
+  "license": "MIT"
+}

talkthrough-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+work/
+*.mp4
+!examples/*.mp4

talkthrough-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Issues and pull requests are welcome.
+
+## Set up
+
+```bash
+git clone https://github.com/amishah1998/talkthrough
+cd talkthrough
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[all]"
+talkthrough doctor
+```
+
+## Before you open a PR
+
+- Render one real video with your change and look at a few frames from it
+  (`ffmpeg -ss 10 -i out.mp4 -frames:v 1 frame.png`), including one mid-transition.
+  Framing bugs only show up in real frames.
+- If you touch narration rules, keep the one promise: the voice says only what the page says.
+- Keep the code dependency-light. Pillow, websockets and pypdfium2 are the only hard dependencies.
+
+## Reporting a bad video
+
+Attach the page (or a link to it), the `shots.json`, and a frame that shows the problem.

talkthrough-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karan Bansal
+
+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.

talkthrough-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: talkthrough
+Version: 0.1.0
+Summary: Turn any HTML page or PDF into a narrated walkthrough video of itself
+Project-URL: Homepage, https://github.com/amishah1998/talkthrough
+Project-URL: Issues, https://github.com/amishah1998/talkthrough/issues
+Author: Karan Bansal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,html,narration,pdf,text-to-speech,video,walkthrough
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10
+Requires-Dist: pypdfium2>=4.30
+Requires-Dist: websockets>=12
+Provides-Extra: all
+Requires-Dist: anthropic>=0.60; extra == 'all'
+Requires-Dist: kokoro-onnx>=0.4; extra == 'all'
+Requires-Dist: soundfile>=0.12; extra == 'all'
+Provides-Extra: local
+Requires-Dist: kokoro-onnx>=0.4; extra == 'local'
+Requires-Dist: soundfile>=0.12; extra == 'local'
+Provides-Extra: plan
+Requires-Dist: anthropic>=0.60; extra == 'plan'
+Description-Content-Type: text/markdown
+
+# talkthrough
+
+[![smoke](https://github.com/amishah1998/talkthrough/actions/workflows/smoke.yml/badge.svg)](https://github.com/amishah1998/talkthrough/actions/workflows/smoke.yml)
+
+**A walkthrough that talks. Any HTML page or PDF becomes a narrated video of itself.**
+
+A camera moves over the real page one section at a time, a spotlight shows what is being explained,
+a voice explains it, and captions follow the voice. Nothing on screen is redrawn or restyled: every
+frame is a real crop of your page, so the diagram in the video is the diagram in the document.
+
+![The spotlight moves from the wrong answer to the right one in the Chain-of-Thought paper](https://raw.githubusercontent.com/amishah1998/talkthrough/main/docs/demo.gif)
+
+*The Chain-of-Thought Prompting paper ([Wei et al. 2022](https://arxiv.org/abs/2201.11903), CC BY 4.0).
+The full 58-second walkthrough, with sound and the free local voice:*
+
+https://github.com/user-attachments/assets/bbc0805c-d711-4213-aeb9-a08ec82a8158
+
+The narration is written by Claude from the page's own text, under one rule: add nothing the page
+does not say. That keeps the numbers right far more often than a fresh script would, but it is a model
+writing text, not a guarantee. Read the shot list or the preview sheet before you share a video about
+numbers that matter.
+
+Use it for the report nobody will open, the recap your students watch on the bus, or the docs page
+you want to post as a 90-second clip.
+
+## Quickstart
+
+### In Claude Code (recommended)
+
+```
+/plugin marketplace add amishah1998/talkthrough
+/plugin install talkthrough@talkthrough
+```
+
+Then ask: "make a walkthrough video of report.pdf". Claude reads the page, decides what to focus on,
+writes the shot list, checks the framing on a preview sheet, and renders with the free local voice.
+No API key needed; the agent does the planning.
+
+The skill in `skills/talkthrough/` follows the Agent Skills format, so other agents that read
+skills can use the same folder.
+
+### From the command line
+
+You write the shot list, the tool does the rest. No API key, and this is the path the test suite runs
+on Linux:
+
+```bash
+pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"
+talkthrough doctor                                  # checks browser, ffmpeg and a voice
+talkthrough capture report.pdf --out work/          # page image and a numbered list of sections
+# write work/shots.json (format below), then:
+talkthrough preview work/ && talkthrough render work/ --out report.mp4 --open
+```
+
+The `plan` and `make` commands are untested as of this release; the capture, hand-written
+shots.json, preview and render path is verified. `talkthrough make report.pdf` does it all in one go,
+with Claude choosing the sections through the API, and needs `ANTHROPIC_API_KEY` plus
+`pip install "talkthrough[all] @ git+https://github.com/amishah1998/talkthrough"`.
+
+## How it works
+
+```
+page.html / report.pdf
+   │  capture   headless browser (HTML) or pdfium (PDF): one tall image + a list of sections
+   ▼
+page.png + boxes.json
+   │  plan      an agent or Claude picks the sections that matter and writes what to say
+   ▼
+shots.json
+   │  preview   one spotlighted frame per shot, to check framing before rendering
+   │  render    voice per shot, eased camera moves, spotlight, captions, H.264 + AAC
+   ▼
+walkthrough.mp4   (portrait 1080x1920 by default; landscape and square too)
+```
+
+Step by step, with a shot list you write or edit yourself:
+
+```bash
+talkthrough capture recap.html --out work/
+talkthrough plan work/ --seconds 90 --note "focus on the pricing table"   # or write work/shots.json by hand
+talkthrough preview work/
+talkthrough render work/ --out recap.mp4
+```
+
+A shot list looks like this:
+
+```json
+{
+  "format": "portrait",
+  "tts": "auto",
+  "shots": [
+    {"boxes": ["b0"], "say": "Here is the whole report in ninety seconds. Three findings, one decision."},
+    {"rect": [95, 828, 470, 440], "move": "hold", "say": "This chart is the one to remember: costs fell while usage doubled."}
+  ]
+}
+```
+
+### Title card, end card, file size
+
+Every video opens on a short title card (the page title and the running time) and closes on an end
+card: "Read the full page", the page's link, and a small "made with talkthrough" line. In the
+shot list, `"title"` and `"link"` override what is shown (set `"link"` to the public URL when you
+render a local file), and `"intro": false`, `"outro": false` or `"credit": false` turn parts off.
+
+`--speed 1.25` (or `"speed": 1.25`) makes the voice itself talk faster, with natural pitch; the camera
+and captions follow because they are timed from the audio. Useful for readers who would otherwise
+watch at 1.5x.
+
+`render --share` (or `"quality": "share"`) encodes for chat apps at about half the size of the
+default, with no visible loss on text. Audio is loudness-normalised in both modes, so every voice
+comes out at the same level.
+
+## Voices
+
+It picks the first one available, in this order, or you choose with `"tts"` in the shot list or `--tts`:
+
+| Voice | Setup | Captions | Cost | Notes |
+|---|---|---|---|---|
+| **Cartesia Sonic 3.6** | `CARTESIA_API_KEY` | exact word timings | about $0.25 per 1,000 words | #1 on the [Artificial Analysis TTS leaderboard](https://artificialanalysis.ai/text-to-speech/leaderboard) when this was written |
+| **ElevenLabs** | `ELEVENLABS_API_KEY` | exact word timings | about $0.30 to $0.60 per 1,000 words | Large voice library |
+| **OpenAI gpt-4o-mini-tts** | `OPENAI_API_KEY` | per sentence | cents per video | Tone and pace steerable with `"instructions"` |
+| **Kokoro** (local, free) | `pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"` | per sentence | free | Apache-2.0 weights, runs on CPU on macOS, Linux and Windows; one-time ~350 MB download |
+| **macOS `say`** | nothing | per sentence | free | Zero setup on a Mac; clearly synthetic |
+
+"Per sentence" means each sentence is voiced on its own and measured, so captions change exactly on
+sentence boundaries; words inside a sentence are spread by length.
+
+## Requirements
+
+| For | Needs | Notes |
+|---|---|---|
+| Everything | Python 3.10+ and ffmpeg | Pillow, websockets and pypdfium2 install with the package |
+| HTML pages | Chrome, Chromium or Edge | Found automatically; or set `CHROME=/path/to/browser` |
+| PDFs | nothing extra | Rendered with pdfium; sections come from the page's white space, not its text layer |
+| A voice | one of the options above | `talkthrough doctor` shows what it found |
+| Auto-planning | `anthropic` and `ANTHROPIC_API_KEY` | Not needed when an agent writes the shot list |
+
+## Limits
+
+- Tested on macOS by hand and on Ubuntu (Python 3.10 and 3.12) by the smoke test on every push:
+  an HTML page and a PDF rendered with the Kokoro voice. Windows support is written but untested.
+- The Cartesia, ElevenLabs and OpenAI voices and the `plan` and `make` commands have not been run
+  end to end yet. The local Kokoro voice has.
+- Section detection splits on white space, so a figure with tightly packed panels can come out as
+  one section. Frame part of it with a `rect`; the outline snaps to the content you meant.
+- Pages behind a login or that build slowly can capture half-loaded. Capture a saved copy or a PDF.
+- Narration works best in English or Hinglish in Roman letters. Pages in any language capture fine,
+  and Hindi in a caption gets a Devanagari font, but the voices are tuned for English and correctly
+  joined Hindi letters need libraqm installed.
+
+## Licence
+
+[MIT](LICENSE)

talkthrough-0.1.0/README.md

@@ -0,0 +1,153 @@
+# talkthrough
+
+[![smoke](https://github.com/amishah1998/talkthrough/actions/workflows/smoke.yml/badge.svg)](https://github.com/amishah1998/talkthrough/actions/workflows/smoke.yml)
+
+**A walkthrough that talks. Any HTML page or PDF becomes a narrated video of itself.**
+
+A camera moves over the real page one section at a time, a spotlight shows what is being explained,
+a voice explains it, and captions follow the voice. Nothing on screen is redrawn or restyled: every
+frame is a real crop of your page, so the diagram in the video is the diagram in the document.
+
+![The spotlight moves from the wrong answer to the right one in the Chain-of-Thought paper](https://raw.githubusercontent.com/amishah1998/talkthrough/main/docs/demo.gif)
+
+*The Chain-of-Thought Prompting paper ([Wei et al. 2022](https://arxiv.org/abs/2201.11903), CC BY 4.0).
+The full 58-second walkthrough, with sound and the free local voice:*
+
+https://github.com/user-attachments/assets/bbc0805c-d711-4213-aeb9-a08ec82a8158
+
+The narration is written by Claude from the page's own text, under one rule: add nothing the page
+does not say. That keeps the numbers right far more often than a fresh script would, but it is a model
+writing text, not a guarantee. Read the shot list or the preview sheet before you share a video about
+numbers that matter.
+
+Use it for the report nobody will open, the recap your students watch on the bus, or the docs page
+you want to post as a 90-second clip.
+
+## Quickstart
+
+### In Claude Code (recommended)
+
+```
+/plugin marketplace add amishah1998/talkthrough
+/plugin install talkthrough@talkthrough
+```
+
+Then ask: "make a walkthrough video of report.pdf". Claude reads the page, decides what to focus on,
+writes the shot list, checks the framing on a preview sheet, and renders with the free local voice.
+No API key needed; the agent does the planning.
+
+The skill in `skills/talkthrough/` follows the Agent Skills format, so other agents that read
+skills can use the same folder.
+
+### From the command line
+
+You write the shot list, the tool does the rest. No API key, and this is the path the test suite runs
+on Linux:
+
+```bash
+pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"
+talkthrough doctor                                  # checks browser, ffmpeg and a voice
+talkthrough capture report.pdf --out work/          # page image and a numbered list of sections
+# write work/shots.json (format below), then:
+talkthrough preview work/ && talkthrough render work/ --out report.mp4 --open
+```
+
+The `plan` and `make` commands are untested as of this release; the capture, hand-written
+shots.json, preview and render path is verified. `talkthrough make report.pdf` does it all in one go,
+with Claude choosing the sections through the API, and needs `ANTHROPIC_API_KEY` plus
+`pip install "talkthrough[all] @ git+https://github.com/amishah1998/talkthrough"`.
+
+## How it works
+
+```
+page.html / report.pdf
+   │  capture   headless browser (HTML) or pdfium (PDF): one tall image + a list of sections
+   ▼
+page.png + boxes.json
+   │  plan      an agent or Claude picks the sections that matter and writes what to say
+   ▼
+shots.json
+   │  preview   one spotlighted frame per shot, to check framing before rendering
+   │  render    voice per shot, eased camera moves, spotlight, captions, H.264 + AAC
+   ▼
+walkthrough.mp4   (portrait 1080x1920 by default; landscape and square too)
+```
+
+Step by step, with a shot list you write or edit yourself:
+
+```bash
+talkthrough capture recap.html --out work/
+talkthrough plan work/ --seconds 90 --note "focus on the pricing table"   # or write work/shots.json by hand
+talkthrough preview work/
+talkthrough render work/ --out recap.mp4
+```
+
+A shot list looks like this:
+
+```json
+{
+  "format": "portrait",
+  "tts": "auto",
+  "shots": [
+    {"boxes": ["b0"], "say": "Here is the whole report in ninety seconds. Three findings, one decision."},
+    {"rect": [95, 828, 470, 440], "move": "hold", "say": "This chart is the one to remember: costs fell while usage doubled."}
+  ]
+}
+```
+
+### Title card, end card, file size
+
+Every video opens on a short title card (the page title and the running time) and closes on an end
+card: "Read the full page", the page's link, and a small "made with talkthrough" line. In the
+shot list, `"title"` and `"link"` override what is shown (set `"link"` to the public URL when you
+render a local file), and `"intro": false`, `"outro": false` or `"credit": false` turn parts off.
+
+`--speed 1.25` (or `"speed": 1.25`) makes the voice itself talk faster, with natural pitch; the camera
+and captions follow because they are timed from the audio. Useful for readers who would otherwise
+watch at 1.5x.
+
+`render --share` (or `"quality": "share"`) encodes for chat apps at about half the size of the
+default, with no visible loss on text. Audio is loudness-normalised in both modes, so every voice
+comes out at the same level.
+
+## Voices
+
+It picks the first one available, in this order, or you choose with `"tts"` in the shot list or `--tts`:
+
+| Voice | Setup | Captions | Cost | Notes |
+|---|---|---|---|---|
+| **Cartesia Sonic 3.6** | `CARTESIA_API_KEY` | exact word timings | about $0.25 per 1,000 words | #1 on the [Artificial Analysis TTS leaderboard](https://artificialanalysis.ai/text-to-speech/leaderboard) when this was written |
+| **ElevenLabs** | `ELEVENLABS_API_KEY` | exact word timings | about $0.30 to $0.60 per 1,000 words | Large voice library |
+| **OpenAI gpt-4o-mini-tts** | `OPENAI_API_KEY` | per sentence | cents per video | Tone and pace steerable with `"instructions"` |
+| **Kokoro** (local, free) | `pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"` | per sentence | free | Apache-2.0 weights, runs on CPU on macOS, Linux and Windows; one-time ~350 MB download |
+| **macOS `say`** | nothing | per sentence | free | Zero setup on a Mac; clearly synthetic |
+
+"Per sentence" means each sentence is voiced on its own and measured, so captions change exactly on
+sentence boundaries; words inside a sentence are spread by length.
+
+## Requirements
+
+| For | Needs | Notes |
+|---|---|---|
+| Everything | Python 3.10+ and ffmpeg | Pillow, websockets and pypdfium2 install with the package |
+| HTML pages | Chrome, Chromium or Edge | Found automatically; or set `CHROME=/path/to/browser` |
+| PDFs | nothing extra | Rendered with pdfium; sections come from the page's white space, not its text layer |
+| A voice | one of the options above | `talkthrough doctor` shows what it found |
+| Auto-planning | `anthropic` and `ANTHROPIC_API_KEY` | Not needed when an agent writes the shot list |
+
+## Limits
+
+- Tested on macOS by hand and on Ubuntu (Python 3.10 and 3.12) by the smoke test on every push:
+  an HTML page and a PDF rendered with the Kokoro voice. Windows support is written but untested.
+- The Cartesia, ElevenLabs and OpenAI voices and the `plan` and `make` commands have not been run
+  end to end yet. The local Kokoro voice has.
+- Section detection splits on white space, so a figure with tightly packed panels can come out as
+  one section. Frame part of it with a `rect`; the outline snaps to the content you meant.
+- Pages behind a login or that build slowly can capture half-loaded. Capture a saved copy or a PDF.
+- Narration works best in English or Hinglish in Roman letters. Pages in any language capture fine,
+  and Hindi in a caption gets a Devanagari font, but the voices are tuned for English and correctly
+  joined Hindi letters need libraqm installed.
+
+## Licence
+
+[MIT](LICENSE)

talkthrough-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+Please report security issues privately to karan@karanbansal.in rather than in a public issue.
+
+talkthrough runs a local headless browser against the page you give it and, when a cloud
+voice or the `plan` command is used, sends the page text and images to that provider. Do not point
+it at pages you are not allowed to share with those providers.

talkthrough-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "talkthrough"
+version = "0.1.0"
+description = "Turn any HTML page or PDF into a narrated walkthrough video of itself"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Karan Bansal" }]
+keywords = ["pdf", "html", "video", "walkthrough", "narration", "text-to-speech", "claude-code"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Topic :: Multimedia :: Video",
+  "Environment :: Console",
+]
+dependencies = [
+  "pillow>=10",
+  "websockets>=12",
+  "pypdfium2>=4.30",
+]
+
+[project.optional-dependencies]
+plan = ["anthropic>=0.60"]
+local = ["kokoro-onnx>=0.4", "soundfile>=0.12"]
+all = ["anthropic>=0.60", "kokoro-onnx>=0.4", "soundfile>=0.12"]
+
+[project.scripts]
+talkthrough = "talkthrough.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/amishah1998/talkthrough"
+Issues = "https://github.com/amishah1998/talkthrough/issues"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["docs", "tests", ".github"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

talkthrough-0.1.0/skills/talkthrough/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: talkthrough
+description: Turn an existing HTML page or PDF (a report, recap, cheat sheet, slide deck, docs page) into a narrated walkthrough video of the page itself, like an automatic screen-share. It captures the real page, moves a camera over one section at a time with a spotlight, adds a voiceover written only from the page's own words, and burns in captions synced to the voice. Nothing is redrawn or invented. Use when the user says "make a video of this page", "walkthrough video", "turn this HTML/PDF into a video", "narrate this report", "screen-share video of this", "video version of this doc", "/talkthrough". Not for motion graphics designed from scratch, and not for screen recordings of an app in use.
+---
+
+# talkthrough
+
+The video shows the page the reader already has, section by section, with a voice explaining it.
+The promise is fidelity: every frame is a real crop of the real page, and every sentence of
+narration is something the page says. That is what makes it safe for reports, recaps and anything
+with numbers in it.
+
+The `talkthrough` CLI does the mechanics. Your job is the part that needs judgement: deciding
+what on the page matters, and writing what the voice says over each part.
+
+## Setup
+
+Run `talkthrough doctor`. If the command is missing, run every command through
+`uvx --from "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough" talkthrough ...`
+(the `[local]` part brings the free Kokoro voice; without it only macOS `say` is available), or install it
+with `pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"`. It needs a Chromium browser
+(Chrome, Chromium or Edge) and ffmpeg. For the voice it uses, in order: Cartesia if
+`CARTESIA_API_KEY` is set, ElevenLabs if `ELEVENLABS_API_KEY` is set, OpenAI if `OPENAI_API_KEY` is
+set, the free local Kokoro voice if installed (`pip install "talkthrough[local] @ git+https://github.com/amishah1998/talkthrough"`), then macOS
+`say`. If none is available, suggest the local voice.
+
+## Workflow
+
+Use a fresh work folder per video, e.g. `./walkthrough-work/<name>`.
+
+1. **Capture.** `talkthrough capture PAGE --out DIR`
+   PAGE is an .html file, a URL or a .pdf. It writes `page.png` (the whole page, or every PDF page
+   stacked), `boxes.json` (each section with an id, its rect in css px, and a text excerpt),
+   `page.txt` and `page.json`. HTML sections come from the DOM; PDF sections come from the white
+   space between blocks, so scanned PDFs work too.
+
+2. **Decide what matters.** Read `page.txt` in full. Look at `page.png` in slices if the layout is
+   not obvious from the text. Pick the sections a busy reader most needs, following the page's own
+   signals: its title and opening promise, anything it calls key or essential, the central diagram
+   or table, the decisions, the takeaways, the closing call to action. Skip what is meant to be
+   looked up rather than heard: long reference tables, appendices, source lists, boilerplate.
+   If the user said what to focus on, that wins.
+
+3. **Write `DIR/shots.json`.**
+
+   ```json
+   {
+     "format": "portrait",
+     "tts": "auto",
+     "shots": [
+       {"boxes": ["b0"], "say": "The page's hook, in one or two sentences."},
+       {"boxes": ["b41", "b42"], "say": "One idea, framed by two boxes together."},
+       {"rect": [95, 828, 470, 440], "move": "hold", "say": "Part of a wide diagram, in css px."}
+     ]
+   }
+   ```
+
+   - `format`: `portrait` 1080x1920 (default, for phones), `landscape` 1920x1080, `square` 1080x1080.
+     A single-column page reads best in portrait.
+   - `boxes` frames the union of those boxes; `rect` frames a hand-picked region instead. The camera
+     will not zoom past about 1.15x the capture's pixel density, so text stays sharp. Split a wide
+     diagram into two or three `rect` shots so a phone can read it.
+   - `move`: `auto` (default) pans down a tall region and slowly pushes in on the rest; `pan`,
+     `zoom` and `hold` force one.
+   - `spotlight` (default on) dims everything outside the framed region and outlines it, so the
+     viewer knows what the voice is talking about. Set `false` per shot or at the top level.
+   - The outline snaps to the content inside `boxes` or `rect`: it shrinks to the ink, drops a thin
+     edge strip the rect cut through (half a caption, a sliver of the next panel), and pads each side
+     by up to `pad` (24 css px) or halfway to the nearest neighbour. A rough `rect` is fine. Set
+     `"snap": false` on a shot to outline the exact rect instead.
+   - `tts`: `auto`, `cartesia`, `elevenlabs`, `openai`, `kokoro` or `say`. With a named backend you may also set
+     `voice`, `model` (cloud), `instructions` (OpenAI) or `rate` (say).
+
+   - `speed`: voice pace for every backend, e.g. 1.25. Use it when the user wants a faster watch.
+   - `title` / `link`: what the opening and closing cards show. Defaults are the page title and its
+     URL; for a local file, ask the user for the public URL and set `link` to it. `intro`, `outro`
+     and `credit` set to `false` turn those parts off.
+
+   If the user has no agent handy, `talkthrough plan DIR --seconds 90` asks Claude to write this
+   file (needs `pip install "talkthrough[plan] @ git+https://github.com/amishah1998/talkthrough"` and `ANTHROPIC_API_KEY`).
+
+4. **Preview before rendering.** `talkthrough preview DIR` writes `DIR/preview.png`, one
+   spotlighted frame per shot, and prints the expected length. Look at it. Each shot must frame what
+   its narration talks about, with no key text cut at the edge. Fix `shots.json` and preview again.
+
+5. **Render.** `talkthrough render DIR --out NAME.mp4` (add `--share` when the video is going to
+   WhatsApp, Slack or similar: about half the size). It voices each shot, moves the camera
+   with eased travel between shots, draws captions (synced to the voice's word timings when the
+   backend gives them), adds a progress line, and encodes H.264 + AAC at 30 fps. Expect roughly
+   real-time rendering: a 90-second video takes about 90 seconds on a laptop.
+
+6. **Check the real video.** Pull a few frames with `ffmpeg -ss T -i NAME.mp4 -frames:v 1 f.png`,
+   including one mid-transition and one on the densest shot, and look at them before handing over.
+
+## Writing the narration
+
+- **Only what the page says.** Paraphrase for the ear, but add no fact, number, name, claim or
+  example that is not on the page. If the page hedges, the voice hedges. An invented line breaks the
+  one promise this format makes.
+- **60 to 120 seconds**, about 150 to 300 words. Each shot 1 to 3 short sentences, 12 to 45 words.
+  More shots with less text beat a few long monologues.
+- **Page order, with a spine.** Open on the hook, walk the sections that matter, close on the
+  page's own takeaway or next step.
+- **Point at what is on screen.** "This diagram", "the bad one on the left", "step three".
+- **Write for a voice.** Spell out symbols it would stumble on ("server dot py"), drop code syntax
+  and parentheses, and use plain punctuation.
+
+## Gotchas
+
+- **Box ids are positional.** Re-capturing after the page changes can shift every id; write
+  `shots.json` against the capture you render from.
+- **A frame is usually taller than the section it shows.** The spotlight handles that; do not
+  shrink `rect` below the zoom limit to crop neighbours away.
+- **Pages that need a login or build their content slowly** may capture half-loaded. Capture a saved
+  copy or the PDF instead.
+- **Captions** use exact word timings from Cartesia and ElevenLabs. Other voices speak one sentence
+  at a time, so captions change exactly on sentence boundaries.

talkthrough-0.1.0/src/talkthrough/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

talkthrough-0.1.0/src/talkthrough/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()