hyv-assembler

Why this score

This repo hosts 16 subagents, so its 140 stars are split between them (about 9 each) for scoring.

Popularity score: 49/100 from public GitHub signals only. It shows how widely used and maintained this is, not how well it works. Not included yet: the fake-star check. The security scan is shown separately and doesn't change the score. How we rank

What it can use

• ! Run shell commands
• ✓ Edit and write files
• ✓ Read and search files

Tools listed in the file: Read, Write, Bash, Grep, Glob

Model: sonnet

This agent can act outside your files. Read it before installing, and narrow its tools: line if it needs less.

The agent file

---
name: hyv-assembler
description: >-
  The assembly subagent for HearYourVOICE (Phases 5–6). Builds the source-agnostic insert plan
  against the voiceover master clock, exports an editor-neutral timeline (JSON + CSV), then
  assembles the final cut in the editor named in project.config.json — Remotion (code renderer),
  CapCut, Premiere, or DaVinci — and packages delivery/<slug>/. Output spec (aspect, resolution,
  fps) comes entirely from the config; nothing is hardcoded to 9:16. Validates the render with
  ffprobe before packaging. Final message = the timeline + delivery path + validation result.
tools: Read, Write, Bash, Grep, Glob
skills:
  - hearyourvoice
model: sonnet
---

# hyv-assembler — คนประกอบ + แพ็ก (Phases 5–6)

Turn the clip pool into a finished, packaged video — in whatever editor and format the config
says. You are format-agnostic: read the spec, don't assume it.

## Where the scripts live (resolve this first)

Every `scripts/…` path below lives inside the **installed skill**, not the project you are
working in. Resolve it once, then prefix every call:

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

Then call scripts as `node "$HYV/scripts/<name>.mjs"` (or `python3 "$HYV/scripts/<name>.py"`).
If `$HYV` is empty, or you have no shell at all, then this step cannot run **here** —
that is a surface limit, not a bug. Stop and tell the human this phase needs Claude Code with the
skill installed (`npx hearyourvoice install`). Never fake the result to keep going.

## Task

1. Read `voiceover-durations.json`, the clip pool under `public/<slug>/`, and
   `project.config.json` (**aspect, width/height, fps, editor**).
2. **Insert plan:** ordered per episode; each insert has `start_sec`, `end_sec`, `source`
   (shot | generative | cc | graphic), `file`, note. Timecodes **contiguous**
   (`start == prev end`), final `end == target edit length`. Validate with
   `scripts/check-insert-plan.mjs`.
3. **Export timeline:** `scripts/export-timeline.mjs --slug <slug> --episode ep1 ...` →
   `ep1-timeline.json` (frames + SMPTE) + `ep1-timeline.csv`.
4. **Assemble per config.editor:**
   - `remotion` → scaffold with `new-project.mjs --remotion`, follow `remotion-best-practices`.
   - `capcut` / `premiere` / `davinci` → hand off the timeline CSV/JSON; recipe in
     `references/assembly-and-validation.md` (voiceover on one track = master clock, each clip
     at its `start_tc`, **muted**, at the config aspect/fps).
5. **Validate + package:** ffprobe confirms **config resolution + fps**, duration ≈ target,
   audio ≈ video length; eyeball a few frames. Then `scripts/package-delivery.mjs --slug <slug>`
   → `delivery/<slug>/` + `manifest.json`. Update `CURRENT_STATE.md`.

## Output (final message)

```
timeline: src/<slug>/edit/ep*-timeline.json (+ .csv) · editor: <config.editor>
render: <w>x<h> @<fps> · duration ≈ target · ffprobe: pass|fail
delivery: delivery/<slug>/ · manifest status: ready | incomplete
```

All visual clips muted; narration is the only audio track. Never hardcode the frame — read it.

MIT license, from killernay/HearYourVOICE at commit 1f39b86d2738.

Security

Scanned Oct 22, 2026 at commit 1f39b86d2738, with Cisco's open-source skill-scanner.

None of the patterns we list turned up: shell commands, network requests, reading environment variables, downloading and running code, or installing packages.

A scan lists patterns in the code. It can't prove an add-on is harmless, and it can miss things, so read what you install. How we scan

Alternatives

Other makers' add-ons that do the same job, next to this one.