Introduction
I run a bilingual (Japanese/English) tech blog with 882 articles. To repurpose this content as YouTube videos, I built an automated pipeline combining Claude Code's parallel agent feature with VOICEVOX text-to-speech.
In the process, I hit Claude Code's weekly usage limit — something that reportedly affects only the top 2% of users. Here's how the pipeline works and what I learned.
Pipeline Overview
Blog article (.md)
↓ Claude Code parallel agents (10 concurrent)
Dialogue script (sections.json)
↓ VOICEVOX × 3 parallel workers
Narrated video (video.mp4)
↓ YouTube API
Published on YouTube
1. Script Generation (Claude Code)
Each article is read and converted into a two-character dialogue script (sections.json). Using Claude Code's Agent tool, 10 agents run simultaneously for parallel processing.
[
{
"section_title": "Section Name",
"slide_points": ["Key point 1", "Key point 2"],
"lines": [
{"speaker": "usagi", "text": "KatakanaReadingText", "display_text": "Screen display text"},
{"speaker": "sora", "text": "KatakanaReadingText", "display_text": "Screen display text"}
]
}
]
text: For VOICEVOX reading (English technical terms in katakana)display_text: For on-screen display (English terms as-is)- Each article generates 6–10 sections with 6–8 lines each
2. Character Pair System
Four VOICEVOX character pairs are assigned to articles in rotation:
| Pair ID | Questioner | Explainer | Style |
|---|---|---|---|
| zundamon_metan | Zundamon | Shikoku Metan | Naive × Polite |
| tsumugi_kiritan | Kasukabe Tsumugi | Meimei Himari | Gyaru × Cool |
| usagi_sora | Chugoku Usagi | Kyushu Sora | Shy × Gentle |
| hau_whitecul | Amehare Hau | WhiteCUL | Energetic × Intellectual |
Standing character images are from Sakamoto Ahiru.
Note (2026-04-23): The
tsumugi_kiritanpair was originally assigned the voice and display name of "Meimei Himari" because I mistakenly believed Tohoku Kiritan was not included in VOICEVOX. After updating my local VOICEVOX to the latest version, I confirmed that Tohoku Kiritan (speaker_id=108), added in 0.24.1 (2024-07-08), is in fact available, and the affected videos are now being regenerated with Tohoku Kiritan's voice and display name.
3. Video Generation (Parallel VOICEVOX)
Three VOICEVOX Engine Docker containers distribute work via Python's multiprocessing.Queue:
# 3 VOICEVOX instances on different ports
docker run -d --name voicevox_50021 -p 50021:50021 voicevox/voicevox_engine:latest
docker run -d --name voicevox_2 -p 50022:50021 voicevox/voicevox_engine:latest
docker run -d --name voicevox_3 -p 50023:50021 voicevox/voicevox_engine:latest
Each instance uses ~600MB RAM and ~400% CPU, so 4 workers is the practical limit on a 16-core machine.
Note (added 2026-04-23): The article originally used the
cpu-ubuntu20.04-latesttag, but this tag stopped being updated around Ubuntu 20.04's EOL (May 2025) and is frozen at VOICEVOX 0.23.x. It does not include characters added in 0.24.1 (2024-07-08) such as the Tohoku sisters (Kiritan, Zunko, Itako). Uselatestorcpu-latestinstead.
Results
| Metric | Value |
|---|---|
| Total articles | 882 |
| Scripts generated | 659 |
| Videos generated | 542 |
| Average video duration | ~4 min 45 sec |
| Average video size | 15.1 MB |
| Total video size | ~8.2 GB |
| Sequential throughput | ~13 videos/hour |
| 3-worker parallel throughput | ~40 videos/hour |
Pair Distribution
Scripts were generated with balanced rotation across non-default pairs (early batches favored zundamon_metan):
| Pair | Count |
|---|---|
| hau_whitecul | 215 |
| tsumugi_kiritan | 189 |
| usagi_sora | 177 |
| zundamon_metan | 94 |
Hitting Claude Code's Usage Limit
What Happened
I'm on the Max $200/month plan — the highest tier available, with 20× the usage capacity of the Pro plan. Even so, Claude Code has a weekly usage limit, and according to the official docs, roughly the top 2% of users hit this limit. The fact that I hit it on the largest plan speaks to how heavy this workload was.
Here's how I got there:
- Launched 10 parallel agents per batch, continuously
- Each agent reads an article (~thousands of characters) and generates a JSON script (~thousands of characters)
- Batches 22–27: 60 agents spawned within a few hours
- Cumulative across sessions: hundreds of agents total
What the Limit Looks Like
When batch 28 (10 simultaneous agents) launched, every agent failed with:
You've hit your limit · resets 8am (Asia/Tokyo)
The limit uses a rolling window — recent usage is evaluated dynamically. Even after the limit was lifted, usage was at 80%, so I paused parallel agent work.
Lessons Learned
- Normal development work (editing code, asking questions, debugging) won't trigger the limit
- Parallel agents × batch processing is the heaviest usage pattern
- Reducing parallelism (10 → 5) can extend your budget
- Video generation (VOICEVOX) is independent of the Claude API, so it's unaffected
Video Structure
Each generated video follows this structure:
OP (6s) → Main content (dialogue + slides) → Bridge (4s) → ED (15s)
- Two character standing images alternate on screen
- Telop (subtitles) and slide bullet points displayed simultaneously
- VOICEVOX synthesized speech (24000Hz mono)
- BGM: Kevin MacLeod (incompetech.com) CC BY 3.0
Conclusion
Claude Code's parallel agent feature is remarkably powerful for large-scale content generation. Automating script generation for 882 articles and combining it with parallel VOICEVOX processing made it possible to produce videos at a scale that would be impractical manually.
However, if you're running parallel agents at scale, be mindful of the weekly usage limit. Plan your batches and adjust parallelism accordingly.
