MLXnarrator

Give a silent screen recording a voice — offline, on a Mac. Write a plain-text script; a local Kokoro text-to-speech model speaks it, Whisper writes the subtitles, and ffmpeg renders the finished MP4. No cloud, no API keys.

Trail statsTelemetry · at a glance

100%
offline: no cloud, no API keys, no per-minute fees
82M
Kokoro voice model, running locally on Apple Silicon
1.30×
speed-up ceiling before the narration is flagged as rushed
2
render modes: burned-in subtitles, or none with no re-encode

01 · The Map · Mission Brief

Brief

Every demo video has the same problem: it's twelve seconds of you clicking things and eleven seconds of you wishing you had said something clever.

MLXnarrator fixes that. You write what you want to say in a plain text file. It speaks the script with a local text-to-speech model, fits the narration to your video, listens to itself with Whisper to produce subtitles, and renders a finished MP4 with ffmpeg — on an Apple Silicon Mac, with no cloud, no API keys, and no “your free trial has ended” email.

Don’t take my word for it — the receipts are on GitHub

02 · The Pack · Crew Duties

My Contribution

Built the whole pipeline: script → Kokoro-82M speech (running through MLX on Apple Silicon) → fit to the video’s length → whisper.cpp subtitles → an ffmpeg render.
Made the narration fit the video by speeding it up, never slowing it down, and having the tool warn (default threshold 1.30×) when it starts sounding like an auctioneer.
Generated subtitles from the final audio rather than from the script, so the timing is never a guess — then left them as a plain .srt you can proofread. Re-rendering never overwrites your edits, and any existing SRT is backed up with a timestamp before it can be regenerated.
Added two render modes: burned-in subtitles, or none at all — the fast mode copies the video stream, so it finishes in seconds with no quality loss, with an optional H.264 re-encode.
Cleaned the script automatically before speech — Markdown headings and rules, timestamp section markers, bold/italic markers, backticks, and link URLs are all stripped so the text file can stay tidy.
Wrapped every step twice — as a terminal script and as a double-click Finder launcher — so it works for people who never open a terminal, and added a voice-listing helper, an LLM prompt pack for drafting narration, and docs for setup and troubleshooting.

03 · The Cabin · The Satellite

System Architecture

Kokoro TTS (MLX)

src/narrate.py reads the cleaned script and speaks it with Kokoro-82M, which runs on Apple Silicon through MLX. A small model with a surprisingly human voice; the voice and speed are one-line settings.

Fit to the video

The narration is time-stretched with ffmpeg’s atempo filter to match the video length (never slowed), with a configurable warning above 1.30× and a short silent tail left at the end. Output: narration-fit.wav.

whisper.cpp subtitles

whisper.cpp transcribes the final, fitted audio into narration.srt — a plain file you proofread before rendering, with line length capped at 60 characters.

ffmpeg render

Renders output/demo-final.mp4 with burned-in subtitles (via an ffmpeg build with libass), or a no-subtitles version that copies the video stream. Any audio already on the recording is kept quietly underneath the voice.

Scripts and launchers

Each step is a shell script in bin/ with a matching double-click .command launcher, plus a run-everything shortcut. Settings live in the scripts, so there is only one place to edit.

04 · The Ridge · Asteroid Belt

Technical Challenges

Burning subtitles needs libass

Homebrew’s plain ffmpeg can’t burn subtitles, so the project uses the keg-only ffmpeg-full build, which the scripts find automatically — while the plain ffmpeg still handles the no-subtitles render.

Narration that outruns the video

A script that’s too long for the footage has to be sped up. The tool speeds up but never slows down, and flags anything beyond 1.30× so you shorten the script instead of shipping a rushed read.

Double-click launchers on macOS

Finder launchers can be blocked by quarantine flags and start with a different PATH than the terminal. The docs cover the chmod / xattr fixes and initialising Homebrew for login shells.

05 · Sunrise · Planet-rise

Takeaways

Most of the design is about keeping the human in control: every stage leaves a plain file you can inspect or fix — the script, the audio, the subtitles — and nothing you edit is silently overwritten. The model does the speaking; you still decide what gets said, and how it reads.

Previous waypointPrevious burn · 2 of 10

FoundYou

One global ID across every camera

Next waypointNext burn · 4 of 10

RoleSense

An AI resume screener across 40+ job categories

All Projects