yukkuri-video-generator: The Repo That Builds Videos by Listening First
A Python pipeline for Yukkuri commentary that turns script text into rendered MP4s only after the voice exists, the duration is known, and the timeline can be locked to reality.
- This repo’s real trick is not video editing, it is waiting for synthesized audio and then treating the measured duration as the source of truth.
- The pipeline reads like a small production system because parsing, synthesis, subtitles, and composition each depend on the previous stage finishing correctly.
- Its YAML settings and meta files make the project feel reusable and AI-maintainable, not like a one-off script.
- In the Yukkuri ecosystem, this occupies a narrow but useful niche: script in, rendered MP4 out, with far less manual assembly.
Why this repo feels more like a production system than a script
Most lightweight video tools guess timing from text and then force the visuals to fit. This repo does the opposite. It synthesizes the voice first, reads the actual WAV duration, and only then builds the rest of the timeline around something real.
That order matters. It turns lip-sync, subtitles, and sprite placement from estimates into dependencies, which is a much safer way to automate a media workflow.
Yukkuri videos, without the manual assembly line
If you do not already know the format, Yukkuri videos are built from static character avatars, synthetic voices, and subtitles. The hard part is not any single element. It is stitching them together repeatedly without spending your life in a timeline editor.
| Workflow | Input style | Main job solved | Where timing comes from | Manual editing | Best use case | Main limitation |
|---|---|---|---|---|---|---|
| Manual YMM4 assembly | Script plus assets | Hand-built Yukkuri episodes | Human timing and editor judgment | High | Fine-grained creator control | Slow and repetitive |
| This repo | Script in, MP4 out | Automated Yukkuri rendering | Measured audio duration | Low | Batch production from text scripts | Depends on VOICEVOX and local assets |
| AutoYukkuri | Live voice commentary | Convert spoken footage into YMM4 projects | Speech recognition timing | Medium | Creators who start from recorded narration | Still centered on YMM4 workflows |
| KuchiPaku | Timing label files | Automate lip-sync and expression placement | External label files | Medium | Timeline assistance inside YMM4 | Solves a narrower problem |
| Bespoke automation scripts | Custom pipeline | End-to-end content generation | Varies by stack | Low to medium | Teams with unique publish workflows | Usually fragile and project-specific |
How the pipeline actually moves
The codebase is cleanly separated. The parser turns raw text into dialogue objects. The voice layer calls VOICEVOX. The subtitle layer wraps text for the screen. The composer stitches everything into a single render pass.
# The important pattern is dependency order, not a specific framework.
parsed = script_parser.parse(script_text)
for line in parsed:
audio_file = voice_synthesizer.synthesize(line.text, speaker_id=line.speaker_id)
duration = AudioFileClip(audio_file).duration
subtitle = subtitle_generator.build(line.text, duration=duration)
video_composer.add_segment(audio=audio_file, subtitle=subtitle, duration=duration)
final_clip = video_composer.compose()
Why the config file matters more than it looks
The YAML layer is not just convenience. It is the reason the project can stay extensible. Character positions, speaker IDs, and layout settings live outside the core logic, so new setups do not require rewriting the engine.
video:
resolution:
width: 1920
height: 1080
characters:
reimu:
speaker_id: 1
position:
x: 180
y: 620
marisa:
speaker_id: 2
position:
x: 1460
y: 620
voicevox:
host: "http://127.0.0.1:50021"
The repo is also documenting how AI should collaborate with code
I created an automated tool that takes a script and outputs the main video, short video, and thumbnail in under 7 minutes. Since I'm also instructing ChatGPT to create the script, I feel like I've become a machine that just passes scripts to the program and hits a single command.
This repository’s meta files matter because they treat process as part of the product. The code is not only describing how to render a video. It is also telling collaborators, including AI collaborators, how to work inside the repo.
That is a bigger shift than it first appears. A project with explicit maintenance rules, implementation notes, and workflow constraints is easier to extend safely than a pile of scripts with no operating model.
What this competes with, and what it avoids
The comparison is not about which tool is better in the abstract. It is about where each one sits in the workflow. Some tools help you start from a live recording. Some help you lip-sync inside YMM4. This repo tries to remove the editing middle layer entirely.
| Tool | Primary input | Output | Timing model | Editing surface | What it avoids |
|---|---|---|---|---|---|
| Manual YMM4 | Script and assets | Hand-authored project | Human decided | Full editor UI | Automation |
| This repo | Script text | Rendered MP4 | Measured audio duration | Configuration files and Python modules | Guessing timing |
| AutoYukkuri | Spoken narration | YMM4 project | Whisper-derived alignment | YMM4-compatible workflow | Manual transcription |
| KuchiPaku | Label files and TTS timing | Lip-sync automation inside YMM4 | Label driven | Expression timeline tooling | Rebuilding the whole video stack |
| Bespoke scripts | Varies | Varies | Varies | Usually code only | Project-specific repeat work |
That niche is the whole story. It is not trying to replace every Yukkuri tool. It is trying to make one narrow path much faster and much more reliable.
Where it stands today
The repository reads like an early prototype with strong intent. The structure is clear, the separation of concerns is sensible, and the timing model is genuinely smart. The missing pieces, like tests and complete asset coverage, make it feel unfinished in the honest way prototypes should.





