boson-video 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. boson_video-0.2.0/.dockerignore +11 -0
  2. boson_video-0.2.0/.gitignore +8 -0
  3. boson_video-0.2.0/AGENTS.md +76 -0
  4. boson_video-0.2.0/CLAUDE.md +14 -0
  5. boson_video-0.2.0/Dockerfile +24 -0
  6. boson_video-0.2.0/LICENSE +21 -0
  7. boson_video-0.2.0/PKG-INFO +130 -0
  8. boson_video-0.2.0/README.md +93 -0
  9. boson_video-0.2.0/deploy/start.sh +21 -0
  10. boson_video-0.2.0/deploy/vercel/vercel.json +7 -0
  11. boson_video-0.2.0/docs/DIRECTION.md +328 -0
  12. boson_video-0.2.0/docs/deploy.md +14 -0
  13. boson_video-0.2.0/docs/how-it-works.md +75 -0
  14. boson_video-0.2.0/docs/measured.md +95 -0
  15. boson_video-0.2.0/docs/plugin.md +79 -0
  16. boson_video-0.2.0/docs/read-view.html +228 -0
  17. boson_video-0.2.0/docs/screenshot.jpg +0 -0
  18. boson_video-0.2.0/docs/superpowers/specs/2026-10-04-plugin-design.md +67 -0
  19. boson_video-0.2.0/docs/timeline-format.md +46 -0
  20. boson_video-0.2.0/docs/workflow.md +103 -0
  21. boson_video-0.2.0/pyproject.toml +63 -0
  22. boson_video-0.2.0/scripts/accuracy.py +56 -0
  23. boson_video-0.2.0/scripts/mcp_smoke.py +74 -0
  24. boson_video-0.2.0/scripts/planted_errors.py +156 -0
  25. boson_video-0.2.0/server.json +37 -0
  26. boson_video-0.2.0/src/boson_video/__init__.py +4 -0
  27. boson_video-0.2.0/src/boson_video/accuracy.py +64 -0
  28. boson_video-0.2.0/src/boson_video/app/app.css +309 -0
  29. boson_video-0.2.0/src/boson_video/app/app.js +825 -0
  30. boson_video-0.2.0/src/boson_video/app/index.html +16 -0
  31. boson_video-0.2.0/src/boson_video/ask.py +107 -0
  32. boson_video-0.2.0/src/boson_video/audio.py +146 -0
  33. boson_video-0.2.0/src/boson_video/bv_speech.swift +90 -0
  34. boson_video-0.2.0/src/boson_video/checker.py +264 -0
  35. boson_video-0.2.0/src/boson_video/cli.py +249 -0
  36. boson_video-0.2.0/src/boson_video/env.py +19 -0
  37. boson_video-0.2.0/src/boson_video/frames.py +175 -0
  38. boson_video-0.2.0/src/boson_video/jobs.py +157 -0
  39. boson_video-0.2.0/src/boson_video/library.py +91 -0
  40. boson_video-0.2.0/src/boson_video/local.py +99 -0
  41. boson_video-0.2.0/src/boson_video/mcp_server.py +161 -0
  42. boson_video-0.2.0/src/boson_video/mercury.py +95 -0
  43. boson_video-0.2.0/src/boson_video/moments.py +89 -0
  44. boson_video-0.2.0/src/boson_video/ocr.py +110 -0
  45. boson_video-0.2.0/src/boson_video/pipeline.py +168 -0
  46. boson_video-0.2.0/src/boson_video/plugin.py +527 -0
  47. boson_video-0.2.0/src/boson_video/render.py +984 -0
  48. boson_video-0.2.0/src/boson_video/scenes.py +250 -0
  49. boson_video-0.2.0/src/boson_video/screens.py +98 -0
  50. boson_video-0.2.0/src/boson_video/sensevoice.py +231 -0
  51. boson_video-0.2.0/src/boson_video/server.py +244 -0
  52. boson_video-0.2.0/src/boson_video/speech.py +118 -0
  53. boson_video-0.2.0/src/boson_video/storyboard.py +52 -0
  54. boson_video-0.2.0/src/boson_video/study.py +237 -0
  55. boson_video-0.2.0/src/boson_video/timeline.py +274 -0
  56. boson_video-0.2.0/src/boson_video/web.py +531 -0
  57. boson_video-0.2.0/src/boson_video/writer.py +164 -0
  58. boson_video-0.2.0/src/boson_video/youtube.py +264 -0
  59. boson_video-0.2.0/tests/fixtures/planted_errors.json +366 -0
  60. boson_video-0.2.0/tests/test_accuracy.py +53 -0
  61. boson_video-0.2.0/tests/test_install.py +89 -0
  62. boson_video-0.2.0/tests/test_live.py +57 -0
  63. boson_video-0.2.0/tests/test_local.py +48 -0
  64. boson_video-0.2.0/tests/test_moments.py +78 -0
  65. boson_video-0.2.0/tests/test_plugin.py +348 -0
  66. boson_video-0.2.0/tests/test_read_view.py +231 -0
  67. boson_video-0.2.0/tests/test_render.py +125 -0
  68. boson_video-0.2.0/tests/test_scenes.py +125 -0
  69. boson_video-0.2.0/tests/test_screens.py +140 -0
  70. boson_video-0.2.0/tests/test_storyboard.py +43 -0
  71. boson_video-0.2.0/tests/test_study.py +120 -0
  72. boson_video-0.2.0/tests/test_web.py +167 -0
  73. boson_video-0.2.0/tests/test_words.py +101 -0
  74. boson_video-0.2.0/tests/test_youtube.py +167 -0
  75. boson_video-0.2.0/uv.lock +1764 -0
@@ -0,0 +1,11 @@
1
+ .env
2
+ .git
3
+ .venv
4
+ .pytest_cache
5
+ .claude
6
+ __pycache__
7
+ *.pyc
8
+ out
9
+ tests
10
+ docs
11
+ scripts
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ out/
6
+ .env
7
+ .DS_Store
8
+ .claude/
@@ -0,0 +1,76 @@
1
+ # Boson-Video: guide for coding agents
2
+
3
+ Read any video like a document. **Read [docs/DIRECTION.md](docs/DIRECTION.md) first.** It
4
+ holds the agreed direction, the milestones, who does what, and the owner's open
5
+ decisions. The target screen is [docs/read-view.html](docs/read-view.html); open it in a
6
+ browser.
7
+
8
+ ## Commands
9
+
10
+ - `uv sync` once, then `uv run boson-video <youtube link | id | file> [--open] [--no-words] [--no-summary] [--lang zh_CN] [-o folder]` (videos are kept in `BOSON_VIDEO_HOME`, default `~/.boson-video`, for the CLI, the page and the plugin alike)
11
+ - `uv run boson-video ask <video> "question"`: the moment that answers it (needs the page to exist)
12
+ - `uv run boson-video serve [--open [<video>]]`: the website on 127.0.0.1:8765: paste a link, read it with the video playing beside it and a working ask box
13
+ - `uv run boson-video web [--hosted] [--host 0.0.0.0] [--port 8770]`: the product page, invite-only, new design (the first run prints your code); `--hosted` refuses YouTube links
14
+ - `uv run boson-video models [zh|en|all]`: fetch the local speech models now (otherwise the first video that needs one downloads it)
15
+ - `uv run boson-video invite [label] [--per-day 10] [--asks 100] | --list | --revoke CODE`: invite codes for it
16
+ - `uv run boson-video mcp`: the plugin (MCP over stdio) for Claude Code, Claude Desktop, Cursor, Codex; setup in `docs/plugin.md`
17
+ - `uv run python scripts/mcp_smoke.py <video> [--no-keys]`: run the plugin like an AI app and call every tool
18
+ - `uv run pytest` (offline) · `uv run pytest -m live` (hits YouTube, runs Apple's transcriber)
19
+ - `uv run python scripts/accuracy.py <video id> <caption language> <locale>`: score our transcript against human captions
20
+
21
+ ## Map
22
+
23
+ - `src/boson_video/youtube.py`: watch page → video, storyboard levels, chapters, heatmap, caption list
24
+ - `storyboard.py`: fetch sheets in parallel, slice into frames
25
+ - `local.py`: ffmpeg keyframes → frames + our own sheets
26
+ - `audio.py`: yt-dlp audio download, 16 kHz WAV, pauses, cutting into pieces
27
+ - `speech.py` + `bv_speech.swift`: Apple's on-device transcriber (macOS 26), built on first use into
28
+ `~/Library/Caches/boson-video/`; pieces run at once; `names()` lists the video's own names for the writer
29
+ - `sensevoice.py`: SenseVoice through sherpa-onnx, where Apple's transcriber isn't available (Windows, Linux)
30
+ - `mercury.py`: the one Mercury client (strict JSON, retries, cost)
31
+ - `study.py`: English for every passage, the glossary, and answers to questions (Jev finds, Mercury explains, Jev checks)
32
+ - `web.py`: `boson-video web`, the product page (Starlette): invite codes and a signed cookie, per-code videos and daily limits, links and uploads, the document as JSON, answers with frames · `app/`: its one page (`index.html`, `app.css`, `app.js`; plain JS, no libraries, no product name): ribbon with hover preview and readout; Summary, Transcript, Terms, Scenes and Ask tabs; original / both / English
33
+ - `server.py`: `boson-video serve`, the website: a front page to paste a YouTube link (`/api/open` starts the background build, `/api/status` follows it), pages and their frames, `/api/ask` (JSON from its own origin only), questions kept in `<id>/notes.json`
34
+ - `library.py`: where videos live (`BOSON_VIDEO_HOME`), load and save (page, `timeline.json`, `sheets/`)
35
+ - `jobs.py`: builds a video in a background thread; progress in `status.json`
36
+ - `frames.py`: picks moments from the scene map; full-resolution frames (yt-dlp stream address + ffmpeg, one per second needed); thumbnail fallback
37
+ - `screens.py`: what was shown, as text: frames at the scene map's moments, read by OCR; subtitles kept apart; build steps credited with their new lines
38
+ - `ocr.py`: RapidOCR in a worker process (never alongside sherpa-onnx), reading frames as they arrive
39
+ - `moments.py`: the moment, the unit everything cites: scenes, words, screen text and the frame joined, coded state, delta, trajectory or seek
40
+ - `plugin.py`: the plugin's tools as plain functions (briefing, read, frames, search, check, list) · `mcp_server.py`: wires them to MCP
41
+ - `accuracy.py`: error rates against human captions (words; characters for Chinese)
42
+ - `writer.py`: Mercury writes the summary and sections (strict JSON schema, every sentence cites passages, one retry)
43
+ - `checker.py`: Jev checks each sentence against its passages; numbers compared in code; citations repaired
44
+ - `ask.py`: Jev finds the passage that answers a question (one pass, or two for more than 255 passages)
45
+ - `env.py`: loads keys from `.env`
46
+ - `scenes.py`: cuts, looks, base/repeat/new, `profile()` headline
47
+ - `render.py`: the self-contained read view (ribbon, summary with language switch, search, scenes); a little JS, no libraries
48
+ - `pipeline.py`: `build` (scenes), `add_words` (speech), `add_summary` (write + check), with per-stage timings · `cli.py`: entry point
49
+ - `timeline.py`: the shared data model; `timeline.json` is the contract between stages and for other tools, versioned, spec in `docs/timeline-format.md`
50
+ - `docs/`: `DIRECTION.md` (source of truth) and `read-view.html` (target design); `deploy.md`: how the owner hosts it (Dockerfile, Coolify, the Vercel address), kept out of the README
51
+
52
+ ## Rules
53
+
54
+ - Follow `docs/DIRECTION.md`: build the next milestone, respect "Not now", and update the
55
+ milestone table when work lands. Don't change the direction without the owner.
56
+ - Speed is the product. Time every stage (`Stopwatch` in `pipeline.py`) and update the
57
+ measured tables in `docs/measured.md` when numbers move. Say which numbers are measured and which
58
+ are estimates.
59
+ - Scene thresholds were calibrated on three reference videos. After any change to
60
+ `scenes.py`, recheck all three: 9JKT5rBbrwM (talking head, expect 3 scenes),
61
+ zjkBMFhNj_g (slides + webcam box, about 59 new, no false repeats), dQw4w9WgXcQ (fast
62
+ cuts). `tests/test_scenes.py` encodes the same cases.
63
+ - Jev is text-only and doesn't write text: it judges (checks, finds) and another model
64
+ writes. It leans toward the option listed first, so every Choice goes out twice in the same
65
+ request with the options reversed, and the answers are averaged (`checker.both_orders`).
66
+ - The engine must work with no keys. Anything that needs Jev or a writing model is an extra
67
+ that says what it is and what checked it. Read TypeSafe's live docs (https://docs.typesafe.ai/llms.txt) before
68
+ integrating it.
69
+ - Keys live in `.env`, which git ignores: `TYPESAFE_API_KEY` (Jev), `INCEPTION_API_KEY`
70
+ (Mercury). Never commit keys.
71
+ - Don't try to get around YouTube's bot checks (PO tokens, player API clients). The
72
+ Chrome extension is the route for that.
73
+ - Ask the owner before downloading models or media onto the owner's machines. `docs/DIRECTION.md` lists what is pending.
74
+ (On a user's computer the plugin downloads its speech model on first use and says so: that is the product.)
75
+ - Publishing: `uv build`, then `uv publish` (PyPI) and `mcp-publisher publish` (the registry, from `server.json`).
76
+ Keep the version the same in `pyproject.toml`, `src/boson_video/__init__.py` and `server.json`.
@@ -0,0 +1,14 @@
1
+ # Boson-Video
2
+
3
+ Read any video like a document. The agreed direction and the agent guide are imported
4
+ below; read them before building.
5
+
6
+ @docs/DIRECTION.md
7
+ @AGENTS.md
8
+
9
+ ## Claude Code notes
10
+
11
+ - For Jev / TypeSafe work, use the `typesafe-ai` skill.
12
+ - The target design is also published as an artifact (owner-only):
13
+ https://claude.ai/artifact/4KTYhto8fKhLPptrokXyUn. After editing `docs/read-view.html`,
14
+ republish it with that URL so the link stays the same.
@@ -0,0 +1,24 @@
1
+ # boson-video web on a server (Coolify, or any Docker host). It runs with --hosted: uploads only,
2
+ # because YouTube downloads stay on the user's side (docs/DIRECTION.md). Mount a persistent
3
+ # volume at /data: videos, invite codes and the speech models (about 650 MB, fetched on the
4
+ # first start by deploy/start.sh) live there. Keys come from the environment, never the image.
5
+ FROM python:3.12-slim
6
+
7
+ # ffmpeg reads the uploads; libgl1 and libglib2.0-0 are what OpenCV (under the screen reader) needs
8
+ RUN apt-get update \
9
+ && apt-get install -y --no-install-recommends ffmpeg ca-certificates curl bzip2 libgl1 libglib2.0-0 \
10
+ && rm -rf /var/lib/apt/lists/*
11
+ COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
12
+
13
+ WORKDIR /app
14
+ COPY pyproject.toml uv.lock README.md ./
15
+ COPY src ./src
16
+ RUN uv sync --frozen --no-dev
17
+ COPY deploy/start.sh ./start.sh
18
+
19
+ ENV BOSON_VIDEO_HOME=/data \
20
+ BOSON_MODELS=/data/models \
21
+ PATH="/app/.venv/bin:$PATH" \
22
+ PYTHONUNBUFFERED=1
23
+ EXPOSE 8770
24
+ CMD ["sh", "/app/start.sh"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 James Lin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.5
2
+ Name: boson-video
3
+ Version: 0.2.0
4
+ Summary: Skim any video: a timed summary, a bilingual transcript, screen text and checked answers, as a web page or an MCP plugin.
5
+ Project-URL: Homepage, https://github.com/linboxin/Boson-Video
6
+ Project-URL: Repository, https://github.com/linboxin/Boson-Video
7
+ Project-URL: Issues, https://github.com/linboxin/Boson-Video/issues
8
+ Author: James Lin
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,learning,mcp,mcp-server,ocr,subtitles,summary,transcript,video,youtube
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: End Users/Desktop
15
+ Classifier: Natural Language :: Chinese (Simplified)
16
+ Classifier: Natural Language :: English
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Operating System :: Microsoft :: Windows
19
+ Classifier: Operating System :: POSIX :: Linux
20
+ Classifier: Programming Language :: Python :: 3
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Multimedia :: Video
23
+ Classifier: Topic :: Text Processing
24
+ Requires-Python: >=3.12
25
+ Requires-Dist: deno>=2.0
26
+ Requires-Dist: httpx[http2]>=0.28
27
+ Requires-Dist: imageio-ffmpeg>=0.6.0
28
+ Requires-Dist: mcp>=2.3.0
29
+ Requires-Dist: numpy>=2.0
30
+ Requires-Dist: pillow>=11.0
31
+ Requires-Dist: rapidocr-onnxruntime>=1.4.4
32
+ Requires-Dist: sherpa-onnx-core>=1.13.8
33
+ Requires-Dist: sherpa-onnx>=1.13.8
34
+ Requires-Dist: typesafe-sdk>=0.7.2
35
+ Requires-Dist: yt-dlp[default]>=2026.8.19
36
+ Description-Content-Type: text/markdown
37
+
38
+ # Boson-Video
39
+
40
+ **Get the point of any video without watching all of it.** Paste a YouTube link or drop a video
41
+ file. Every line of the summary, the transcript and the screen text carries the second it came
42
+ from, and questions are answered from the video and checked against it.
43
+
44
+ <!-- mcp-name: io.github.linboxin/boson-video -->
45
+
46
+ ![A video read in Boson-Video: the player and the ribbon on the left, the terms explained on the right](https://raw.githubusercontent.com/linboxin/Boson-Video/main/docs/screenshot.jpg)
47
+
48
+ - **The ribbon:** the whole video on one strip (scenes, chapters, most replayed). Hover to see any second's frame and words.
49
+ - **Summary:** sections with their frames; every sentence timed and checked (✓ ? ✗).
50
+ - **Transcript:** the original with English beneath, technical terms explained, on-screen text read in.
51
+ - **Ask:** answers that cite their moments and show the frames, with background kept apart.
52
+ - **Your own AI:** the same document as an MCP plugin for Claude, Cursor, Codex and more.
53
+
54
+ Built for long talks, lectures and finance videos in a language you half know (Chinese and English today).
55
+
56
+ ## In your own AI
57
+
58
+ One line, nothing else to install ([uv](https://docs.astral.sh/uv/) runs it):
59
+
60
+ ```bash
61
+ claude mcp add boson-video -- uvx boson-video mcp
62
+ ```
63
+
64
+ Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
65
+
66
+ ```json
67
+ { "mcpServers": { "boson-video": { "command": "uvx", "args": ["boson-video", "mcp"] } } }
68
+ ```
69
+
70
+ Codex (`~/.codex/config.toml`):
71
+
72
+ ```toml
73
+ [mcp_servers.boson-video]
74
+ command = "uvx"
75
+ args = ["boson-video", "mcp"]
76
+ ```
77
+
78
+ Then ask your AI about any YouTube link. It opens the video, reads the transcript, looks at the
79
+ frames that matter at full resolution, searches, and checks its claims, citing every moment. No
80
+ keys needed. Everything runs on your computer. Details: [docs/plugin.md](https://github.com/linboxin/Boson-Video/blob/main/docs/plugin.md).
81
+
82
+ ## Run the page
83
+
84
+ ```bash
85
+ uvx boson-video web # http://127.0.0.1:8770; the first run prints your invite code
86
+ ```
87
+
88
+ Keys make it fuller: `INCEPTION_API_KEY` (Mercury writes the summary, the English and the terms)
89
+ and `TYPESAFE_API_KEY` (Jev checks every sentence and answers questions). Without them you still get
90
+ the scenes, the transcript and search.
91
+
92
+ ## Tested videos
93
+
94
+ Measured, one run each unless a range is shown. Mac: M5 MacBook with Apple's transcriber. Windows: a 12-thread laptop with
95
+ SenseVoice or Parakeet on the CPU. Full tables: [docs/measured.md](https://github.com/linboxin/Boson-Video/blob/main/docs/measured.md).
96
+
97
+ | Video | Length | Scene map | Words | Transcript errors¹ | Screen text | Summary ✓ |
98
+ | --- | --- | --- | --- | --- | --- | --- |
99
+ | Money or Life 美股频道, Meta and AI (zh, talking head) | 24:53 | 1.3 s | 13.8 s (Mac) | no human captions | — | 13 / 13 |
100
+ | Money or Life 美股频道, AI drug discovery (zh, slides) | 28:24 | 1.1 s | 18.5 s (Mac) | not scored | 36 moments read | 15 / 16 |
101
+ | 程序员老王, LLM abliteration (zh, animated diagrams) | 11:35 | — | 10.0 s (Windows) | not scored | 88 moments; subtitles apart at 85 | 21–22 / 22–23 (several runs) |
102
+ | 陳永儀, TEDxTaipei (zh, talk) | 14:29 | — | 7.1 s (Mac) | 5.3% chars (Mac), 4.8% (SenseVoice) | — | 14 / 14 |
103
+ | Ken Robinson, TED (en, talk) | 20:06 | — | 9.9 s (Mac) | 10.0% words (Mac), 10.5% (Parakeet) | — | 22 / 25 |
104
+ | Sean's AI Stories, agent observability (en, screen recording) | 20:48 | 1.5 s | 13.2 s (Mac) | not scored | none: YouTube refused full resolution | 23 / 26 |
105
+ | Andrej Karpathy, Intro to LLMs (en, slides) | 59:48 | 1.6 s | 30.5 s (Mac) | only automatic captions | 19 of 20 slides right | 22 / 23 |
106
+ | Rick Astley, Never Gonna Give You Up (fast cuts) | 3:33 | 0.7 s | — | — | — | — |
107
+
108
+ ¹ Against human captions (`scripts/accuracy.py`); about half the English errors are filler words the captions leave out.
109
+ Summary ✓: sentences confirmed against what was said (Jev and code).
110
+
111
+ ## Command line
112
+
113
+ ```bash
114
+ uvx boson-video <link | id | file> # build a video: scenes, words, screen text, summary
115
+ uvx boson-video ask <video> "question" # the moment that answers it
116
+ uvx boson-video models # fetch the local speech models now instead of on first use
117
+ ```
118
+
119
+ From a clone: `uv sync`, then `uv run boson-video …`; `uv run pytest` runs the tests (offline).
120
+
121
+ ## More
122
+
123
+ - [docs/workflow.md](https://github.com/linboxin/Boson-Video/blob/main/docs/workflow.md): how the workflow is designed: stages, the document, the ways in
124
+ - [docs/how-it-works.md](https://github.com/linboxin/Boson-Video/blob/main/docs/how-it-works.md): the pipeline, what YouTube allows, limits
125
+ - [docs/DIRECTION.md](https://github.com/linboxin/Boson-Video/blob/main/docs/DIRECTION.md): what we're building, milestones, decisions
126
+ - [docs/timeline-format.md](https://github.com/linboxin/Boson-Video/blob/main/docs/timeline-format.md): the document format, for other tools
127
+ - [AGENTS.md](https://github.com/linboxin/Boson-Video/blob/main/AGENTS.md): the guide for coding agents
128
+
129
+ MIT licensed. YouTube's terms don't allow automated access for products, so everything that touches
130
+ YouTube runs on your own computer.
@@ -0,0 +1,93 @@
1
+ # Boson-Video
2
+
3
+ **Get the point of any video without watching all of it.** Paste a YouTube link or drop a video
4
+ file. Every line of the summary, the transcript and the screen text carries the second it came
5
+ from, and questions are answered from the video and checked against it.
6
+
7
+ <!-- mcp-name: io.github.linboxin/boson-video -->
8
+
9
+ ![A video read in Boson-Video: the player and the ribbon on the left, the terms explained on the right](https://raw.githubusercontent.com/linboxin/Boson-Video/main/docs/screenshot.jpg)
10
+
11
+ - **The ribbon:** the whole video on one strip (scenes, chapters, most replayed). Hover to see any second's frame and words.
12
+ - **Summary:** sections with their frames; every sentence timed and checked (✓ ? ✗).
13
+ - **Transcript:** the original with English beneath, technical terms explained, on-screen text read in.
14
+ - **Ask:** answers that cite their moments and show the frames, with background kept apart.
15
+ - **Your own AI:** the same document as an MCP plugin for Claude, Cursor, Codex and more.
16
+
17
+ Built for long talks, lectures and finance videos in a language you half know (Chinese and English today).
18
+
19
+ ## In your own AI
20
+
21
+ One line, nothing else to install ([uv](https://docs.astral.sh/uv/) runs it):
22
+
23
+ ```bash
24
+ claude mcp add boson-video -- uvx boson-video mcp
25
+ ```
26
+
27
+ Claude Desktop (`claude_desktop_config.json`) or Cursor (`.cursor/mcp.json`):
28
+
29
+ ```json
30
+ { "mcpServers": { "boson-video": { "command": "uvx", "args": ["boson-video", "mcp"] } } }
31
+ ```
32
+
33
+ Codex (`~/.codex/config.toml`):
34
+
35
+ ```toml
36
+ [mcp_servers.boson-video]
37
+ command = "uvx"
38
+ args = ["boson-video", "mcp"]
39
+ ```
40
+
41
+ Then ask your AI about any YouTube link. It opens the video, reads the transcript, looks at the
42
+ frames that matter at full resolution, searches, and checks its claims, citing every moment. No
43
+ keys needed. Everything runs on your computer. Details: [docs/plugin.md](https://github.com/linboxin/Boson-Video/blob/main/docs/plugin.md).
44
+
45
+ ## Run the page
46
+
47
+ ```bash
48
+ uvx boson-video web # http://127.0.0.1:8770; the first run prints your invite code
49
+ ```
50
+
51
+ Keys make it fuller: `INCEPTION_API_KEY` (Mercury writes the summary, the English and the terms)
52
+ and `TYPESAFE_API_KEY` (Jev checks every sentence and answers questions). Without them you still get
53
+ the scenes, the transcript and search.
54
+
55
+ ## Tested videos
56
+
57
+ Measured, one run each unless a range is shown. Mac: M5 MacBook with Apple's transcriber. Windows: a 12-thread laptop with
58
+ SenseVoice or Parakeet on the CPU. Full tables: [docs/measured.md](https://github.com/linboxin/Boson-Video/blob/main/docs/measured.md).
59
+
60
+ | Video | Length | Scene map | Words | Transcript errors¹ | Screen text | Summary ✓ |
61
+ | --- | --- | --- | --- | --- | --- | --- |
62
+ | Money or Life 美股频道, Meta and AI (zh, talking head) | 24:53 | 1.3 s | 13.8 s (Mac) | no human captions | — | 13 / 13 |
63
+ | Money or Life 美股频道, AI drug discovery (zh, slides) | 28:24 | 1.1 s | 18.5 s (Mac) | not scored | 36 moments read | 15 / 16 |
64
+ | 程序员老王, LLM abliteration (zh, animated diagrams) | 11:35 | — | 10.0 s (Windows) | not scored | 88 moments; subtitles apart at 85 | 21–22 / 22–23 (several runs) |
65
+ | 陳永儀, TEDxTaipei (zh, talk) | 14:29 | — | 7.1 s (Mac) | 5.3% chars (Mac), 4.8% (SenseVoice) | — | 14 / 14 |
66
+ | Ken Robinson, TED (en, talk) | 20:06 | — | 9.9 s (Mac) | 10.0% words (Mac), 10.5% (Parakeet) | — | 22 / 25 |
67
+ | Sean's AI Stories, agent observability (en, screen recording) | 20:48 | 1.5 s | 13.2 s (Mac) | not scored | none: YouTube refused full resolution | 23 / 26 |
68
+ | Andrej Karpathy, Intro to LLMs (en, slides) | 59:48 | 1.6 s | 30.5 s (Mac) | only automatic captions | 19 of 20 slides right | 22 / 23 |
69
+ | Rick Astley, Never Gonna Give You Up (fast cuts) | 3:33 | 0.7 s | — | — | — | — |
70
+
71
+ ¹ Against human captions (`scripts/accuracy.py`); about half the English errors are filler words the captions leave out.
72
+ Summary ✓: sentences confirmed against what was said (Jev and code).
73
+
74
+ ## Command line
75
+
76
+ ```bash
77
+ uvx boson-video <link | id | file> # build a video: scenes, words, screen text, summary
78
+ uvx boson-video ask <video> "question" # the moment that answers it
79
+ uvx boson-video models # fetch the local speech models now instead of on first use
80
+ ```
81
+
82
+ From a clone: `uv sync`, then `uv run boson-video …`; `uv run pytest` runs the tests (offline).
83
+
84
+ ## More
85
+
86
+ - [docs/workflow.md](https://github.com/linboxin/Boson-Video/blob/main/docs/workflow.md): how the workflow is designed: stages, the document, the ways in
87
+ - [docs/how-it-works.md](https://github.com/linboxin/Boson-Video/blob/main/docs/how-it-works.md): the pipeline, what YouTube allows, limits
88
+ - [docs/DIRECTION.md](https://github.com/linboxin/Boson-Video/blob/main/docs/DIRECTION.md): what we're building, milestones, decisions
89
+ - [docs/timeline-format.md](https://github.com/linboxin/Boson-Video/blob/main/docs/timeline-format.md): the document format, for other tools
90
+ - [AGENTS.md](https://github.com/linboxin/Boson-Video/blob/main/AGENTS.md): the guide for coding agents
91
+
92
+ MIT licensed. YouTube's terms don't allow automated access for products, so everything that touches
93
+ YouTube runs on your own computer.
@@ -0,0 +1,21 @@
1
+ #!/bin/sh
2
+ # Start boson-video web in a container: fetch the speech models into the volume once (SenseVoice
3
+ # for Chinese, Parakeet for English, Silero for finding speech; about 650 MB), then serve.
4
+ set -e
5
+ M="${BOSON_MODELS:-/data/models}"
6
+ URL=https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models
7
+ mkdir -p "$M"
8
+
9
+ fetch() {
10
+ [ -d "$M/$1" ] && return 0
11
+ echo "downloading $1 (once, into the volume)"
12
+ rm -rf "$M/.part" && mkdir -p "$M/.part"
13
+ curl -fsSL "$URL/$1.tar.bz2" | tar -xj -C "$M/.part"
14
+ mv "$M/.part/$1" "$M/$1" && rm -rf "$M/.part"
15
+ }
16
+ fetch sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2025-09-09
17
+ fetch sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8
18
+ [ -f "$M/silero_vad.onnx" ] || curl -fsSL -o "$M/silero_vad.onnx" "$URL/silero_vad.onnx"
19
+
20
+ # Behind Coolify's proxy, which brings HTTPS and the domain; the first start prints your invite code.
21
+ exec boson-video web --hosted --host 0.0.0.0 --port "${PORT:-8770}"
@@ -0,0 +1,7 @@
1
+ {
2
+ "$schema": "https://openapi.vercel.sh/vercel.json",
3
+ "rewrites": [
4
+ { "source": "/", "destination": "https://h0wsk84kc00084ccg08o040k.40.160.231.143.sslip.io/" },
5
+ { "source": "/:path*", "destination": "https://h0wsk84kc00084ccg08o040k.40.160.231.143.sslip.io/:path*" }
6
+ ]
7
+ }