cardbox-video 0.1.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 (83) hide show
  1. cardbox_video-0.1.0/.gitignore +12 -0
  2. cardbox_video-0.1.0/CHANGELOG.md +19 -0
  3. cardbox_video-0.1.0/CONTRIBUTING.md +32 -0
  4. cardbox_video-0.1.0/Dockerfile +19 -0
  5. cardbox_video-0.1.0/LICENSE +21 -0
  6. cardbox_video-0.1.0/PKG-INFO +296 -0
  7. cardbox_video-0.1.0/README.md +238 -0
  8. cardbox_video-0.1.0/SECURITY.md +16 -0
  9. cardbox_video-0.1.0/docker-compose.yml +11 -0
  10. cardbox_video-0.1.0/docs/spec.md +142 -0
  11. cardbox_video-0.1.0/examples/README.md +17 -0
  12. cardbox_video-0.1.0/examples/hash-table/reel.yaml +56 -0
  13. cardbox_video-0.1.0/examples/promo/promo-explainer.yaml +84 -0
  14. cardbox_video-0.1.0/examples/promo/promo-reel.yaml +40 -0
  15. cardbox_video-0.1.0/examples/wifi.txt +9 -0
  16. cardbox_video-0.1.0/pyproject.toml +69 -0
  17. cardbox_video-0.1.0/server/.gitignore +2 -0
  18. cardbox_video-0.1.0/server/README.md +75 -0
  19. cardbox_video-0.1.0/server/cmd/cardbox-server/main.go +123 -0
  20. cardbox_video-0.1.0/server/go.mod +17 -0
  21. cardbox_video-0.1.0/server/go.sum +50 -0
  22. cardbox_video-0.1.0/server/internal/api/api.go +427 -0
  23. cardbox_video-0.1.0/server/internal/api/api_test.go +197 -0
  24. cardbox_video-0.1.0/server/internal/jobs/hub.go +69 -0
  25. cardbox_video-0.1.0/server/internal/jobs/job.go +55 -0
  26. cardbox_video-0.1.0/server/internal/jobs/jobs_test.go +173 -0
  27. cardbox_video-0.1.0/server/internal/jobs/manager.go +206 -0
  28. cardbox_video-0.1.0/server/internal/ratelimit/ratelimit.go +64 -0
  29. cardbox_video-0.1.0/server/internal/ratelimit/ratelimit_test.go +33 -0
  30. cardbox_video-0.1.0/server/internal/runner/runner.go +118 -0
  31. cardbox_video-0.1.0/server/internal/runner/runner_test.go +37 -0
  32. cardbox_video-0.1.0/server/internal/store/store.go +197 -0
  33. cardbox_video-0.1.0/server/internal/webhook/webhook.go +91 -0
  34. cardbox_video-0.1.0/server/internal/webhook/webhook_test.go +58 -0
  35. cardbox_video-0.1.0/src/cardbox/__init__.py +3 -0
  36. cardbox_video-0.1.0/src/cardbox/__main__.py +3 -0
  37. cardbox_video-0.1.0/src/cardbox/app.py +325 -0
  38. cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-Bold.ttf +0 -0
  39. cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-OFL.txt +93 -0
  40. cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-Regular.ttf +0 -0
  41. cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-SemiBold.ttf +0 -0
  42. cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-OFL.txt +93 -0
  43. cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-Regular.ttf +0 -0
  44. cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-SemiBold.ttf +0 -0
  45. cardbox_video-0.1.0/src/cardbox/assets/icons/LICENSE-lucide.txt +43 -0
  46. cardbox_video-0.1.0/src/cardbox/assets/icons/lucide.json +1 -0
  47. cardbox_video-0.1.0/src/cardbox/browser.py +61 -0
  48. cardbox_video-0.1.0/src/cardbox/captions.py +83 -0
  49. cardbox_video-0.1.0/src/cardbox/cards.py +203 -0
  50. cardbox_video-0.1.0/src/cardbox/cli.py +230 -0
  51. cardbox_video-0.1.0/src/cardbox/formats.py +40 -0
  52. cardbox_video-0.1.0/src/cardbox/icons.py +44 -0
  53. cardbox_video-0.1.0/src/cardbox/localguard.py +43 -0
  54. cardbox_video-0.1.0/src/cardbox/mcp_server.py +233 -0
  55. cardbox_video-0.1.0/src/cardbox/media.py +148 -0
  56. cardbox_video-0.1.0/src/cardbox/music.py +97 -0
  57. cardbox_video-0.1.0/src/cardbox/render.py +267 -0
  58. cardbox_video-0.1.0/src/cardbox/scenes/library.js +267 -0
  59. cardbox_video-0.1.0/src/cardbox/scenes/runtime.js +173 -0
  60. cardbox_video-0.1.0/src/cardbox/scenes.py +129 -0
  61. cardbox_video-0.1.0/src/cardbox/script.py +112 -0
  62. cardbox_video-0.1.0/src/cardbox/spec.py +173 -0
  63. cardbox_video-0.1.0/src/cardbox/templates/app.html +355 -0
  64. cardbox_video-0.1.0/src/cardbox/templates/reel.yaml +31 -0
  65. cardbox_video-0.1.0/src/cardbox/templates/studio.html +108 -0
  66. cardbox_video-0.1.0/src/cardbox/themes.py +44 -0
  67. cardbox_video-0.1.0/src/cardbox/voice/__init__.py +1 -0
  68. cardbox_video-0.1.0/src/cardbox/voice/align.py +101 -0
  69. cardbox_video-0.1.0/src/cardbox/voice/engines.py +158 -0
  70. cardbox_video-0.1.0/src/cardbox/voice/profile.py +145 -0
  71. cardbox_video-0.1.0/src/cardbox/voice/studio.py +141 -0
  72. cardbox_video-0.1.0/src/cardbox/voice/worker.py +110 -0
  73. cardbox_video-0.1.0/src/cardbox/workspace.py +60 -0
  74. cardbox_video-0.1.0/tests/conftest.py +8 -0
  75. cardbox_video-0.1.0/tests/test_align.py +51 -0
  76. cardbox_video-0.1.0/tests/test_app.py +91 -0
  77. cardbox_video-0.1.0/tests/test_captions.py +32 -0
  78. cardbox_video-0.1.0/tests/test_formats_themes.py +38 -0
  79. cardbox_video-0.1.0/tests/test_mcp.py +41 -0
  80. cardbox_video-0.1.0/tests/test_media_music.py +35 -0
  81. cardbox_video-0.1.0/tests/test_script.py +71 -0
  82. cardbox_video-0.1.0/tests/test_spec.py +48 -0
  83. cardbox_video-0.1.0/tests/test_voice_profile.py +41 -0
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ build/
8
+ *.mp4
9
+ caption.txt
10
+ .DS_Store
11
+ data/
12
+ tutorial/out/
@@ -0,0 +1,19 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (first release)
4
+
5
+ - **The app:** run `cardbox` and it opens in your browser. Write a script, choose format and style, add images or
6
+ clips, record your voice, preview frames and render, with no commands.
7
+ - **Plain-text scripts:** one paragraph per beat; `# headline`, `# 8.8% label` stat cards and `@ file` media lines.
8
+ No paid AI needed.
9
+ - **Formats:** vertical (9:16), landscape (16:9) and square (1:1) from the same script.
10
+ - **Style:** 7 themes, any accent color, sans or mono, 4 caption styles, 3 generated music moods.
11
+ - **Voice:** record about a minute (consent first), clone it locally, and every line is transcribed and re-recorded
12
+ if a word comes out wrong. The computer's voice and silent previews also work.
13
+ - **13 animated scenes**, cued to spoken words: counter, donut, bars, flow, terminal, mesh, grid, photo, logo, chat,
14
+ script, voice, formats.
15
+ - **Media:** your own images and video clips as backgrounds; openly licensed image search (Openverse, Wikimedia
16
+ Commons) with credits written into the caption.
17
+ - **MCP server** with 14 tools, including `make_video` (plain text) and `preview_beat` (frames the AI can see).
18
+ - **Render API (Go):** worker pool, SSE progress, idempotency, content-hash reuse, signed webhooks, API keys,
19
+ rate limits, Prometheus metrics, crash recovery.
@@ -0,0 +1,32 @@
1
+ # Contributing
2
+
3
+ Thanks for helping! Small, focused pull requests are easiest to review.
4
+
5
+ ## Setup
6
+
7
+ ```bash
8
+ git clone https://github.com/aryainguz/cardbox && cd cardbox
9
+ python -m venv .venv && . .venv/bin/activate
10
+ pip install -e ".[dev]"
11
+ python -m playwright install chromium
12
+ cardbox doctor
13
+ pytest && ruff check src tests
14
+ (cd server && go test -race ./...)
15
+ ```
16
+
17
+ ## Good first contributions
18
+
19
+ - **A new scene.** Add one function to `src/cardbox/scenes/library.js` (design it in the 1080-wide stage,
20
+ content between y 330 and 1290, so it works in every format), describe its params in `CATALOG` in
21
+ `src/cardbox/scenes.py` and in `docs/spec.md`, and add an example beat to `examples/`.
22
+ - **A theme.** Add a palette to `src/cardbox/themes.py` and its name to `Theme` in `spec.py`.
23
+ - **A caption style.** Add a `.cap.<style>` rule in `cards.py` and the name to `captions` in `spec.py`.
24
+ - **A music mood.** Add an entry to `MOODS` in `music.py`.
25
+
26
+ Check your change visually with `cardbox preview <spec> <beat>` in all three formats.
27
+
28
+ ## Guidelines
29
+
30
+ - Every number in an example must be true.
31
+ - No copyrighted media in the repo: images in examples must be openly licensed, with credits.
32
+ - Keep the voice features consent-first.
@@ -0,0 +1,19 @@
1
+ # One image with the renderer (Python + Chromium + ffmpeg) and the Go API in front of it.
2
+ FROM golang:1.26-bookworm AS server
3
+ WORKDIR /src
4
+ COPY server/go.mod server/go.sum ./
5
+ RUN go mod download
6
+ COPY server/ ./
7
+ RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /cardbox-server ./cmd/cardbox-server
8
+
9
+ FROM python:3.11-slim-bookworm
10
+ RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg espeak-ng && rm -rf /var/lib/apt/lists/*
11
+ WORKDIR /app
12
+ COPY pyproject.toml README.md LICENSE ./
13
+ COPY src ./src
14
+ RUN pip install --no-cache-dir . && python -m playwright install --with-deps chromium
15
+ COPY --from=server /cardbox-server /usr/local/bin/cardbox-server
16
+ ENV CARDBOX_DATA=/data CARDBOX_ADDR=:8080
17
+ VOLUME /data
18
+ EXPOSE 8080
19
+ CMD ["cardbox-server"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The cardbox authors
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,296 @@
1
+ Metadata-Version: 2.5
2
+ Name: cardbox-video
3
+ Version: 0.1.0
4
+ Summary: Plain text in, finished video out: narrated, captioned, animated videos in your own cloned voice. No paid AI needed; an MCP server lets any AI assistant drive it.
5
+ Project-URL: Homepage, https://github.com/aryainguz/cardbox
6
+ Project-URL: Documentation, https://aryainguz.github.io/cardbox
7
+ Project-URL: Source, https://github.com/aryainguz/cardbox
8
+ Project-URL: Issues, https://github.com/aryainguz/cardbox/issues
9
+ Project-URL: Changelog, https://github.com/aryainguz/cardbox/blob/main/CHANGELOG.md
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 The cardbox authors
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: captions,ffmpeg,mcp,reels,shorts,tiktok,tts,video,voice-cloning
33
+ Classifier: Development Status :: 3 - Alpha
34
+ Classifier: Environment :: Web Environment
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: MacOS
38
+ Classifier: Operating System :: POSIX :: Linux
39
+ Classifier: Programming Language :: Python :: 3
40
+ Classifier: Programming Language :: Python :: 3.10
41
+ Classifier: Programming Language :: Python :: 3.11
42
+ Classifier: Programming Language :: Python :: 3.12
43
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
44
+ Classifier: Topic :: Multimedia :: Video
45
+ Requires-Python: >=3.10
46
+ Requires-Dist: mcp>=2.0
47
+ Requires-Dist: numpy>=1.24
48
+ Requires-Dist: playwright>=1.44
49
+ Requires-Dist: pydantic>=2.6
50
+ Requires-Dist: pyyaml>=6.0
51
+ Provides-Extra: dev
52
+ Requires-Dist: pytest>=8; extra == 'dev'
53
+ Requires-Dist: ruff>=0.5; extra == 'dev'
54
+ Provides-Extra: voice
55
+ Requires-Dist: chatterbox-tts>=0.1.2; extra == 'voice'
56
+ Requires-Dist: openai-whisper>=20240930; extra == 'voice'
57
+ Description-Content-Type: text/markdown
58
+
59
+ <p align="center">
60
+ <img src="site/media/logo.svg" width="72" alt="cardbox logo">
61
+ </p>
62
+
63
+ <h1 align="center">cardbox</h1>
64
+
65
+ <p align="center">
66
+ <b>Script in. Video out. In your own voice.</b><br>
67
+ Narrated, captioned, animated videos for Reels, Shorts, YouTube and LinkedIn from plain text.<br>
68
+ No paid AI needed, and your AI assistant can drive it over MCP when you want more.
69
+ </p>
70
+
71
+ <p align="center">
72
+ <a href="https://aryainguz.github.io/cardbox">Website</a> ·
73
+ <a href="#quick-start">Quick start</a> ·
74
+ <a href="#use-it-from-your-ai-assistant-mcp">MCP</a> ·
75
+ <a href="docs/spec.md">Spec reference</a> ·
76
+ <a href="server/">Render API</a>
77
+ </p>
78
+
79
+ <p align="center">
80
+ <img alt="license" src="https://img.shields.io/badge/license-MIT-black">
81
+ <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-black">
82
+ <img alt="go" src="https://img.shields.io/badge/go-1.26%2B-black">
83
+ <img alt="mcp" src="https://img.shields.io/badge/MCP-server-black">
84
+ </p>
85
+
86
+ ---
87
+
88
+ <p align="center"><img src="site/media/demo.gif" alt="The cardbox app: a plain-text script becomes a finished video" width="860"></p>
89
+
90
+ <p align="center"><b><a href="https://aryainguz.github.io/cardbox">Watch the 80-second explainer</a></b>: made with cardbox, narrated in my cloned voice.</p>
91
+
92
+ ## No paid AI needed
93
+
94
+ cardbox's core needs **no paid AI, no API keys and no account**. Write what you want to say in plain text, pick a look, and it makes the video on your own computer, voice included.
95
+
96
+ **Want more?** Connect your AI assistant (Claude, Cursor or any MCP client). It can write the script from one sentence, find openly licensed images, pick animated scenes and time them to your words, and check preview frames before rendering.
97
+
98
+ | | Without AI (free, the core) | With your AI assistant (optional) |
99
+ | --- | --- | --- |
100
+ | Script | You write plain text | Written from one sentence |
101
+ | Visuals | Templates, themes, your own images and clips | + licensed image search, scene choice, word-timed animations |
102
+ | Voice | Your cloned voice, or the computer's voice | Same |
103
+ | Cost | Free | Whatever your assistant costs |
104
+
105
+ ## Why cardbox
106
+
107
+ Making a short explainer video by hand means scripting, recording, re-recording the line you fluffed, cutting, captioning, animating and syncing it all. With cardbox you either **ask your AI assistant** for the video, or **write what you want to say**:
108
+
109
+ ```text
110
+ One step. Any size. Your phone finds one contact out of ten thousand in a single step.
111
+
112
+ # 1 million checks
113
+ Searching names one by one gets slower as your list grows.
114
+
115
+ # 1 step, at any size
116
+ A hash table turns a name into the exact shelf where it lives.
117
+
118
+ Follow for more computer science, explained simply.
119
+ ```
120
+
121
+ ```bash
122
+ cardbox make script.txt --format vertical --voice me --render # → script.mp4 + caption.txt (or just use the app)
123
+ ```
124
+
125
+ Each paragraph becomes one beat. The first is the hook, the last is the closing card, a `# headline` sets what's on screen, and a headline that starts with a number becomes a big stat card.
126
+
127
+ Want full control (animated scenes, images, word-timed animations)? The same video as a spec:
128
+
129
+ ```yaml
130
+ title: How a hash table finds anything instantly
131
+ format: vertical # vertical · landscape · square
132
+ theme: midnight # 7 themes, or any accent color
133
+ voice: me # your cloned voice · system · none
134
+ beats:
135
+ - kind: hook
136
+ text: One step. Any size.
137
+ say: Your phone finds one contact out of ten thousand in a single step.
138
+ - kind: scene
139
+ scene: counter
140
+ head: So the lookup is
141
+ say: Finding Priya takes one step, whether you have ten contacts or ten million.
142
+ params: {to: 1, label: step, on: one} # fires the moment you say "one"
143
+ - kind: end
144
+ text: Follow for more
145
+ say: Follow for more computer science, explained simply.
146
+ ```
147
+
148
+ ## What makes it different
149
+
150
+ - 🎙️ **Your voice, cloned on your machine.** Read ten short lines in a browser page (about a minute), and every video is narrated in your voice. A consent statement is the first thing recorded.
151
+ - 👂 **It checks its own narration.** Every line is transcribed with Whisper and compared with the script. If a word came out slurred or skipped, cardbox re-records that line with a new seed. No more listening to every take.
152
+ - ⏱️ **Animations land on the word.** `on: billion` starts a counter the instant you say "billion". Captions highlight each word as it's spoken.
153
+ - 🤖 **An MCP server, built in.** Claude, Cursor or any MCP client can write the script, **look at preview frames** before rendering, find images, walk you through voice recording, and render.
154
+ - 🖼️ **License-safe images.** Search Openverse and Wikimedia Commons for reusable images only (CC0, public domain, CC BY, CC BY-SA). Credits are written into the post caption automatically.
155
+ - 📐 **One script, every platform.** `format: landscape` re-lays out every beat for YouTube; `square` for the LinkedIn feed.
156
+ - 🎵 **A soundtrack with no licensing questions.** A music bed is synthesized for each video (calm, upbeat or tense), with a hit on every cut and ducking under the voice.
157
+ - 🛠️ **Runs as a service.** A Go [render API](server/) with a worker pool, live progress over SSE, signed webhooks, idempotency and Prometheus metrics.
158
+
159
+ ## Quick start
160
+
161
+ ```bash
162
+ pipx install cardbox-video && cardbox # opens the app in your browser
163
+ ```
164
+
165
+ That's it if you have Google Chrome. Otherwise run `python -m playwright install chromium` once.
166
+ (`pip install cardbox-video` works too; `pipx` keeps it in its own environment.)
167
+
168
+ **Requirements**
169
+
170
+ | | |
171
+ | --- | --- |
172
+ | Python | 3.10, 3.11 or 3.12 |
173
+ | ffmpeg | `brew install ffmpeg` · `sudo apt install ffmpeg` · `winget install ffmpeg` |
174
+ | A browser | Google Chrome, or Chromium via Playwright (used to draw frames) |
175
+ | System voice (optional) | built into macOS; `espeak-ng` on Linux |
176
+ | Voice cloning (optional) | `cardbox-video[voice]`: about 3 GB of models. Apple Silicon or an NVIDIA GPU recommended. On CPU it works, but each line takes a while |
177
+
178
+ Tested on macOS (Apple Silicon) and Linux. Windows should work for everything except the system voice; reports welcome.
179
+
180
+ <p align="center"><img src="site/media/app.jpg" alt="The cardbox app" width="820"></p>
181
+
182
+ The app does everything without commands. You write the script, pick a format, theme, voice and music, drop in your own images or clips, record your voice, preview every frame, and render. You can then watch the video, download it and copy its caption. Your videos live in `~/Cardbox`, shared with the CLI and the MCP server.
183
+
184
+ **Your own voice.** Click *Record my voice* in the app (about a minute of reading). Cloning needs the voice extras:
185
+
186
+ ```bash
187
+ pip install "cardbox-video[voice]" # Chatterbox + Whisper (PyTorch; Apple Silicon or a GPU recommended)
188
+ ```
189
+
190
+ > The voice stack is heavy. To keep PyTorch out of your main environment, install `cardbox-video[voice]` in a separate one and point `CARDBOX_VOICE_PYTHON` at its interpreter.
191
+
192
+ **Your own images and clips.** Drop them into the app, or into the video's `media/` folder. Name them `1.jpg`, `2.mp4`, … to use them for beat 1, 2, … or write `@ photo.jpg` inside a paragraph.
193
+
194
+ ### Prefer the terminal?
195
+
196
+ ```bash
197
+ cardbox make script.txt --format landscape --voice me --render # plain text → video
198
+ cardbox new my-video && cardbox render my-video # a full YAML spec
199
+ cardbox preview my-video 1 # a PNG of beat 1
200
+ cardbox voice record me # the recording studio
201
+ cardbox doctor # check your setup
202
+ ```
203
+
204
+ ## Tutorial
205
+
206
+ A complete walkthrough, recorded live on a laptop: installing, the app, writing a script, formats and themes,
207
+ your own images, previewing, rendering, voice recording, the YAML spec, MCP and the CLI. The narration is the
208
+ author's cloned voice.
209
+
210
+ The recording itself is reproducible: [`tutorial/record.py`](tutorial/record.py) drives the real app in Chrome,
211
+ runs the real commands, and narrates with a recorded voice.
212
+
213
+ ## Use it from your AI assistant (MCP)
214
+
215
+ Add cardbox to your client's MCP config:
216
+
217
+ ```json
218
+ {
219
+ "mcpServers": {
220
+ "cardbox": { "command": "cardbox", "args": ["mcp"] }
221
+ }
222
+ }
223
+ ```
224
+
225
+ - **Claude Desktop:** `claude_desktop_config.json` · **Claude Code:** `claude mcp add cardbox -- cardbox mcp` · **Cursor:** `.cursor/mcp.json`
226
+
227
+ Then just ask: *"Make a 40-second vertical video explaining how DNS works, in my voice."*
228
+
229
+ | Tool | What it does |
230
+ | --- | --- |
231
+ | `make_video` | Plain-text script in, video spec out: the quickest start |
232
+ | `guide` | How to write a good video: spec format, scenes, writing rules |
233
+ | `create_reel` / `get_reel` / `list_reels` | Save and read specs (validation errors come back in plain English) |
234
+ | `preview_beat` | Returns a **frame image** so the assistant can see its work before rendering |
235
+ | `render_reel` | Renders the MP4 and the post caption, and flags lines the voice may have fumbled |
236
+ | `search_images` / `add_image` | Openly licensed images, downloaded and credited |
237
+ | `voice_status` / `voice_record` / `voice_test` | Record, check and try your cloned voice |
238
+ | `find_icons` / `spec_schema` | 1,900 Lucide icons; the full JSON Schema |
239
+
240
+ ## Formats, themes and styles
241
+
242
+ | Option | Values |
243
+ | --- | --- |
244
+ | `format` | `vertical` 1080×1920 (Reels, Shorts, TikTok) · `landscape` 1920×1080 (YouTube, LinkedIn) · `square` 1080×1080 (feeds) |
245
+ | `theme` | `midnight` · `ember` · `forest` · `neon` · `sunset` · `mono` · `paper` (light) |
246
+ | `accent` | any hex color, overriding the theme's accent |
247
+ | `font` | `sans` (Inter) · `mono` (JetBrains Mono) |
248
+ | `captions` | `highlight` · `box` · `minimal` · `none` |
249
+ | `music` | `calm` · `upbeat` · `tense` · `none` |
250
+
251
+ **Beat kinds:** `hook`, `text`, `stat`, `list`, `scene`, `end`. Hooks and text beats can take a `background` (an image with a slow push-in, or any scene).
252
+
253
+ **Scenes (13):** `counter` · `donut` · `bars` · `flow` · `terminal` · `mesh` · `grid` · `photo` · `logo` · `chat` · `script` · `voice` · `formats`. See [docs/spec.md](docs/spec.md) for every parameter.
254
+
255
+ **Pronunciation:** captions show `say`, but the voice reads `pronounce` when you set it. Write `say: SongsPK` with `pronounce: Songs P K`.
256
+
257
+ ## Render API (Go)
258
+
259
+ [`server/`](server/) is an HTTP service that queues renders and streams progress:
260
+
261
+ ```bash
262
+ cd server && go run ./cmd/cardbox-server # or: docker compose up
263
+ curl -X POST localhost:8080/v1/renders -H "Content-Type: application/yaml" --data-binary @video.yaml
264
+ curl -N localhost:8080/v1/renders/<id>/events # live progress (SSE)
265
+ ```
266
+
267
+ A ready image is published with every release: `docker run -p 8080:8080 ghcr.io/aryainguz/cardbox`.
268
+
269
+ It has a bounded worker pool with backpressure, cancellation, graceful drain, SQLite persistence with crash recovery, idempotency keys, reuse of identical renders, HMAC-signed webhooks with retries, API keys, per-key rate limits and Prometheus metrics. Details are in [server/README.md](server/README.md).
270
+
271
+ ## How it works
272
+
273
+ ```
274
+ spec.yaml ─► voice (clone · verify with Whisper · retry) ─► word timings
275
+ ─► cards (HTML) + scenes (canvas, cued to words) in a headless browser
276
+ ─► per-beat clips (captions word by word, progress bar) ─► concat
277
+ ─► synthesized music, ducked under the voice ─► video.mp4 + caption.txt
278
+ ```
279
+
280
+ Everything runs locally. Your recordings and your voice model never leave your machine.
281
+
282
+ ## Responsible use
283
+
284
+ Voice cloning is powerful. cardbox records a consent statement as the first take of every voice profile, and won't build a voice without it. **Only clone your own voice, or a voice you have explicit permission to use.** Don't use cardbox to impersonate anyone or to mislead people about who is speaking.
285
+
286
+ ## Contributing
287
+
288
+ New scenes, themes and caption styles are the easiest place to start: each scene is a single function in [`src/cardbox/scenes/library.js`](src/cardbox/scenes/library.js). See [CONTRIBUTING.md](CONTRIBUTING.md).
289
+
290
+ ## Credits
291
+
292
+ - [Chatterbox](https://github.com/resemble-ai/chatterbox) (MIT) for voice cloning, and [Whisper](https://github.com/openai/whisper) (MIT) for listening back.
293
+ - [Lucide](https://lucide.dev) icons (ISC), plus [Inter](https://rsms.me/inter/) and [JetBrains Mono](https://www.jetbrains.com/lp/mono/) (SIL OFL).
294
+ - [Openverse](https://openverse.org) and [Wikimedia Commons](https://commons.wikimedia.org) for openly licensed images.
295
+
296
+ MIT licensed.
@@ -0,0 +1,238 @@
1
+ <p align="center">
2
+ <img src="site/media/logo.svg" width="72" alt="cardbox logo">
3
+ </p>
4
+
5
+ <h1 align="center">cardbox</h1>
6
+
7
+ <p align="center">
8
+ <b>Script in. Video out. In your own voice.</b><br>
9
+ Narrated, captioned, animated videos for Reels, Shorts, YouTube and LinkedIn from plain text.<br>
10
+ No paid AI needed, and your AI assistant can drive it over MCP when you want more.
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://aryainguz.github.io/cardbox">Website</a> ·
15
+ <a href="#quick-start">Quick start</a> ·
16
+ <a href="#use-it-from-your-ai-assistant-mcp">MCP</a> ·
17
+ <a href="docs/spec.md">Spec reference</a> ·
18
+ <a href="server/">Render API</a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <img alt="license" src="https://img.shields.io/badge/license-MIT-black">
23
+ <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-black">
24
+ <img alt="go" src="https://img.shields.io/badge/go-1.26%2B-black">
25
+ <img alt="mcp" src="https://img.shields.io/badge/MCP-server-black">
26
+ </p>
27
+
28
+ ---
29
+
30
+ <p align="center"><img src="site/media/demo.gif" alt="The cardbox app: a plain-text script becomes a finished video" width="860"></p>
31
+
32
+ <p align="center"><b><a href="https://aryainguz.github.io/cardbox">Watch the 80-second explainer</a></b>: made with cardbox, narrated in my cloned voice.</p>
33
+
34
+ ## No paid AI needed
35
+
36
+ cardbox's core needs **no paid AI, no API keys and no account**. Write what you want to say in plain text, pick a look, and it makes the video on your own computer, voice included.
37
+
38
+ **Want more?** Connect your AI assistant (Claude, Cursor or any MCP client). It can write the script from one sentence, find openly licensed images, pick animated scenes and time them to your words, and check preview frames before rendering.
39
+
40
+ | | Without AI (free, the core) | With your AI assistant (optional) |
41
+ | --- | --- | --- |
42
+ | Script | You write plain text | Written from one sentence |
43
+ | Visuals | Templates, themes, your own images and clips | + licensed image search, scene choice, word-timed animations |
44
+ | Voice | Your cloned voice, or the computer's voice | Same |
45
+ | Cost | Free | Whatever your assistant costs |
46
+
47
+ ## Why cardbox
48
+
49
+ Making a short explainer video by hand means scripting, recording, re-recording the line you fluffed, cutting, captioning, animating and syncing it all. With cardbox you either **ask your AI assistant** for the video, or **write what you want to say**:
50
+
51
+ ```text
52
+ One step. Any size. Your phone finds one contact out of ten thousand in a single step.
53
+
54
+ # 1 million checks
55
+ Searching names one by one gets slower as your list grows.
56
+
57
+ # 1 step, at any size
58
+ A hash table turns a name into the exact shelf where it lives.
59
+
60
+ Follow for more computer science, explained simply.
61
+ ```
62
+
63
+ ```bash
64
+ cardbox make script.txt --format vertical --voice me --render # → script.mp4 + caption.txt (or just use the app)
65
+ ```
66
+
67
+ Each paragraph becomes one beat. The first is the hook, the last is the closing card, a `# headline` sets what's on screen, and a headline that starts with a number becomes a big stat card.
68
+
69
+ Want full control (animated scenes, images, word-timed animations)? The same video as a spec:
70
+
71
+ ```yaml
72
+ title: How a hash table finds anything instantly
73
+ format: vertical # vertical · landscape · square
74
+ theme: midnight # 7 themes, or any accent color
75
+ voice: me # your cloned voice · system · none
76
+ beats:
77
+ - kind: hook
78
+ text: One step. Any size.
79
+ say: Your phone finds one contact out of ten thousand in a single step.
80
+ - kind: scene
81
+ scene: counter
82
+ head: So the lookup is
83
+ say: Finding Priya takes one step, whether you have ten contacts or ten million.
84
+ params: {to: 1, label: step, on: one} # fires the moment you say "one"
85
+ - kind: end
86
+ text: Follow for more
87
+ say: Follow for more computer science, explained simply.
88
+ ```
89
+
90
+ ## What makes it different
91
+
92
+ - 🎙️ **Your voice, cloned on your machine.** Read ten short lines in a browser page (about a minute), and every video is narrated in your voice. A consent statement is the first thing recorded.
93
+ - 👂 **It checks its own narration.** Every line is transcribed with Whisper and compared with the script. If a word came out slurred or skipped, cardbox re-records that line with a new seed. No more listening to every take.
94
+ - ⏱️ **Animations land on the word.** `on: billion` starts a counter the instant you say "billion". Captions highlight each word as it's spoken.
95
+ - 🤖 **An MCP server, built in.** Claude, Cursor or any MCP client can write the script, **look at preview frames** before rendering, find images, walk you through voice recording, and render.
96
+ - 🖼️ **License-safe images.** Search Openverse and Wikimedia Commons for reusable images only (CC0, public domain, CC BY, CC BY-SA). Credits are written into the post caption automatically.
97
+ - 📐 **One script, every platform.** `format: landscape` re-lays out every beat for YouTube; `square` for the LinkedIn feed.
98
+ - 🎵 **A soundtrack with no licensing questions.** A music bed is synthesized for each video (calm, upbeat or tense), with a hit on every cut and ducking under the voice.
99
+ - 🛠️ **Runs as a service.** A Go [render API](server/) with a worker pool, live progress over SSE, signed webhooks, idempotency and Prometheus metrics.
100
+
101
+ ## Quick start
102
+
103
+ ```bash
104
+ pipx install cardbox-video && cardbox # opens the app in your browser
105
+ ```
106
+
107
+ That's it if you have Google Chrome. Otherwise run `python -m playwright install chromium` once.
108
+ (`pip install cardbox-video` works too; `pipx` keeps it in its own environment.)
109
+
110
+ **Requirements**
111
+
112
+ | | |
113
+ | --- | --- |
114
+ | Python | 3.10, 3.11 or 3.12 |
115
+ | ffmpeg | `brew install ffmpeg` · `sudo apt install ffmpeg` · `winget install ffmpeg` |
116
+ | A browser | Google Chrome, or Chromium via Playwright (used to draw frames) |
117
+ | System voice (optional) | built into macOS; `espeak-ng` on Linux |
118
+ | Voice cloning (optional) | `cardbox-video[voice]`: about 3 GB of models. Apple Silicon or an NVIDIA GPU recommended. On CPU it works, but each line takes a while |
119
+
120
+ Tested on macOS (Apple Silicon) and Linux. Windows should work for everything except the system voice; reports welcome.
121
+
122
+ <p align="center"><img src="site/media/app.jpg" alt="The cardbox app" width="820"></p>
123
+
124
+ The app does everything without commands. You write the script, pick a format, theme, voice and music, drop in your own images or clips, record your voice, preview every frame, and render. You can then watch the video, download it and copy its caption. Your videos live in `~/Cardbox`, shared with the CLI and the MCP server.
125
+
126
+ **Your own voice.** Click *Record my voice* in the app (about a minute of reading). Cloning needs the voice extras:
127
+
128
+ ```bash
129
+ pip install "cardbox-video[voice]" # Chatterbox + Whisper (PyTorch; Apple Silicon or a GPU recommended)
130
+ ```
131
+
132
+ > The voice stack is heavy. To keep PyTorch out of your main environment, install `cardbox-video[voice]` in a separate one and point `CARDBOX_VOICE_PYTHON` at its interpreter.
133
+
134
+ **Your own images and clips.** Drop them into the app, or into the video's `media/` folder. Name them `1.jpg`, `2.mp4`, … to use them for beat 1, 2, … or write `@ photo.jpg` inside a paragraph.
135
+
136
+ ### Prefer the terminal?
137
+
138
+ ```bash
139
+ cardbox make script.txt --format landscape --voice me --render # plain text → video
140
+ cardbox new my-video && cardbox render my-video # a full YAML spec
141
+ cardbox preview my-video 1 # a PNG of beat 1
142
+ cardbox voice record me # the recording studio
143
+ cardbox doctor # check your setup
144
+ ```
145
+
146
+ ## Tutorial
147
+
148
+ A complete walkthrough, recorded live on a laptop: installing, the app, writing a script, formats and themes,
149
+ your own images, previewing, rendering, voice recording, the YAML spec, MCP and the CLI. The narration is the
150
+ author's cloned voice.
151
+
152
+ The recording itself is reproducible: [`tutorial/record.py`](tutorial/record.py) drives the real app in Chrome,
153
+ runs the real commands, and narrates with a recorded voice.
154
+
155
+ ## Use it from your AI assistant (MCP)
156
+
157
+ Add cardbox to your client's MCP config:
158
+
159
+ ```json
160
+ {
161
+ "mcpServers": {
162
+ "cardbox": { "command": "cardbox", "args": ["mcp"] }
163
+ }
164
+ }
165
+ ```
166
+
167
+ - **Claude Desktop:** `claude_desktop_config.json` · **Claude Code:** `claude mcp add cardbox -- cardbox mcp` · **Cursor:** `.cursor/mcp.json`
168
+
169
+ Then just ask: *"Make a 40-second vertical video explaining how DNS works, in my voice."*
170
+
171
+ | Tool | What it does |
172
+ | --- | --- |
173
+ | `make_video` | Plain-text script in, video spec out: the quickest start |
174
+ | `guide` | How to write a good video: spec format, scenes, writing rules |
175
+ | `create_reel` / `get_reel` / `list_reels` | Save and read specs (validation errors come back in plain English) |
176
+ | `preview_beat` | Returns a **frame image** so the assistant can see its work before rendering |
177
+ | `render_reel` | Renders the MP4 and the post caption, and flags lines the voice may have fumbled |
178
+ | `search_images` / `add_image` | Openly licensed images, downloaded and credited |
179
+ | `voice_status` / `voice_record` / `voice_test` | Record, check and try your cloned voice |
180
+ | `find_icons` / `spec_schema` | 1,900 Lucide icons; the full JSON Schema |
181
+
182
+ ## Formats, themes and styles
183
+
184
+ | Option | Values |
185
+ | --- | --- |
186
+ | `format` | `vertical` 1080×1920 (Reels, Shorts, TikTok) · `landscape` 1920×1080 (YouTube, LinkedIn) · `square` 1080×1080 (feeds) |
187
+ | `theme` | `midnight` · `ember` · `forest` · `neon` · `sunset` · `mono` · `paper` (light) |
188
+ | `accent` | any hex color, overriding the theme's accent |
189
+ | `font` | `sans` (Inter) · `mono` (JetBrains Mono) |
190
+ | `captions` | `highlight` · `box` · `minimal` · `none` |
191
+ | `music` | `calm` · `upbeat` · `tense` · `none` |
192
+
193
+ **Beat kinds:** `hook`, `text`, `stat`, `list`, `scene`, `end`. Hooks and text beats can take a `background` (an image with a slow push-in, or any scene).
194
+
195
+ **Scenes (13):** `counter` · `donut` · `bars` · `flow` · `terminal` · `mesh` · `grid` · `photo` · `logo` · `chat` · `script` · `voice` · `formats`. See [docs/spec.md](docs/spec.md) for every parameter.
196
+
197
+ **Pronunciation:** captions show `say`, but the voice reads `pronounce` when you set it. Write `say: SongsPK` with `pronounce: Songs P K`.
198
+
199
+ ## Render API (Go)
200
+
201
+ [`server/`](server/) is an HTTP service that queues renders and streams progress:
202
+
203
+ ```bash
204
+ cd server && go run ./cmd/cardbox-server # or: docker compose up
205
+ curl -X POST localhost:8080/v1/renders -H "Content-Type: application/yaml" --data-binary @video.yaml
206
+ curl -N localhost:8080/v1/renders/<id>/events # live progress (SSE)
207
+ ```
208
+
209
+ A ready image is published with every release: `docker run -p 8080:8080 ghcr.io/aryainguz/cardbox`.
210
+
211
+ It has a bounded worker pool with backpressure, cancellation, graceful drain, SQLite persistence with crash recovery, idempotency keys, reuse of identical renders, HMAC-signed webhooks with retries, API keys, per-key rate limits and Prometheus metrics. Details are in [server/README.md](server/README.md).
212
+
213
+ ## How it works
214
+
215
+ ```
216
+ spec.yaml ─► voice (clone · verify with Whisper · retry) ─► word timings
217
+ ─► cards (HTML) + scenes (canvas, cued to words) in a headless browser
218
+ ─► per-beat clips (captions word by word, progress bar) ─► concat
219
+ ─► synthesized music, ducked under the voice ─► video.mp4 + caption.txt
220
+ ```
221
+
222
+ Everything runs locally. Your recordings and your voice model never leave your machine.
223
+
224
+ ## Responsible use
225
+
226
+ Voice cloning is powerful. cardbox records a consent statement as the first take of every voice profile, and won't build a voice without it. **Only clone your own voice, or a voice you have explicit permission to use.** Don't use cardbox to impersonate anyone or to mislead people about who is speaking.
227
+
228
+ ## Contributing
229
+
230
+ New scenes, themes and caption styles are the easiest place to start: each scene is a single function in [`src/cardbox/scenes/library.js`](src/cardbox/scenes/library.js). See [CONTRIBUTING.md](CONTRIBUTING.md).
231
+
232
+ ## Credits
233
+
234
+ - [Chatterbox](https://github.com/resemble-ai/chatterbox) (MIT) for voice cloning, and [Whisper](https://github.com/openai/whisper) (MIT) for listening back.
235
+ - [Lucide](https://lucide.dev) icons (ISC), plus [Inter](https://rsms.me/inter/) and [JetBrains Mono](https://www.jetbrains.com/lp/mono/) (SIL OFL).
236
+ - [Openverse](https://openverse.org) and [Wikimedia Commons](https://commons.wikimedia.org) for openly licensed images.
237
+
238
+ MIT licensed.
@@ -0,0 +1,16 @@
1
+ # Security
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please report security issues privately through GitHub's **Report a vulnerability** button (Security tab), not in a
6
+ public issue. You'll get a reply within a few days.
7
+
8
+ ## What to know
9
+
10
+ - **The app and the voice studio** listen on `127.0.0.1` only. They refuse requests whose `Host` isn't a loopback
11
+ name (DNS rebinding) and refuse changes coming from another website's origin (cross-site requests).
12
+ - **Your voice** recordings and cloned voice stay on your machine, in `~/Cardbox/voices`. Nothing is uploaded.
13
+ - **The render API** (`server/`) is meant to run behind your own network controls. Set `CARDBOX_API_KEYS` before
14
+ exposing it, and a strong `CARDBOX_WEBHOOK_SECRET` if you use webhooks. Specs are rendered by a local
15
+ subprocess; don't expose the API to untrusted users without sandboxing the worker.
16
+ - **Voice cloning** must only be used with your own voice or one you have explicit permission to use.