Hearyourvoice

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.

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:

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.

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.