A bot that makes original long-form YouTube videos on its own: public-domain classics of the mind (The
Kybalion, James Allen, Marcus Aurelius, Emerson) explained in modern English and checked against modern psychology,
narrated by George, an older British storyteller (Kokoro bm_george). Every picture is chosen to show what
George is saying at that moment: stock footage checked by a free vision model, or a painting of the scene.
Captions, chapter titles and on-screen book quotes are burned in. Everything runs on free tiers.
It runs itself on GitHub Actions every morning, with no computer of yours switched on: daily checks, and on
video days it writes, narrates, renders, stores and delivers a video, then deletes the stored copy after posting.
Control it from a small web page (panel/) or from GitHub itself.
Start here:
| Document | What's in it |
|---|---|
| docs/GUIDE.md | How to use and steer the bot: the control panel, every control on GitHub, how it tells you things, Actions minutes, adding books |
| docs/HOW-IT-WORKS.md | How the AI pieces make a video and post it, step by step |
| docs/KEYS.md | Every key and token, and what it does |
| docs/STATUS.md | Is it finished? What's proven, what isn't, decisions for you, and your checklist |
| docs/DEPLOY.md | Setup, the storage rules, and every caveat with its fix |
| docs/REQUESTS.md | Everything you've asked for or raised, and what was done |
| docs/DEVLOG.md | Every change, newest first: what, why, and what was checked |
Steer the bot in steering/instructions.md (type plain English) or upload a PDF, Word or text document into
steering/references/.
You need uv and an ffmpeg built with libass (for on-screen text).
| System | Install |
|---|---|
| macOS | brew install uv ffmpeg-full (the plain ffmpeg formula has no libass; ffmpeg-full is found automatically) |
| Ubuntu / Debian | sudo apt-get install ffmpeg, then install uv |
| Small or Windows machine | Use GitHub Codespaces or Docker (below): nothing to install locally |
Then, in the project folder:
uv sync --frozen # exact package versions from uv.lock (Python 3.12 is fetched if needed)
cp .env.example .env # then paste your keys into .env
uv run python -m owd fetch-models # pinned voice and speech-check models (about 500 MB, once)
uv run python -m pytest -q # fast tests; add -m "slow or not slow" for all of themuv run python -m owd write --chapter 2 # writes storyboards/<date>-<title>.toml (about 5 to 10 minutes)
# read and edit the storyboard if you like, then:
uv run python -m owd render storyboards/<the file it printed>The finished files land in output/videos/<name>/: video.mp4, thumbnail.jpg, captions.srt,
metadata.json (title, description with chapters and credits) and review.md, the checklist to go through
before posting (title options, every factual claim, every quote, the narration check).
| Command | What it does |
|---|---|
python -m owd run [--angle "..."] |
Everything at once, as the schedule does: next chapter → script → video → stored → delivered |
python -m owd write --chapter N [--book ID] [--angle "..."] |
Write a long-form storyboard from one chapter of a book in channel.toml |
python -m owd render STORYBOARD [--preview] |
Make the video. --preview downloads smaller footage (for slow connections) |
python -m owd cleanup |
Apply the storage rules: delete stored copies that are due |
python -m owd storage |
List the stored videos and when each copy will be deleted |
python -m owd add-book NUMBER [--chapters "A, B"] [--cite "..."] |
Add a public-domain book by its Project Gutenberg number, after checking its chapters |
python -m owd plan |
Is today a video day? (The daily run asks first) |
python -m owd youtube-login |
Sign in to YouTube once (opens a browser) and print the token for automatic posting |
python -m owd steering |
Read the steering documents and condense long uploads |
python -m owd news [--topic words] [--kind platform] |
Research stories the scripts can cite, or YouTube platform news |
python -m owd voices |
Read a sample paragraph in each candidate voice |
python -m owd fetch-models |
Download the pinned models ahead of time |
python -m owd demo |
A no-API technical test (generated backgrounds) |
Prefix each with uv run outside the dev container.
- Script (
write): one chapter of a public-domain book (as numbered sentences), recent research from the news feeds, and the owner's steering go to free language models (OpenRouter first, then Gemini). Quotes come back as sentence numbers, so the bot inserts the book's exact words. The hook opens a question that only the end answers, chapters end on cliffhangers, and[pause]marks a beat of silence before a reveal. Short drafts are expanded one chapter at a time. Every factual claim is listed for review. - Storyboard (
storyboards/*.toml): chapters and scenes. Each scene has its narration, a footage search and a painting description. Paragraphs starting with>are book quotes. Edit freely before rendering. - Quote check: every quote must appear word for word in its source text (
sources/), or nothing renders. - Narration: Kokoro reads the script, with word timings for cuts, captions and on-screen text.
- Narration check: faster-whisper transcribes the audio and compares it with the script.
- Pictures that match the words: for each scene, a free vision model (Gemini Flash-Lite) looks at the best Pixabay clips next to the sentence and scores them; the best one that fits is used. If none fits, the scene gets a painting of the moment (Cloudflare FLUX, free daily allowance), or the closest clip, flagged for review. One picture per scene, so it never wanders away from the words.
- Video: crossfades inside a chapter, a dip through black between chapters, chapter titles, quote cards (footage dimmed, the book's words in Libre Baskerville) and captions (spoken word in gold). -14 LUFS.
- Storage, delivery and cleanup: every video is first stored in the cloud (a GitHub release in this repository). Then either an issue tells the owner to post it, or the bot uploads and schedules it on YouTube (and hands the stored copy to the owner if YouTube refuses or keeps it private). A copy is deleted 7 days after the video is posted, and at most 4 are stored at once. Rules and caveats: docs/DEPLOY.md.
steering/instructions.mdandsteering/references/: how the bot should write (titles, retention, voice, visuals, YouTube rules). Plain English; read before every script.channel.toml: voice and speed, video length, posting schedule and mode, storage rules, books, language models (in fallback order), news feeds and research keywords..env(local) or CI/Codespaces secrets: the API keys listed in.env.example.
GitHub Codespaces runs this project in the browser on GitHub's machines. Open the repository on
GitHub, then Code → Codespaces → Create codespace. The dev container (.devcontainer/) builds
from the same Dockerfile as the cloud, with packages and models already inside. Add the API keys at
github.com/settings/codespaces. A free personal account includes 120 core-hours a month, which is
about 60 hours on the 2-core machine. Stop the codespace when you're done so the hours aren't used up.
Docker works the same on any machine that runs containers:
docker build -t owd .
docker run --rm --env-file .env -v "$PWD/output:/app/output" -v "$PWD/storyboards:/app/storyboards" owd \
python -m owd write --chapter 2uv.lockpins every Python package with hashes, for macOS and Linux (CPU-only torch on Linux).owd/models.pypins each model to an exact Hugging Face commit.- The caption font (Anton, SIL Open Font License) and the book texts are in the repository.
.github/workflows/tests.ymlruns every test on a clean Ubuntu runner on each push.image.ymlbuilds the Docker image and runs the tests inside it.
- It explains and tests the books; it never just reads them aloud (YouTube doesn't pay for that).
- Quotes are checked word for word against the public-domain source.
- No promises of guaranteed results, no "you were chosen" bait, no health or money advice.
- The narrator never claims to be a human expert.
- Living teachers can be discussed, but their recordings, footage and text are never used.
- Footage creators and sources are credited in every description.