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.
- cardbox_video-0.1.0/.gitignore +12 -0
- cardbox_video-0.1.0/CHANGELOG.md +19 -0
- cardbox_video-0.1.0/CONTRIBUTING.md +32 -0
- cardbox_video-0.1.0/Dockerfile +19 -0
- cardbox_video-0.1.0/LICENSE +21 -0
- cardbox_video-0.1.0/PKG-INFO +296 -0
- cardbox_video-0.1.0/README.md +238 -0
- cardbox_video-0.1.0/SECURITY.md +16 -0
- cardbox_video-0.1.0/docker-compose.yml +11 -0
- cardbox_video-0.1.0/docs/spec.md +142 -0
- cardbox_video-0.1.0/examples/README.md +17 -0
- cardbox_video-0.1.0/examples/hash-table/reel.yaml +56 -0
- cardbox_video-0.1.0/examples/promo/promo-explainer.yaml +84 -0
- cardbox_video-0.1.0/examples/promo/promo-reel.yaml +40 -0
- cardbox_video-0.1.0/examples/wifi.txt +9 -0
- cardbox_video-0.1.0/pyproject.toml +69 -0
- cardbox_video-0.1.0/server/.gitignore +2 -0
- cardbox_video-0.1.0/server/README.md +75 -0
- cardbox_video-0.1.0/server/cmd/cardbox-server/main.go +123 -0
- cardbox_video-0.1.0/server/go.mod +17 -0
- cardbox_video-0.1.0/server/go.sum +50 -0
- cardbox_video-0.1.0/server/internal/api/api.go +427 -0
- cardbox_video-0.1.0/server/internal/api/api_test.go +197 -0
- cardbox_video-0.1.0/server/internal/jobs/hub.go +69 -0
- cardbox_video-0.1.0/server/internal/jobs/job.go +55 -0
- cardbox_video-0.1.0/server/internal/jobs/jobs_test.go +173 -0
- cardbox_video-0.1.0/server/internal/jobs/manager.go +206 -0
- cardbox_video-0.1.0/server/internal/ratelimit/ratelimit.go +64 -0
- cardbox_video-0.1.0/server/internal/ratelimit/ratelimit_test.go +33 -0
- cardbox_video-0.1.0/server/internal/runner/runner.go +118 -0
- cardbox_video-0.1.0/server/internal/runner/runner_test.go +37 -0
- cardbox_video-0.1.0/server/internal/store/store.go +197 -0
- cardbox_video-0.1.0/server/internal/webhook/webhook.go +91 -0
- cardbox_video-0.1.0/server/internal/webhook/webhook_test.go +58 -0
- cardbox_video-0.1.0/src/cardbox/__init__.py +3 -0
- cardbox_video-0.1.0/src/cardbox/__main__.py +3 -0
- cardbox_video-0.1.0/src/cardbox/app.py +325 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-Bold.ttf +0 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-OFL.txt +93 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-Regular.ttf +0 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/Inter-SemiBold.ttf +0 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-OFL.txt +93 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-Regular.ttf +0 -0
- cardbox_video-0.1.0/src/cardbox/assets/fonts/JetBrainsMono-SemiBold.ttf +0 -0
- cardbox_video-0.1.0/src/cardbox/assets/icons/LICENSE-lucide.txt +43 -0
- cardbox_video-0.1.0/src/cardbox/assets/icons/lucide.json +1 -0
- cardbox_video-0.1.0/src/cardbox/browser.py +61 -0
- cardbox_video-0.1.0/src/cardbox/captions.py +83 -0
- cardbox_video-0.1.0/src/cardbox/cards.py +203 -0
- cardbox_video-0.1.0/src/cardbox/cli.py +230 -0
- cardbox_video-0.1.0/src/cardbox/formats.py +40 -0
- cardbox_video-0.1.0/src/cardbox/icons.py +44 -0
- cardbox_video-0.1.0/src/cardbox/localguard.py +43 -0
- cardbox_video-0.1.0/src/cardbox/mcp_server.py +233 -0
- cardbox_video-0.1.0/src/cardbox/media.py +148 -0
- cardbox_video-0.1.0/src/cardbox/music.py +97 -0
- cardbox_video-0.1.0/src/cardbox/render.py +267 -0
- cardbox_video-0.1.0/src/cardbox/scenes/library.js +267 -0
- cardbox_video-0.1.0/src/cardbox/scenes/runtime.js +173 -0
- cardbox_video-0.1.0/src/cardbox/scenes.py +129 -0
- cardbox_video-0.1.0/src/cardbox/script.py +112 -0
- cardbox_video-0.1.0/src/cardbox/spec.py +173 -0
- cardbox_video-0.1.0/src/cardbox/templates/app.html +355 -0
- cardbox_video-0.1.0/src/cardbox/templates/reel.yaml +31 -0
- cardbox_video-0.1.0/src/cardbox/templates/studio.html +108 -0
- cardbox_video-0.1.0/src/cardbox/themes.py +44 -0
- cardbox_video-0.1.0/src/cardbox/voice/__init__.py +1 -0
- cardbox_video-0.1.0/src/cardbox/voice/align.py +101 -0
- cardbox_video-0.1.0/src/cardbox/voice/engines.py +158 -0
- cardbox_video-0.1.0/src/cardbox/voice/profile.py +145 -0
- cardbox_video-0.1.0/src/cardbox/voice/studio.py +141 -0
- cardbox_video-0.1.0/src/cardbox/voice/worker.py +110 -0
- cardbox_video-0.1.0/src/cardbox/workspace.py +60 -0
- cardbox_video-0.1.0/tests/conftest.py +8 -0
- cardbox_video-0.1.0/tests/test_align.py +51 -0
- cardbox_video-0.1.0/tests/test_app.py +91 -0
- cardbox_video-0.1.0/tests/test_captions.py +32 -0
- cardbox_video-0.1.0/tests/test_formats_themes.py +38 -0
- cardbox_video-0.1.0/tests/test_mcp.py +41 -0
- cardbox_video-0.1.0/tests/test_media_music.py +35 -0
- cardbox_video-0.1.0/tests/test_script.py +71 -0
- cardbox_video-0.1.0/tests/test_spec.py +48 -0
- cardbox_video-0.1.0/tests/test_voice_profile.py +41 -0
|
@@ -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.
|