dubyduby: Instructions file for Codex

dubyduby — Agent instructions

You're an AI agent (Claude, Codex, Cursor, etc.) helping a user dub YouTube videos into Korean.

Trigger

User says any of:

• "이 URL dub해줘"
• "dub this URL"
• "dub this video"
• "이 영상 한국어로"
• Pastes a YouTube URL with intent to translate

Two-phase workflow

bash scripts/dub.sh <URL> orchestrates everything. It runs in two phases with a pause between them where you (the agent) write the translation.

Phase 1 — download + transcribe (automatic)

bash scripts/dub.sh https://youtu.be/EXAMPLE

This:

1. Downloads video + audio via yt-dlp → output/<video_id>/1_source/{video.mp4, audio.mp3}
2. Calls Soniox STT batch → output/<video_id>/2_transcript/{tokens.json, transcript.md}
3. Pauses — prints instructions and exits.

If user wants only the first N seconds: bash scripts/dub.sh <URL> 120 (cuts at 120s).

Phase 2 — agent writes translation

Before translating: read glossary.json at repo root. It maps known STT misreads → canonical brand/term names, plus Korean phonetic spellings used in TTS. Apply during transcript cleanup before writing sentences.json.

Read output/<video_id>/2_transcript/transcript.md (full EN text from Soniox).

Write output/<video_id>/3_translation/sentences.json as an array of {en, ko}:

[
  { "en": "Hey everybody,", "ko": "여러분 안녕하세요." },
  { "en": "Opus 4.7 just dropped a few minutes ago,", "ko": "Opus 사 점 칠이 방금 출시됐는데요." }
]

Then re-run the same orchestrator command:

bash scripts/dub.sh https://youtu.be/EXAMPLE

This time it detects sentences.json and proceeds: match_timing → synthesize → finalize → output/<video_id>/6_final/dubbed_video.mp4.

Glossary — STT misread fix + Korean phonetic

glossary.json (repo root) is the source of truth for brand names and recurring terms. Each entry:

{
  "canonical": "Claude Code",
  "stt_misreads": ["Cloth Code", "Cloud Code"],
  "korean_phonetic": "클로드 코드",
  "category": "ai-product"
}