---
name: "devlog_video_automation"
description: "Turn repo activity into a narrated devlog video: mine git history for story beats, write narration that sounds like a person talking, synthesize voiceover with any neural TTS, and assemble the edit with ffmpeg. Use when someone wants devlog episodes generated from a release cycle, a changelog turned into a video, or a repeatable release-to-video publishing pipeline that runs every release with the same effort."
---

# Devlog Video Automation

## Purpose

Take a development period (a release, a sprint, a week of commits) and turn it into a finished narrated devlog video with minimal hand work. The pipeline mines real git history for story beats, drafts narration over actual evidence, renders voiceover, and assembles the edit. It is built to run on a release cadence, so episode ten costs the same effort as episode one.

Tool-agnostic by design: any git repo, any neural TTS voice, any publishing platform. The craft lives in beats one and two; everything after is machinery.

## Workflow

### 1. Mine story beats

Run the miner against the repo for the period:

```bash
python3 bin/mine_beats.py /path/to/repo --since v1.2.0 --until HEAD -o beats.json
```

It reads history with read-only git commands and clusters commits into story beats: features, fixes, refactors, reversals, docs, deps. Every beat carries evidence: commit hashes, dates, authors, diffstat, the actual message text. Commit messages are treated as claims, diffs as the evidence that backs them. A beat with weak evidence (junk subjects like "fix stuff" or "update", no diff info) gets flagged, not invented.

### 2. Draft narration

Open `references/narration-craft.md` and write one narration segment per beat, 20-45 seconds each. Rules: one idea per beat, concrete nouns over abstractions, no invented numbers or quotes, technical terms spelled for the TTS voice. Save as `narration.yaml`:

```yaml
segments:
  - beat: features
    text: "The big one this week: the plugin system finally landed. Three new hooks, one config file, and the old monkey-patching is gone for good."
    visual: cards/01-plugin-system.png
  - beat: fixes
    text: "We also killed the auth race condition that had been haunting the login flow since March. Turns out the token refresh was firing twice."
    visual: cards/02-auth-fix.png
```

### 3. Render voiceover

Pick one voice and keep it for the entire series. Swapping voices mid-season breaks the illusion. Generate one audio file per segment (edge-tts, ElevenLabs, OpenAI TTS, any neural voice). One segment per file is the discipline that keeps timing clean. Validate: every file has real size, no empty renders, spot-listen to the first and last segment.

### 4. Assemble the edit

Follow `references/assembly.md`: one title card per beat, slow Ken Burns drift on each card, narration audio padded to exact video length (never trust `-shortest` on the mux, it clips tails), per-segment mux then concat, subtitles burned in or shipped alongside as SRT.

### 5. Quality gate

Watch the full episode once at 1x speed before it ships:

- No silent gaps longer than a breath, no narration stepping on a transition.
- Technical terms pronounced right. If the voice mangles one, rewrite the spelling in the segment text and re-render that segment only.
- Every factual claim in the narration traces to a commit in beats.json. If it does not, cut it.
- Title, thumbnail, and description ready (see `references/publishing.md`).

### 6. Publish on cadence

Tie publishing to the release cycle, not to inspiration. Numbered episodes, consistent titles, the same upload slots each cycle, one short trailer clip per episode for socials. See `references/publishing.md`.

## Output Contract

- `beats.json`: mined story beats with commit evidence
- `narration.yaml`: narration segments with matching visuals
- `audio/segNN.mp3`: one TTS file per segment
- `devlog-NN.mp4`: finished episode, subtitles burned in or shipped alongside
- `devlog-NN.srt`: subtitle file
- `thumbnail.png` + `description.txt`: ready for upload

## Operating Rules

1. Every factual claim in the narration must trace to a commit in beats.json. Unverifiable means cut it or frame it as opinion.
2. Never invent numbers, dates, quotes, or events. Specific-sounding fiction is the failure mode this skill exists to prevent.
3. One voice for the whole series. No exceptions.
4. One idea per beat, one audio file per segment. Script discipline is what makes assembly reliable.
5. When a commit message and its diff disagree, the diff wins, and the narration says so.
6. Keep the pipeline boring: same commands every episode, same directory layout, same checklist. Save the creativity for the story.