hyperframes-ai-video-generation

Turn a topic prompt into a polished, AI-voiced vertical YouTube Short. One command, fire and forget.

archon workflow run create-classic-short --no-worktree "What is RAG?"

That's it. The workflow researches the topic, drafts a paced narration, generates TTS (free Kokoro locally, or paid ElevenLabs — your choice), edits an HTML+GSAP composition, lints it, and opens a browser preview. Render is always manual — npx hyperframes render videos/<slug> when you're ready.

The repo ships with three templates out of the box — classic (brand-neutral default, blue + dark), archon (Archon-branded), anthropic (Anthropic-branded) — and you can build your own brand by asking your coding agent.

🚀 Just tell your coding agent to do it

The fastest way through this whole README is to not read it yourself. Open this repo in Claude Code (or any agentic coding tool) and paste one of these:

To generate a video with a shipped template:

"Read the README and set everything up so I can generate my first video. The topic is: [your idea or URL here]."

To build your own brand/style first, then generate:

"Read the README. Look at templates/shorts/classic/, templates/shorts/archon/, and templates/shorts/anthropic/ as references, then create a new short template for [your brand name, URL, or vibe — e.g. "my SaaS at example.com", "a cyberpunk dev tool", "Linear"]. Pick the palette, gradient, wordmark, and CTA URL yourself based on the brand. When the template is built and lints clean, generate my first video with it. The topic is: [your idea or URL here]."

The agent will install the system deps, walk you through any keys it needs (Kokoro is free / no key required; ElevenLabs needs an API key), optionally clone + restyle a template for your brand, run the matching archon workflow run create-<brand>-short, and hand you the preview URL. You just supply the inputs.

The stack: Archon (workflow harness) + Claude Code (planning + composition editing) + HyperFrames (HTML/GSAP video framework) + Kokoro (free local TTS, default) or ElevenLabs (paid premium TTS) — both return word-level timestamps. Total runtime per short: ~20-30 min depending on research depth.

Quick Start

🤖 For the coding agent — ask the user these two questions first

If you're an AI coding agent reading this README to set things up, do not assume defaults. Ask the user these two questions and tailor everything below to their answers.

1. Which TTS engine do you want — Kokoro or ElevenLabs?

• Kokoro — free, local, no API key, Apache-licensed, ~325MB one-time model download, runs on CPU. High quality (MOS 4.5). Preset voices only — no voice cloning.
• ElevenLabs — paid (~$5/M chars), premium quality, supports Instant Voice Cloning. Requires an ELEVENLABS_API_KEY from elevenlabs.io.

Install ONLY the deps for the engine they picked (don't install both) and configure ONLY that engine's block in .archon/.env.

If they pick ElevenLabs, walk them through getting set up — don't just point them at a link. Specifically:

1. Tell them to create an ElevenLabs account at https://elevenlabs.io. The free tier is fine for testing (10,000 chars/month ≈ 5-6 shorts); the Starter plan ($5/mo, 30,000 chars) is the realistic minimum for regular use.
2. Walk them to the API key page: log in → click their avatar (top-right) → "API Keys" → "Create API Key" → copy the value. Tell them to paste it as ELEVENLABS_API_KEY=... in .archon/.env. Never commit this file — it's already gitignored.
3. Ask whether they want a preset voice or their own voice clone:
   • Preset voice — set ELEVENLABS_VOICE_ID=nPczCjzI2devNBz1zQrb (Brian, mature American male — the documented default for shorts). Other presets: Adam pNInz6obpgDQGcFmaJgB, Daniel onwK4e9ZLuTAKqWW03F9. Or run python scripts/list_voices.py after setup to browse.
   • Voice clone — direct them to elevenlabs.io → "Voices" → "Add Voice" → "Instant Voice Clone", upload 1-3 minutes of clean audio (their own voice for personalized narration), then copy the new voice's ID from the voice page URL or the voice library detail panel.
4. Confirm the rest of the tuning vars are filled in with the tested-good shorts defaults from .env.example (these are NOT the ElevenLabs platform defaults — the platform defaults sound flatter on shorts):
   • ELEVENLABS_MODEL_ID=eleven_multilingual_v2
   • ELEVENLABS_STABILITY=0.40
   • ELEVENLABS_SIMILARITY_BOOST=0.75
   • ELEVENLABS_STYLE=0.70
   • ELEVENLABS_SPEED_SHORTS=1.15
   • ELEVENLABS_USE_SPEAKER_BOOST=true
5. Verify: after .archon/.env is filled in, run a one-line smoke test before kicking off the full workflow:

   python -c "import os; from dotenv import load_dotenv; load_dotenv('.archon/.env'); print('OK' if os.getenv('ELEVENLABS_API_KEY') else 'MISSING KEY')"
   

   If it prints MISSING KEY, the .env file isn't being read — most likely the path is wrong or the line is commented out.

The full tuning matrix (what each knob does, when to adjust it) is in .env.example and the "Voice tuning" section below — surface that to the user if they ask "what does X setting do?"

2. Do you want to use one of the shipped templates as-is, or customize the look first?

• Use shipped as-is — pick classic (brand-neutral default), archon, or anthropic. No template work needed; go straight to step 5 (run the workflow).
• Customize the style only (reskin) — different palette, wordmark, and CTA URL, but the same scene layouts as the source template. Route to "Adding your own template" → Option A or B.
• Customize the scenes too (redesign) — different visual layouts inside each phase, so the video doesn't look identical to the shipped templates. Route to "Adding your own template" → Option C.

If they want to customize, ask a follow-up: "briefly describe what you want." Brand name, target website, vibe, palette inspiration, any specific scene layouts they care about. One or two sentences is enough for Option B; Option C benefits from a per-phase layout direction (see the alternatives table in that section).

Only after both answers are confirmed: proceed with the install steps below, then build/pick the template, then run the matching workflow.

Three install commands, one config file, one workflow run.

1. Install Claude Code

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

Then claude /login once to authenticate.

2. Install Archon (binary, no setup wizard needed)

# macOS / Linux
curl -fsSL https://archon.diy/install | bash

# Windows (PowerShell)
irm https://archon.diy/install.ps1 | iex

# Homebrew
brew install coleam00/archon/archon

Point Archon at Claude Code (binary installs don't bundle it):

# macOS / Linux / WSL — add to ~/.bashrc or ~/.zshrc
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"

# Windows (PowerShell profile)
$env:CLAUDE_BIN_PATH = "$env:USERPROFILE\.local\bin\claude.exe"

You do NOT need to run archon setup — that's only for the source-install path (which clones the Archon repo). The binary just works against this repo's pre-configured .archon/ directory. On first workflow run, Archon lazily creates ~/.archon/archon.db (SQLite, single file, no schema setup required).

3. Install system deps

You need Node ≥22, Python ≥3.10, ffmpeg, jq, and bun.

# macOS (Homebrew)
brew install node python ffmpeg jq oven-sh/bun/bun

# Windows (winget + bun installer)
winget install OpenJS.NodeJS Python.Python.3.12 Gyan.FFmpeg jqlang.jq
irm bun.sh/install.ps1 | iex

# Linux (Debian / Ubuntu) — apt's `nodejs` is too old on most LTS releases;
# use NodeSource for Node 22.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs python3 python3-venv python3-pip ffmpeg jq unzip
curl -fsSL https://bun.sh/install | bash

Then the Python TTS deps. Use a virtualenv so pip doesn't fight your system Python (Ubuntu 24.04+ blocks bare pip install via PEP 668):

python3 -m venv .venv
source .venv/bin/activate           # macOS / Linux
# .venv\Scripts\activate            # Windows PowerShell

# Pick ONE of these — see "TTS engines" below for the tradeoff.

# Free local TTS (Kokoro, no API key)
pip install kokoro python-dotenv soundfile numpy

# OR commercial TTS (ElevenLabs, paid API)
pip install elevenlabs python-dotenv

If you chose Kokoro, also install espeak-ng system-wide (needed for phoneme conversion):

# macOS
brew install espeak

# Ubuntu / Debian
sudo apt install espeak-ng

# Windows: download the .msi installer
# https://github.com/espeak-ng/espeak-ng/releases

Activate the venv (source .venv/bin/activate) in any shell where you'll run archon workflow run — the workflow's TTS step calls python scripts/kokoro-tts.py or python scripts/elevenlabs-tts.py and needs the chosen package on the active interpreter's path.

4. Clone + configure

git clone https://github.com/coleam00/hyperframes-ai-video-generation
cd hyperframes-ai-video-generation
cp .env.example .archon/.env

Open .archon/.env and fill in the TTS settings for whichever engine you picked:

For Kokoro (free, local):

• KOKORO_VOICE=af_heart (or any voice from the Kokoro voice catalog)
• KOKORO_LANG_CODE=a (a=American English, b=British, j=Japanese, etc.)
• Speed defaults already shipped — see .env.example.

For ElevenLabs (paid, premium quality):

• ELEVENLABS_API_KEY — your key from elevenlabs.io
• ELEVENLABS_VOICE_ID — either your clone's ID or a preset (Brian nPczCjzI2devNBz1zQrb is the documented default)
• The other 7 settings ship with the tested-good defaults for shorts (see "Voice tuning" below).

5. Run it

Pick a template aesthetic. classic is the default — brand-neutral, works for any topic:

# Classic (brand-neutral dark theme, bright blue + sky blue) — DEFAULT
archon workflow run create-classic-short --no-worktree "Your topic here"

# Archon-themed (dark blue + cyan/magenta gradient hero)
archon workflow run create-archon-short --no-worktree "Your topic here"

# Anthropic-themed (near-black + warm orange/cream gradient hero)
archon workflow run create-anthropic-short --no-worktree "Your topic here"

Want a different brand? See "Want a different brand or look?" below — the fastest path is asking your coding agent to clone an existing template and re-skin it.

20-30 minutes later the studio opens with the finished short. Render with npx hyperframes render videos/<slug> -o videos/<slug>/out/<slug>.mp4.

---

What the workflow does

Each template ships with its own three-node Archon workflow at .archon/workflows/create-<template>-short.yaml — all three are structurally identical, only the template path and brand strings differ:

1. parse-input (bash + bun) — derives {topic, slug, duration, title} from the topic phrase.
2. precheck (bash) — verifies templates/shorts/<template>/ exists, videos/<slug>/ doesn't, npx is on PATH.
3. create-short (Claude) — runs the matching playbook at .claude/skills/diy-yt-creator/new-<template>-short.md:
   • Researches the topic (WebFetch + WebSearch grounding)
   • Drafts narration paced to the duration target — with mandatory SSML <break> tags between sentences and natural abbreviations (MIT, not M I T)
   • Generates TTS via python scripts/kokoro-tts.py --shorts (default, free) or python scripts/elevenlabs-tts.py --shorts --no-chunk (paid)
   • Computes phase-transition anchors via python scripts/compute_timings.py (strips break tags, filters phantom punctuation)
   • Edits videos/<slug>/index.html — title, content, GSAP timeline anchors, audio element
   • Runs npx hyperframes lint + inspect until clean
   • Launches npx hyperframes preview in the background
   • Prints the preview URL + the manual render command

Want a different brand or look?

The repo ships three templates out of the box at templates/shorts/:

Template	Aesthetic	Workflow
classic/ (default)	Deep navy + bright blue / sky blue gradient hero, "YOUR BRAND" wordmark, your-domain.com CTA — placeholders ready for you to swap	archon workflow run create-classic-short --no-worktree "<topic>"
archon/	Dark blue + cyan→magenta gradient hero, Archon logo banner, archon.diy CTA	archon workflow run create-archon-short --no-worktree "<topic>"
anthropic/	Near-black + warm orange→cream gradient hero, "ANTHROPIC" wordmark banner, anthropic.com CTA	archon workflow run create-anthropic-short --no-worktree "<topic>"

The classic template is the brand-neutral default. Use it for any topic that isn't specifically about Archon or Anthropic — you'll need to swap the YOUR BRAND wordmark and your-domain.com CTA for your own (one-line CSS edits, documented in the template's README).

All three templates share the same 4-phase rhythm (Phase 1 → 2 → 3 → 4 across ~24s), the same playbook contract (phase IDs #phase1-4, timing constants T1/T2/T3 and P2/P3/P4, the slam_t shake anchor, the audio insertion point), and the same compute_timings.py math.

What can differ between templates: the visual pattern inside each phase. Two templates can share Phase 2 as "the 6-12s slot" but use completely different layouts to fill it — archon/ uses a side-by-side stat-pill row; anthropic/ uses a single oversized metric with a hairline rule; you could write one that uses a full-screen quote with attribution. Same rhythm, different scene design.

Think of the phase contract as the song's tempo and bar count, and the per-template HTML/CSS as the chord voicing and instrumentation.

Adding your own template (let your coding agent do it)

If neither shipped template fits, ask your coding agent to clone one and modify it. Three options below, ordered by how much design effort the agent is taking on. Pick the one that matches what you actually want — they get progressively more transformative.

Heads-up before you start: Option A and Option B produce a template that looks like the source template with a new coat of paint. If your goal is "my videos shouldn't look identical to Archon's or Anthropic's videos," you want Option C. The shipped templates intentionally share scene layouts within their phases — that's the reskin path. Visually distinct scenes are a separate, larger design pass.

Option A — reskin only (you have your brand specs ready)

Use this when you already know your palette, brand name, and CTA URL, and you're fine with the source template's scene layouts. Fastest path, fewest decisions delegated:

"Create a new short template at templates/shorts/<your-brand>/ by cloning templates/shorts/anthropic/ and restyling it for <your brand name>. Specifically:

1. Palette: --bg = <hex>, --accent-1 = <hex> (hero/signature accent), --accent-2 = <hex> (CTA), --accent-3 = <hex> (secondary), --accent-4 = <hex> (workhorse). The hero gradient text-fill should be --accent-1 → --accent-2.
2. Top banner: CSS-rendered wordmark reading "<BRAND IN ALL CAPS>" in the hero gradient, OR drop an SVG into assets/ and follow the swap pattern in templates/shorts/anthropic/DESIGN.md.
3. Default CTA URL: .
4. Update meta.json, hyperframes.json, DESIGN.md, README.md, PRONUNCIATION.md for the new brand. Keep class names (.cyan, .magenta, etc.) and phase IDs (#phase1-4, #p1-hero, #p2-pill-1/2, #p3-card-1/2/3, #p4-url, the T1/T2/T3 and P2/P3/P4 timing constants, slam_t, shake_offsets) identical to the source so compute_timings.py and the playbook work unchanged.
5. Add a sibling playbook at .claude/skills/diy-yt-creator/new-<brand>-short.md mirroring new-anthropic-short.md — same 11 steps, just with the new template path, palette names, and CTA URL.
6. Add an Archon workflow at .archon/workflows/create-<brand>-short.yaml and command at .archon/commands/create-<brand>-short.md mirroring the anthropic versions. Keep the parse-input logic identical; only the workflow name, description, template path, and command reference change.
7. Add the new template's row to the table in this repo's README and to .claude/skills/diy-yt-creator/SKILL.md.
8. Run npx hyperframes lint templates/shorts/<your-brand> to confirm clean."

Result: Same scenes as the source template, your brand colors and wordmark. ~5-10 minutes.

Option B — agent-designed reskin (you supply the vibe, agent picks the palette)

Use this when you don't want to pick hex codes yourself but still want a reskin (same scene layouts, your brand). Hand the agent inspiration and let it derive the palette:

"Look at the existing short templates at templates/shorts/archon/ and templates/shorts/anthropic/ as reference for the structure and design system. Then design a new short template for <your brand or vibe — e.g. "Linear", "a cyberpunk dev tool with green-on-black terminal vibes", "my SaaS company's brand at https://example.com">. You decide the palette, the gradient direction, the wordmark treatment, and the CTA URL — pick choices that match the brand's actual identity (visit the site if a URL was provided; otherwise use your judgment). Keep the scene layouts and all timing-contract IDs from the source template unchanged — this is a reskin pass, not a redesign. Create the template at templates/shorts/<slug>/ along with the playbook, workflow YAML, command file, and SKILL.md entry. When you're done, show me the palette you picked and why, run npx hyperframes lint templates/shorts/<slug> to confirm it's clean, and tell me how to invoke the new workflow."

Result: Same scenes as the source template, agent-picked brand identity. ~10-15 minutes.

Option C — redesign the scenes (different layouts, same phase rhythm)

Use this when you want your videos to look visually distinct from the shipped templates — not just a color swap, but actually different scene compositions in each phase. This is the answer to "why does my Anthropic short look just like the Archon one?"

The phase rhythm stays the same (4 phases, same timing windows, same playbook contract). What changes is what fills each phase visually. Concrete examples of layout substitutions that work without breaking the playbook:

Phase	Default (archon-style)	Possible alternatives
Phase 1 — Hero	Overline + pre-line + gradient slam word + caption pill	Full-bleed quote + tiny attribution; oversized number + label; brand logo entrance + tagline
Phase 2 — Insight slot	Side-by-side stat pill row (2 stats)	Single oversized metric + hairline rule (anthropic now); split-screen comparison; pull-quote with attribution; vertical stack of 3 micro-stats
Phase 3 — Detail slot	Color-card grid (3 feature cards)	Typographic chapter list (anthropic now); horizontal timeline strip; hub-and-spoke diagram; before/after pair; receipt-style itemized list
Phase 4 — CTA	Overline + URL pill + subscribe arrow	QR code + URL; multi-line manifesto end-card; logo lock-up with URL beneath

Sample prompt to redesign two scenes against a fresh template:

"I want a new short template at templates/shorts/<brand>/ cloned from templates/shorts/anthropic/, but with visually distinct scene layouts — not just a reskin. Redesign:

• Phase 2 as <one of: single oversized metric / split-screen comparison / pull-quote / micro-stat stack> — different from both Archon's pill-row and Anthropic's single-metric layout.
• Phase 3 as <one of: horizontal timeline strip / hub-and-spoke / before-after pair / receipt list> — different from both Archon's card grid and Anthropic's chapter list.

Keep Phase 1 and Phase 4 the same shape as the source (hero slam + CTA URL — these are the load-bearing thumbnail moments). Critically: preserve the playbook contract — the phase IDs #phase1-4, the inner element IDs the playbook fills (#p1-hero, #p1-caption, #p2-headline, #p2-overline, #p3-overline, and a sensible mapping for the new P2/P3 elements like #p2-pill-1/2 or #p2-metric and #p3-card-1/2/3), the timing constants T1/T2/T3 and P2/P3/P4, slam_t, shake_offsets, and the audio insertion point at the end of the body. The playbook will read your new structure and fill it; just keep enough IDs intact that it can find its anchors. Then write the playbook at .claude/skills/diy-yt-creator/new-<brand>-short.md, the workflow YAML, and the command file. Run npx hyperframes lint templates/shorts/<brand> until clean."

Result: Visually unique scenes that still play nicely with the playbook and compute_timings.py. ~20-40 minutes depending on layout complexity.

For an in-repo reference: the anthropic template's Phase 2 (single oversized metric) and Phase 3 (typographic chapter list) are concrete examples of Option C applied to a real template. Compare templates/shorts/anthropic/index.html against templates/shorts/archon/index.html to see what "redesigned scenes within the same phase rhythm" actually looks like in code.

Going further — change the phase rhythm itself

Option C keeps the 4-phase rhythm and only changes what's inside each phase. If you want to change the rhythm itself — different phase count (3-phase or 5-phase), different total duration, a hub-and-spoke structural pattern instead of phase mutex, a long-form 16:9 layout — that's a bigger lift. You'll need to update scripts/compute_timings.py to compute boundaries for your new phase count and rewrite the GSAP timeline math in index.html. Ask the agent to walk you through it:

"I want a 5-phase short template (Hero → Problem → Solution → Receipt → CTA) instead of the 4-phase default. Clone templates/shorts/archon/, add a #phase5 div, extend the GSAP timeline with T4/P5 anchors, update scripts/compute_timings.py to compute boundaries for 5 phases (the current logic assumes 4), and write a playbook for it."

Both the agent and the codebase are designed to make these changes one-file-at-a-time and lintable at every step.

TTS engines

The workflow generates narration via one of two TTS pipelines. Pick whichever fits your situation — the rest of the workflow is identical (same playbook, same composition edit, same lint pass):

Engine	Cost	Quality	Voice cloning	Setup	Best for
Kokoro (default)	Free	High (MOS 4.5 on the LMSYS Eval)	No (preset voices only)	pip install kokoro + espeak-ng	Anyone testing the workflow, no-budget creators, fully offline use
ElevenLabs	~$5/M chars	Premium	Yes (Instant Voice Clone)	pip install elevenlabs + API key	Production channels, voice-cloned narration, max polish

Which Python script runs: the create-* workflows call whichever TTS script is paired with the playbook. By default the playbooks assume Kokoro. To switch to ElevenLabs, edit the playbook step 5 to call python scripts/elevenlabs-tts.py … instead of python scripts/kokoro-tts.py … — same flags, same output contract (narration.wav + transcript.json with the same word-timestamp shape).

Output is identical from the downstream pipeline's perspective. Both scripts write a flat-array transcript.json keyed on {word, start, end}. scripts/compute_timings.py, npx hyperframes lint, and the GSAP timeline edits all work without modification.

First-run cost for Kokoro: a one-time ~325MB model download from Hugging Face. After that, generation is fully offline and runs on CPU at roughly real-time speed (a 30-second short generates in ~30-40 seconds on a modern laptop).

Voice tuning (ElevenLabs)

The defaults in .env.example are the tested sweet spot for an Instant Voice Clone on shorts:

Setting	Default	Effect of going up	Effect of going down
ELEVENLABS_STABILITY=0.40		More monotone	Phoneme artifacts ("incoherent words")
ELEVENLABS_STYLE=0.70		Artifacts return at high style + low stability	Flatter, less excitement
ELEVENLABS_SIMILARITY_BOOST=0.75		Locks to reference timbre, suppresses prosody	Drifts further from the reference voice
ELEVENLABS_SPEED_SHORTS=1.15		Compresses phonemes + sentence-final intonation (sentences sound mid-thought)	Slower, more breathing room
ELEVENLABS_MODEL_ID=eleven_multilingual_v2		eleven_v3 is more expressive but drifts further from clone voice	eleven_turbo_v2_5 is faster + cheaper but flatter

See the comment block inside .env.example for the full tuning matrix. If a clone sounds monotone, the first knob is stability ↓. If it sounds garbled, stability ↑ first.

Script-level rules (enforced by the playbook): SSML <break time="0.35s"/> between sentences, <break time="0.4s"/> at phase boundaries (NOT 0.65s — causes re-entry artifacts), natural abbreviations only, selective CAPS on 1-2 power words per phase.

Remote workflow state (optional Postgres / Neon)

By default Archon stores workflow runs, conversation messages, and isolation state in a local SQLite file at ~/.archon/archon.db. Fine for a single machine. If you want shared/remote state — multiple machines hitting the same history, queryable from a dashboard, or just durability beyond the laptop — point Archon at a Postgres database instead.

Switch to Postgres

Set DATABASE_URL in ~/.archon/.env (applies to every project on this machine) or <project>/.archon/.env (this project only):

# Neon (recommended for zero-ops Postgres)
DATABASE_URL=postgresql://USER:PASSWORD@ep-xxxx.region.aws.neon.tech/dbname?sslmode=require

# Self-hosted / Supabase / RDS
DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/dbname

Verify it took:

archon doctor   # Database line should now read: reachable (postgresql)

That's it. No migration command — Archon initializes its schema on first connect.

Caveats

• One-way switch. Setting DATABASE_URL does not import your existing SQLite history. Dump it manually if you care: sqlite3 ~/.archon/archon.db .dump > archon-backup.sql.
• Per-repo override wins. If you put DATABASE_URL in both ~/.archon/.env and <project>/.archon/.env, the project file wins for workflows run inside that repo.
• Neon free tier suspends idle. First connect after suspend pays a cold-start (~1s). Not a problem for archon workflow run (long-running anyway), but archon doctor may feel slow on a cold DB.
• SSL is mandatory on managed hosts. Always append ?sslmode=require to the Neon URL (their dashboard does this for you).

Output

videos/<slug>/
├── index.html              ← root composition (HTML + GSAP timeline)
├── meta.json, hyperframes.json, DESIGN.md, README.md
├── script.txt              ← narration source (with <break> tags inline)
├── audio/
│   ├── narration.wav       ← Kokoro 24kHz PCM, or ElevenLabs (MP3 decoded via ffmpeg)
│   └── narration-chunks/   ← per-chunk intermediates if you use chunked ElevenLabs mode (gitignored)
├── transcript.json         ← word-level timestamps (same shape from either TTS engine)
├── assets/                 ← per-template assets (logos, etc.)
└── out/                    ← rendered MP4 (gitignored)

videos/<slug>/ is committed to git so every generation is a permanent gallery entry. Only the rendered MP4 and per-chunk TTS intermediates are gitignored.

Customization

• TTS engine — pick Kokoro (free, default) or ElevenLabs (paid) via the appropriate .env vars; see "TTS engines" above.
• Voice (Kokoro) — set KOKORO_VOICE in .archon/.env. Catalog: https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md.
• Voice (ElevenLabs) — set ELEVENLABS_VOICE_ID in .archon/.env. Documented presets: Brian nPczCjzI2devNBz1zQrb, Adam pNInz6obpgDQGcFmaJgB, Daniel onwK4e9ZLuTAKqWW03F9. Or use your own clone's ID.
• Voice tuning matrix (ElevenLabs) — see .env.example and the table above.
• Default duration — edit let duration = 30; in any .archon/workflows/create-<template>-short.yaml (the parse-input JS).
• Range guard — same file: if (duration < 10 || duration > 300) clamps to 10s-5min.
• Slug stopwords — same file: STOPWORDS Set; add product/company names so they don't bloat slugs.
• Script style rules — each playbook at .claude/skills/diy-yt-creator/new-<template>-short.md step 4 documents break-tag layout, CAPS guidance, abbreviation conventions.

Repo layout

.
├── .archon/
│   ├── workflows/
│   │   ├── create-classic-short.yaml           ← spawns a brand-neutral short (DEFAULT)
│   │   ├── create-archon-short.yaml            ← spawns an Archon-themed short
│   │   └── create-anthropic-short.yaml         ← spawns an Anthropic-themed short
│   ├── commands/
│   │   ├── create-classic-short.md             ← AI command driving the classic playbook
│   │   ├── create-archon-short.md              ← AI command driving the Archon playbook
│   │   └── create-anthropic-short.md           ← AI command driving the Anthropic playbook
│   ├── plans/port-create-archon-short.md       ← origin-port reference
│   └── config.yaml
├── .claude/
│   ├── rules/                                  ← project-wide rules the AI follows
│   └── skills/
│       ├── diy-yt-creator/                     ← the playbooks (one per template)
│       ├── hyperframes/                        ← framework patterns (palettes, refs)
│       ├── hyperframes-cli/                    ← CLI command reference
│       └── archon/                             ← Archon workflow authoring docs
├── templates/shorts/
│   ├── classic/                                ← brand-neutral template (deep navy + blue/sky-blue) — DEFAULT
│   ├── archon/                                 ← Archon-themed template (dark blue + cyan/magenta)
│   └── anthropic/                              ← Anthropic-themed template (near-black + orange/cream)
├── scripts/
│   ├── kokoro-tts.py                           ← FREE local TTS (Apache-licensed, ~325MB model, espeak-ng)
│   ├── elevenlabs-tts.py                       ← PAID ElevenLabs TTS with MP3 + ffmpeg decode
│   ├── tts_lib.py                              ← chunked-generation lib for ElevenLabs (delta-regen)
│   ├── compute_timings.py                      ← derives phase boundaries, slam_t, hero entrance, etc.
│   └── list_voices.py                          ← list available ElevenLabs preset voices
└── videos/<slug>/                              ← one folder per generated short

Caveats

• Kokoro first run downloads ~325MB. The Hugging Face model cache lives at ~/.cache/huggingface/. After the first run, generation is fully offline. If you see a "model not found" error, your network blocked the download — set HF_HUB_OFFLINE=0 and retry.
• Kokoro needs espeak-ng system-wide. This is a separate install (not in pip). See Quick Start step 3 for the OS-specific install command. If the script errors with "espeak-ng not found," that's the cause.
• ElevenLabs PCM output is Pro-tier only. scripts/tts_lib.py requests mp3_44100_128 (available on Creator and below) and decodes to PCM via ffmpeg. If you're on Pro and want pure PCM, edit tts_lib.py to switch output_format.
• Phantom punctuation in transcripts. ElevenLabs occasionally emits a standalone . word around <break> tags. clean_sync_data in tts_lib.py filters these defensively so phase-boundary math doesn't drift. (Kokoro doesn't have this issue.)
• Break-tag re-entry artifacts (ElevenLabs). Phase-boundary <break> durations of 0.65s+ can cause an audible click/breath when the model resumes. The playbook uses 0.4s for phase breaks and 0.35s for inter-sentence breaks — proven artifact-free in 20+ test runs.
• Speed ceiling is 1.15 (both engines). Going to 1.20 compresses phonemes (more garbled output) AND flattens sentence-final intonation (sentences sound mid-thought, like they didn't end).
• Bun on Windows + multi-line bun -e. Archon spawns inline bun scripts via Node's execFile; on Windows, bun truncates the script at the first newline (silent — exit 0, no error). The parse-input node uses a bash wrapper (mktemp + bun run) to avoid this.
• AI fabrication risk. If WebFetch / WebSearch fails, the playbook may invent statistics. If you spot fabrications, restart with a source URL embedded in the topic ("Topic — see https://example.com/blog/").
• Repo name is historical. This stack pivoted from Remotion to HyperFrames mid-2026. The repo name reflects the original Remotion-based project; the active stack on main is HyperFrames.

Provenance

Ported from diy-yt-creator-hyperframes. Current main is HyperFrames + (Kokoro or ElevenLabs) single-call with the tuned settings matrix documented above. ElevenLabs voice settings, break-tag durations, and the MP3 + ffmpeg decode pipeline were validated over a live tuning session. Kokoro support was added once the engine matured to MOS 4.5 with native word-level timestamps — the same transcript.json shape works for both engines downstream.

License

MIT