hearyourvoice

name

hearyourvoice

description

The repeatable workflow for short Thai documentary/explainer videos — one topic in, one finished MP4 out. Use when producing a video end to end or running any stage: research a topic, write a script, run an adversarial agent debate over the hook/punchline, generate ElevenLabs voiceover, gather visuals (self-shot, Creative-Commons, or generative), lay timecoded inserts on a timeline, and package a delivery folder. Format-agnostic: aspect/resolution/fps come from a per-project config (9:16, 16:9, 1:1, custom) — nothing is hardcoded. Editor-agnostic: assemble in CapCut, Premiere, DaVinci, or a code renderer from a universal timeline (JSON + CSV). Generative footage (e.g. Veo) is one optional source, never required. Ships a 16-strong `hyv-*` subagent team led by `hyv-producer`, so a video can be delegated whole or fanned out in parallel. The reasoning half runs anywhere; steps that shell out (ffprobe, yt-dlp, ffmpeg, your editor) need Claude Code.

HearYourVOICE

The recipe — run this, don't read the library first

A topic and a .env with ELEVENLABS_API_KEY + VOICE_ID is everything you need to start. Everything below this section is reference for when a step surprises you. Do not read it up front, do not open references/* to orient, and never read a script's source to work out how it behaves — run it with --help, or just run it: they all print what they need and refuse safely.

HYV=$(ls -d .claude/skills/hearyourvoice ~/.claude/skills/hearyourvoice 2>/dev/null | head -1)

# 0 · scaffold (writes src/<slug>/ + public/<slug>/ + .env if missing)
node "$HYV/scripts/new-project.mjs" --slug <slug> --title "<ชื่อ>"

# 1 · research → write src/<slug>/research.md yourself
#     LOOK FIRST: research.md already there with an Evidence log? Read it, skip searching.
#     Else: 3 facts, ≥2 INDEPENDENT sources each, ≤6 WebFetch. Then stop and write.
#     An EMPTY fetch counts and is an answer: "ไม่มีเนื้อหา" / "cannot extract the figures"
#     means that number isn't published — not that you need a better query. Two empties on
#     one claim = change the claim, not the query. The sources decide what the video is about.
#     Each fact carries its EXCERPTS, not just links. End with "## Evidence log":
#     every query, every URL fetched (incl. dead ends), what each gave.
#     That file is the evidence — writers think with it, บก rules on it, re-runs reuse it.

# 2 · script → write src/<slug>/voiceover-v1.md yourself
#     Format: "## EP1 - <title>" then a blank line, "VO:", blank line, the narration.

# 3 · voiceover — the gate prints the bill and exits 2; that is the gate working
node "$HYV/scripts/gen-voiceover.mjs" --slug <slug>          # shows characters billed
node "$HYV/scripts/gen-voiceover.mjs" --slug <slug> --yes    # only after a human OK

# 4 · the master clock (this file is what every later timecode is built from)
node "$HYV/scripts/measure-voiceover.mjs" --dir public/<slug>/voiceover \
     --out src/<slug>/voiceover-durations.json

Voice, model and format come from .env on their own. Don't pass --voice-id unless the human named a specific voice — an empty voice_id in the config means "use .env", and passing the config's empty/placeholder value overrides .env and breaks the call.

That is the whole voice mode. Stop there and hand it back: they hear the script before anyone builds visuals for it. full mode continues at phase 4.

Budget your reading. Every file you open before starting is wall-clock the human waits through. One measured run spent 5 of its 16 minutes reading templates, --help output and script source before its first search. The recipe above is the orientation; anything else, open it when you hit the thing it explains.

---

The end-to-end loop that turns one topic into one finished video, in whatever format the project config asks for. It is the orchestrator every project runs, regardless of where the footage comes from. Each phase either does work directly or hands off to a specialist.

Footage is source-agnostic. A finished video can use any mix of: shots you film yourself, generative shots (Google Veo or any model), found Creative-Commons clips, or motion graphics built in your editor. Generative is optional — many projects use zero Veo. Only load veo-insert-planner when you actually generate Veo shots.

Editor-agnostic. The skill exports a universal timeline (edit/<ep>-timeline.json + .csv); assemble the final cut in whatever you use — CapCut, Premiere, DaVinci Resolve, or a code-based renderer. The recipe is identical (see references/assembly-and-validation.md).

Optional companion skills (loaded only when relevant):

• veo-insert-planner — for the generative-footage path (silent Veo prompt briefs).
• remotion-best-practices — only if you choose to assemble in a code-based renderer (Remotion). Not required for NLE editors.

First move: one worker per video — including you

One video? Do it yourself. Follow the recipe above. Do not spawn a chain of specialists to hand one script down a line: research → script → hook → voice can't overlap, so splitting it adds a fresh context per link and buys nothing. Measured: solo 4:38 to a real voiceover; the same job through a delegation chain hadn't finished at 13 minutes.

Several videos? That's what the team is for. One hyv-producer per topic, each doing its own whole chain in its own src/<slug>/. Three videos in roughly the time of one — three workers, not one worker under three foremen.

Spawn every producer in ONE message — one Agent call per topic, all in the same block, never one message each. "In parallel" is not something you intend, it is something the message shape either does or doesn't do: three Agent calls in one block run at once; three messages queue, and topic 3 starts only when topic 1 is done. Observed: a 3-topic run spawned exactly one producer and then waited on it — while the words "spawn 3 ตัวใน ข้อความเดียว" sat right there in the human's prompt. Compose all of them before you send. Their whole point is that they never need each other.

Set nothing up first. Each producer scaffolds its own slug — new-project.mjs never overwrites .env, so they can't collide. You do not need to inspect the folder, list the env vars, or prove node/ffprobe exist before handing out topics: the desks need none of that to start searching, and the tools get checked by the phase that uses them. Measured: doing that homework first cost 2:49 — a third of the run — with every desk idle for all of it. The topics are the only thing you have that they need. Hand them over and get out of the way.

Spawn ACROSS, never DOWN.

down   A → B → C          3 handoffs · 3× the time · same one answer
across A ∥ A ∥ A → pick   0 handoffs · 1× the time · best of three

Down a chain, agents lose: every link is a fresh context re-reading what the last one knew. Across the same input they win, and it costs no wall clock at all — three agents on one brief finish in the time of one, and you keep the best. You pay tokens, not minutes.

Spawn with run_in_background: false whenever you need the answer. Agent backgrounds by default: send three writers off without the flag and you get three acknowledgements and no scripts, so you'll reach for shell to wait — observed verbatim: sleep 30 && echo done, a sleep 1 noop labelled "placeholder while waiting for background agents", echo "waiting for writer agents". Every one of those is a model turn that produces nothing, timed by a guess about work you can't see. One message makes them concurrent; the flag hands you their work. You need both — concurrent work you never collect is worth nothing. Typing sleep means you spawned wrong; fix the spawn, not the wait.

And when you do spawn: already a file → send the absolute path. Not a file → paste it. research.md and project.config.json are written; three writers can read them at once. Retyping the brief into three prompts means generating it four times — once to the file, once per writer — and that generation is serial, on the critical path, with nobody writing until you finish. Measured: pasting full briefs produced 23,814 characters of prompt; sending paths instead produced 1,638 per writer, with no loss. Paste only what exists nowhere else: the angle, that the others are competing, the deliverable shape. And make paths absolute — a bare references/… doesn't resolve from the project.

So spawn for competition:

1. newsroom only — three hyv-scriptwriter on one brief, in ONE message — three angles, then hyv-script-reviewer (the บก) picks one and names its fixes. Not theory: the hook debate already works this way and produced "ในคน 100 คนที่คิดแบบนี้ เป็นไซนัสจริง แค่ 3 คน — แล้วอีก 97 คนล่ะ", which no single writer here came up with. Under solo (the default) you draft the angles yourself and spawn nobody — see the dial above.
2. The debate panel — hyv-hook-maximalist ∥ hyv-skeptic-editor ∥ hyv-target-viewer → hyv-judge, when the winning hook is still contested. Independence is the product: each must argue without seeing the others, impossible in one context. Three in ONE message, then the judge.
3. The human named a specialist.

The rest of the hyv-* files are worth their weight as spec — how each phase is done, its gates, what it must never fake. Read the spec; don't hire the agent for a step you can do yourself with the brief already in your context.

Don't go looking for agents on disk: they arrive by several routes (.claude/agents/, a plugin, a marketplace), and a missing file proves nothing except that you looked in the wrong place.

The phase numbers are a data order, not a queue. Spawn everything whose inputs already exist, at once. In particular cc-scout, graphics and your own filming don't need the audio — they read the shotlist, so start them with phase 2, not after it. One is a slow API call, the other slow web search; running them back to back pays for both. (The generative branch is the one real exception: a Veo prompt must state its exact seconds, so prompt-smith waits for the measured clock — gen-veo-briefs.mjs requires --durations.) Phase 5 waits by nature: it joins the clock to the clip pool.

Delegating keeps each phase's noise — search results, ffprobe output, clip listings — out of the main conversation; you get the summary, not the logs. If no hyv-* subagent is available to you, run the phases below yourself and say so once, so the user knows they got the solo path. Everything works solo; the team is an accelerator, not a requirement. To add it: npx hearyourvoice install (Claude Code) or install the plugin. Full roster and decision chain: references/subagents.md.

Two rules that hold either way: the human confirms the output spec and every gate (topic lock, split hook/punchline, spending voiceover or generative credits), and hyv-judge recommends but never rules on creative direction.

Know what you can actually run — then say so

Half this loop is pure reasoning. The other half shells out to real binaries on a real machine. Which half you can do depends on where you are running — so know the line, and check each tool at the step that uses it, never up front.

Do not preflight. ffprobe is used at phase 2, five-plus minutes after you start; proving it exists before your first search buys a fact you can't act on yet and costs a turn now, while the human waits. Each check is its own model turn — measured: four setup calls burned 2:49 before a single producer was spawned, a third of the run, and every one of those tools was for a phase that hadn't started. The scripts already fail loudly and safely when a binary is missing; that failure, at the step, is the check. Start the work. Verify the tool when you reach for it.

Work	Needs	Runs where
research · script · review · storyboard · debate panel · judge	reasoning (+ web search)	anywhere — chat, Cowork, Claude Code
shotlister (new-shotlist.py, openpyxl) · voiceover (ffprobe) · cc-scout (yt-dlp) · veo-runner · assembler (ffmpeg + your editor)	a local shell + binaries + your files	Claude Code only

Note hyv-shotlister is phase 1 but still needs Python — the line is drawn by tool dependency, not by phase number.

🛑 Hard stop — never simulate the machine half

If you cannot run shell commands, you cannot do the second row. Do not fake it:

• Never invent durations or write a voiceover-durations.json you did not measure with ffprobe. The master clock is measured audio — a guessed number silently breaks every timecode downstream and the error is invisible until the render is wrong.
• Never claim a file was generated, a clip downloaded, a license verified, or a video rendered unless you ran the command and saw it succeed.

Stop instead, say which step needs a local shell, and tell the user to run it in Claude Code (npx hearyourvoice install). A correct refusal beats a plausible fabrication.

Core invariants (never break these)

• The output spec is read, never assumed. Aspect, width/height, fps, and editor come from src/<slug>/project.config.json (template: references/examples/project.config.example.json). Defaults are vertical 9:16 · 1080×1920 · 30 fps, but 16:9, 1:1, 4:5 and custom are equally supported — every script takes --aspect/--width/--height/--fps. Confirm the config with the user before producing; never hardcode a frame.
• The voiceover is the master clock. Every visual's timecode is derived from the measured ElevenLabs audio duration — never from the written script's guessed length.
• All visual clips are silent. Self-shot, generative, and CC clips are muted on the timeline. Narration is its own audio track; ambience, if any, is one continuous bed under the voice.
• Image-led, minimal on-screen text. Thai captions only where they earn their place.
• One project = one src/<slug>/ folder + assets under public/<slug>/; assembled in your editor, rendered to out/, packaged to delivery/<slug>/.

See references/pipeline-loop.md for the one-screen map + phase input/output contract, and references/naming-conventions.md for every path and filename pattern.

How far to go — ask, then stop there

Not every request wants a finished video. How far you run is a dial the human sets, and each stop is a real deliverable, not a half-done run — every mode's output is exactly the input the next one needs:

Mode	You stop after	They get	Measured
script	phase 1e	research brief · script with a ranked hook · shotlist.xlsx	~8–10 min
voice ← ask for this if unsure	phase 2	the above + real voiceover mp3 + the measured clock	~12–15 min
full	phase 6	the above + footage + timeline + rendered mp4 + delivery/	~25–30 min

Quote these honestly. Every specialist is ~2–3 minutes of wall clock, and a chain of eight is 20+ minutes however much runs in parallel — parallelism makes three topics finish together, it does not shorten one chain. Add ~4 min if the debate runs, and skip nothing to make a number look better. Telling someone "6 minutes" and delivering 25 is worse than saying 25.

voice is the useful default when the human hasn't said. The voiceover is the master clock, so it is also the natural checkpoint: they hear whether the script actually works before anyone spends time sourcing twenty images for it. A script that sounds wrong out loud should die at 6 minutes, not at 15 — and the audio is what tells you.

script hands the work to the human on purpose. The shotlist is a work order: one row per shot, how to capture or source it, the licence. Phase 3 already has no agent — nobody can hold your camera — and phase 4 can work the same way when the human would rather pick the visuals themselves. Stopping there is a finished job, so report it as one.

Say which mode you are running, once, before you start. When they only asked for "a video about X", ask which they want rather than assuming full — it is the most expensive answer to a question they may not have asked.

The second dial: solo or newsroom — how hard the story gets tested

How far you go and how hard you check are different questions. Both dials apply to every mode: voice solo and voice newsroom both end at a real mp3; they disagree about what happened before it.

	solo ← default	newsroom
the script	the producer drafts 2–3 angles in its own context and picks one	3 × hyv-scriptwriter compete, blind to each other, in ONE message
the check	the producer's own read	hyv-script-reviewer (opus) picks the winner, blocks fixes, re-reads the resubmit
the brief	facts + sources	facts + the excerpt behind each + an Evidence log of every query and dead end
cost	~11 min to script	~43 min to script — see below

Both numbers are measured on the same job — three Thai fish, three desks in parallel, scripts only: solo 3/3 at 10:43 · newsroom 3/3 at 43:07. Four times the clock, and the human is the one who gets to decide whether this topic is worth it.

Inside the newsroom run, per desk: ~4 min researching · ~3½ writing the brief with its excerpts · ~6 for three writers competing · and the rest in the บก's loop — it failed and sent back roughly twice per desk before passing. That loop is the product, not an overrun: it caught a script that told viewers to cast where it had just spent three lines proving the fish can't live.

And this is the whole point of the desks: those three clips ran concurrently, so three cost what one costs. Serially they'd have been about two hours. newsroom does not make one clip fast — nothing does — it makes ten clips cost what one clip costs. One topic in newsroom is the expensive way to buy one script; ten topics in newsroom is the only sane way to buy ten.

Neither is the "cheap" one — they buy different things. solo is one mind's best guess, checked by the mind that guessed. newsroom is three independent attempts judged by a stronger model against sourced evidence, and it catches what a single pass cannot: measured, a scriptwriter refused a brief claiming ปลาช่อน is special because it breathes air — ปลาชะโด, same family, breathes air too — and the desk rewrote the premise around water depth instead. No solo draft found that, because the writer who spots it is the one who isn't the writer who wrote it.

Default to solo, and say the other exists. Most clips don't need three writers arguing, and eight minutes for a real script is a good trade. Reach for newsroom when being wrong is expensive — medicine, money, law, anything a viewer might act on, anything that will be fact-checked in public — or when there are several topics, where its cost stops mattering. If they asked for newsroom, quote them ~45 minutes up front and don't flinch. They picked the slow one on purpose; never quietly hand them solo because a number looked bad.

The loop

0a Ideas ─▶ ══ you pick ══ ─▶ 0b Research (may kill the premise)
                                     │
                                     ▼
   1 Script + punchline debate ─▶ ══ hook locked ══
                                                     │
                        ┌────────────────────────────┴────────────────────────┐
                        ▼                                                     ▼
              2 Voiceover (master clock)                      3 Mock shots — optional, you film
                generate ─▶ ffprobe                           4 Footage — find CC · graphics
                        │                                        (need no audio: start now)
                        └────────────────────────────┬────────────────────────┘
                                                     ▼
                                       4' Generative shots — optional
                                          prompts need the measured seconds,
                                          so this branch waits for 2
                                                     │
                                                     ▼  join: measured clock + clip pool
                                          5 Prepare inserts onto TC
                                                     │
                                                     ▼
                                          6 Validate + package
                                                     │
                                                     └─▶ back to 0 for the next topic

Left and right start together — CC scouting and graphics never touch the audio. Only the
generative branch and 5 have to wait.

Phases 3 and 4 are where visuals come from — use whichever sources fit the project (often just one). Phase 2 (voiceover) must precede phases 4–5, because insert timing is derived from the measured audio.

---

Phase 0 — Find the story (ideas → pick → research)

Goal: end up with one topic and a factual brief you can build on. Two steps, and a human between them.

0a · Ideate (hyv-ideator — cheap, no search, no verification)

Generate 5–10 fully-shaped candidates into content-idea-log.md. Each one carries a hook, 3–5 แก่นเรื่อง points, มุมเล่า (why the viewer cares), an เปรียบเทียบ analogy, a Format, the B-roll it needs — and ต้องตรวจ: the claims it stands on. Fan out one ideator per pillar.

Ideas before research, on purpose. Ideas are cheap; research is not. Ten ideas → the human keeps one → you verify only that one. Research first and you pay for nine briefs you throw away. But the trade only holds if you treat an unverified idea as what it is: a hypothesis. Never state a figure as fact at this stage — write it under ต้องตรวจ.

0c · Debate which idea (the panel's highest-value use — skip it when the human named the topic)

When more than one idea is live and you can't separate them, run the panel on the ideas: all three in ONE message (hyv-hook-maximalist, hyv-skeptic-editor, hyv-target-viewer), then hyv-judge. Their three questions already are the right ones for choosing what to make — most stopping power / can we actually pay it off / would I care.

This beats debating the hook, and it's not close. 0c decides whether the video exists; a hook debate polishes one line of a video already being made. A perfect hook on a topic nobody cares about is a competent boring video — and you never find out, because it shipped. Four minutes spent choosing what to make is worth more than four minutes spent on its first sentence, which is why the phase-1 hook debate is now contested-only.

══ GATE — the human picks ══

Ideas are pitched, never chosen, by an agent. The panel recommends; hyv-judge flags a split; you pick. Same rule the hook debate lives under.

0b · Research the winner (hyv-researcher — real WebSearch)

1. Verify the ต้องตรวจ claims first. They're what the hook rests on. If one is false the idea is dead — research is allowed to kill it, and should say what the real number is; a corrected premise often beats the pitch.
2. Research with WebSearch / WebFetch and any source docs the user provides. Every key fact needs ≥2 independent sources; capture them for later attribution. Depth is a dial, and it defaults shallow: normal lands 3 facts on ≤6 fetches — that is all a 90s script has room for. Pass deep (up to 8 facts, ≤12 fetches) only when the user asks for it or a contested premise needs it. Topics with unlimited literature (medicine, law, economics) will happily absorb an afternoon; the cap is what stops them, so treat it as a stop rather than a target to browse past.
3. Write a research brief from references/research-brief.template.md: thesis, audience, the one surprising insight, key facts + sources, subject lock (the exact named subject so later prompts/visuals never drift), and visual opportunities.

Output: a research brief (chat or src/<slug>/research.md) and a chosen slug.

Phase 1 — Script + punchline debate (เขียนบท + agent ต่อสู้กัน)

Goal: a thesis-driven, TTS-ready narration whose hook and punchline have survived an adversarial debate.

1. Draft src/<slug>/script-v1.md: title, one-line thesis, beats, closing. Prose is fine.

2. Punchline debate — only when the hook is contested. hyv-scriptwriter returns its hook candidates ranked, plus contested: yes|no. On no, take its top hook, say so in your report, and move on — no panel. On yes (or when the human asks for a debate), run the adversarial panel in references/punchline-debate.md. This is the "agents fighting over the punchline" step, and it costs ~4 minutes and four agents: spend it on the hook that could really go two ways, not as a rubber stamp for one that's already obviously the winner.

   When it does run, spawn all three panelists in ONE message — three Agent calls in the same block, not three messages. hyv-hook-maximalist, hyv-skeptic-editor and hyv-target-viewer never read each other's work: each one only reads the brief and argues its own corner, so queueing them makes the debate three times slower for nothing. Only hyv-judge waits — it needs all three verdicts, so it goes in the next message.

   hyv-script-reviewer runs on every video, and nothing is voiced before it passes. This is the documentary process, not ceremony: research → draft → the editor raises issues → you fix → you resubmit → approved → then you record. It sits at the last moment the script is still cheap to change. After it, voice costs money, a fix means paying twice, and the voiceover is the master clock — re-record and every downstream timecode moves. Loop until VERDICT: pass; it fails on any Facts or Overpromise issue and names the line.

3. Rewrite into TTS-ready narration at src/<slug>/voiceover-v1.md following $HYV/references/script-and-voiceover-spec.md (inside the installed skill, not this project) — short lines, deliberate breaks for pacing, hook in the first ~3 s, explicit punchline beats. Put the voice-config block (voice id, model: eleven_v3, source) at the top.

4. Build the shotlist (src/<slug>/shotlist.xlsx) — give every beat a category-prefixed shot ID and plan capture/source/coverage. This is the artifact that makes the rest of the workflow easy; see references/shotlist-format.md. Scaffold a blank one with scripts/new-shotlist.py, or copy references/examples/chado-NG-shotlist.xlsx. Build it straight from the script + the brief's Visual opportunities (which already names 5–8 concrete shots with a likely source each). hyv-storyboard is a separate optional pass, worth it only when the visuals must be composed — a sequence that has to build — rather than sourced from CC, stock or graphics, which is most videos.

Output: script-v1.md, a locked voiceover-v1.md, and shotlist.xlsx. The locked hook/punchline gates phase 2.

The shotlist (planning backbone)

The shotlist is the single artifact that threads phases 3–5: one row per unique shot, with the episodes that reuse it, how to capture or source it, the license, batch capture sessions, per-episode coverage, and a CC source log. Build it in phase 1 and keep its status column current as shots get captured/sourced/generated — at a glance you see what's left before assembly. Full column contract and the 5-sheet structure: references/shotlist-format.md. Its shot IDs flow straight into the phase-5 insert plan and the attribution list.

Phase 2 — Voiceover (ลงเสียง) — the master clock

Goal: generate the narration and measure its real length; everything downstream times off this.

1. Generate with scripts/gen-voiceover.mjs (segmented per episode, reads voiceover-v1.md, writes public/<slug>/voiceover/ep*.mp3). Env: ELEVENLABS_API_KEY from .env, VOICE_ID, MODEL=eleven_v3 (see INSTALL.md → Environment & API keys).
2. Measure every MP3 with scripts/measure-voiceover.mjs (uses ffprobe) → src/<slug>/voiceover-durations.json. Edit length per episode = audioFrames + TAIL_FRAMES (default 24 frames at 30 fps).

Output: public/<slug>/voiceover/ep*.mp3 + voiceover-durations.json. Ask before spending ElevenLabs credits.

Phase 3 — Mock shots (ถ่ายเอง หรือ generative) — optional

Goal: capture the bespoke shots — either filmed yourself or generated.

• Self-shot: raw captures → public/<slug>/raw/; review and cut exact timestamp selects only → public/<slug>/select/. Loose/random clips are rejected.
• Generative mock: if you want AI shots here, treat them as a footage source in phase 4 (see the generative path). Mock UI/infographics can instead be motion graphics built in your editor — note them as graphics beats for phase 5.

All selects are silent. Output: reviewed silent selects in public/<slug>/select/.

Phase 4 — Footage: find and/or generate (Find footage หรือ generative shot)

Goal: assemble the pool of insert clips, from whichever sources fit. See references/footage-sources.md for the full matrix and how to choose. The four sources:

1. Found Creative-Commons — verify CC BY via yt-dlp metadata (YouTube's CC filter gives false positives). Download → public/<slug>/cc/video/, cut reviewed selects → public/<slug>/cc/select/, record credit/license/sourceUrl in public/<slug>/ATTRIBUTION.md.
2. Generative (optional) — build the silent scene brief from the measured durations (scripts/gen-veo-briefs.mjs, or veo-insert-planner), render the copy/paste prompt Markdown (scripts/veo-generate.py --emit-md; prompt recipe in references/veo-prompt-guide.md), generate clips → public/<slug>/generated/ep*/. Apply subject lock + anti-loop variation guards. Strip any audio (ffmpeg -an). Use this only when a generated shot beats the alternatives.
3. Self-shot selects from phase 3.
4. Motion graphics (built in your editor) — the always-available fallback; if no acceptable clip exists for a beat, make the beat a graphic. Never wire loose, unreviewed clips.

Output: a reviewed clip pool under public/<slug>/ from one or more sources.

Phase 5 — Prepare inserts onto TC + export timeline (เตรียม insert ลง TC)

Goal: build the source-agnostic insert plan and export an editor-neutral timeline against the voiceover master clock.

1. Build the insert plan: an ordered list per episode where each insert has start_sec, end_sec, source (shot | generative | cc | graphic), file, and a note. Timecodes are contiguous (each start_sec == previous end_sec) and the final end_sec == target edit length from voiceover-durations.json. Validate with scripts/check-insert-plan.mjs. (For the generative path, veo-insert-planner's brief already is this plan with source: generative.)
2. Export the timeline with scripts/export-timeline.mjs --slug <slug> --episode ep1 --brief <brief.json> --durations voiceover-durations.json → writes src/<slug>/edit/ep1-timeline.json (frames + SMPTE timecode) and ep1-timeline.csv (one row per clip).
3. Assemble in the editor named in project.config.json (see references/assembly-and-validation.md) — the recipe is identical everywhere: voiceover mp3 on one audio track (master clock), each clip placed at its start_tc and muted, at the config's aspect and fps. Works in CapCut, Premiere, DaVinci, or a code renderer (editor: "remotion" → scaffold with new-project.mjs --remotion, then load remotion-best-practices).

Output: an editor-neutral timeline + a cut ready to render.

Phase 6 — Validate, package, log

Render the final mp4 from your editor, then run the editor-agnostic gates in references/assembly-and-validation.md: the mp4 exists; ffprobe confirms the width×height and fps from project.config.json, duration ≈ target, audio length ≈ video length; and you eyeball a few frames (not blank, correct episode, Thai text fits, clips muted). If you assembled in code, also run that tool's checks.

Then package the deliverable — the canonical output format (see references/output-format.md). The working files are scattered across src/, public/, and out/; scripts/package-delivery.mjs --slug <slug> gathers them into one standard delivery/<slug>/ folder (video/, voiceover/, script/, briefs/, attribution/, thumbnails/) plus a canonical manifest.json and a README.md. The manifest reports per-episode checks and a status of ready/incomplete; it exits non-zero until every episode is ready. That folder is the hand-off.

Finally update CURRENT_STATE.md and mark the topic done in content-idea-log.md. → loop back to phase 0.

The outcome of the skill is delivery/<slug>/ with manifest.json reporting status: ready — one folder you can upload or hand off, not scattered files.

---

Scripts in this skill

Generic, project-agnostic helpers — these generalize the per-project chado scripts/* so a new project doesn't copy-paste and edit paths. Each prints --help.

Scaffolding / planning:

• scripts/new-project.mjs — scaffold src/<slug>/ (research.md, script-v1.md, voiceover-v1.md, edit/, veo/) and public/<slug>/ (voiceover/, raw/, select/, cc/, generated/). Editor-agnostic; pass --remotion to also emit a code-renderer starter.
• scripts/new-shotlist.py — blank 5-sheet shotlist.xlsx (needs openpyxl).

Voiceover (phase 2):

• scripts/gen-voiceover.mjs — generic ElevenLabs generator (replaces the per-project gen-<slug>-voiceover.sh). Reads voiceover-v1.md ## EP<n>/VO: segments, --voice-id/--model, writes public/<slug>/voiceover/ep*.mp3, measures each. Needs Node 18+ and ELEVENLABS_API_KEY.
• scripts/measure-voiceover.mjs — ffprobe a voiceover folder → voiceover-durations.json (audioSec, audioFrames, sceneFrames, targetSec).

Footage / inserts (phases 4–5):

• scripts/fetch-cc-images.mjs — find, licence-check and download Creative-Commons stills from Openverse + Wikimedia Commons (--query, Thai works; --dry-run, --json). Reads the licence from each item's metadata rather than trusting a search filter, rejects ND (a cut is a derivative) and NC by default, downloads to public/<slug>/cc/images/, and appends creator/licence/source to ATTRIBUTION.md. Free, no key — the first thing to try for a beat, ahead of any text card.
• scripts/gen-veo-briefs.mjs — config-driven Veo brief builder + guards (generalizes gen-chado-veo-briefs.mjs). Project specifics live in a JSON config (references/examples/veo-briefs.config.example.json): subject lock, style descriptors, negative terms, per-episode focuses, and guard thresholds (min none-shots, max subject-shots, max consecutive subject, no-duplicate prompts, reject-term enforcement). Only for the generative path.
• scripts/veo-generate.py — portable Veo clip runner (generalizes generate_ep1_veo.py). Point --plugin/--agent-root at your Veo provider; --brief/--out at the episode. Forces silent output, pads to exact duration, supports --all batch and --dry-run. Also --emit-md renders the copy/paste prompt Markdown (ep*-google-veo-insert-prompts.md) from a brief — no provider needed; prompt recipe in references/veo-prompt-guide.md.
• scripts/check-insert-plan.mjs — validate a source-agnostic insert plan vs the durations manifest: contiguous timecodes, final end_sec == target, valid source, .mp4/graphic files, optional subject-lock / anti-loop (visual_strategy-aware).
• scripts/export-timeline.mjs — turn a brief + durations into an editor-neutral timeline: ep*-timeline.json (frames + SMPTE timecode) and ep*-timeline.csv (one row per clip) for CapCut/Premiere/DaVinci, plus an optional code-renderer snippet. Source-agnostic.

Deliverable (phase 6):

• scripts/package-delivery.mjs — gather the scattered working files into the standard delivery/<slug>/ folder + canonical manifest.json + README.md, ffprobe-verifying every render. This is the skill's output format (references/output-format.md).

When to stop and ask

Ask the user before: choosing the topic (phase 0), locking the hook/punchline when the debate is split (phase 1), spending ElevenLabs credits (phase 2), and spending generative credits (phase 4). These are the costly or irreversible steps.

Money: the gate is in the code, not in this paragraph

The two scripts that spend real money refuse by default. Run them normally and they call nothing, print exactly what would be billed, and exit 2:

Script	Without --yes	Cost shown
gen-voiceover.mjs	no API call, no mp3	segments + characters billed
veo-generate.py	no clips, provider not even loaded	clips, total seconds, ~THB estimate

Exit 2 there is the gate doing its job — it is not an error to debug or work around. Show the output to the user verbatim, get an explicit OK, then re-run the same command with --yes appended. Never put --yes on a first run, and never decide to spend on the user's behalf.

Keys: ask, don't assume — and never need one you don't

No key is required to get real work done. Research, script, the punchline debate, storyboard and shotlist need nothing. Both paid steps have a free twin that produces the prompts — and hands them to the human, who generates them wherever they like (their own ElevenLabs account, another TTS, another video model) and drops the results back in:

Instead of paying here	Run this	You get
gen-voiceover.mjs --yes	gen-voiceover.mjs --emit-md	a TTS sheet: voice settings, each segment, the filename to save it as, how to bring the audio back
veo-generate.py --yes	veo-generate.py --emit-md	copy/paste generation prompts per shot

🚫 Never synthesize a stand-in voice

--emit-md hands a sheet to the human. It is not a licence to voice the script yourself with whatever TTS is lying around — not say, not a system voice, not a local model. If there is no working key, the sheet is the deliverable for that step. Stop and hand it back.

A robot placeholder is not a preview of anything:

• It sounds broken. Anyone who opens the file judges the whole tool by it, and a file sitting in out/ looks like the deliverable no matter what you named the folder.
• Its timing is a lie anyway. Measured on one real project: the same script ran 107.0 s through the macOS Thai voice and 82.1 s through the real ElevenLabs voice — 25 seconds, 23% apart. Every insert placed against the placeholder clock has to be thrown away, so the "preview" previews nothing.

Need to prove the render pipeline before spending? Render against silence at the target length (ffmpeg -f lavfi -i anullsrc -t <sec>). It proves exactly what a fake voice proves — that frames come out at the right size, fps and duration — and it can never be mistaken for a finished video.

Offer the --emit-md path before asking anyone for an API key. Many users should never need one.

When a key genuinely is needed (the user chose to generate here), set it up properly:

1. Check first — npx hearyourvoice doctor reports which keys are set without printing values.
2. Missing? Copy the template: cp <skill>/references/examples/env.example .env, then ask the user for the value and write it into .env yourself.
3. Never echo a key back into the conversation, a commit, a log, or a filename. Read it from .env; don't repeat it. Confirm .env is gitignored before writing (it is, in this repo's template) and never commit it.
4. Don't invent a key, don't guess a VOICE_ID, and don't proceed on a placeholder — stop and ask.

ELEVENLABS_API_KEY + VOICE_ID cover phase 2. VEO_PLUGIN_PATH points at the user's own provider for phase 4 — this skill ships none. Full list with comments: references/examples/env.example.