hacker-press: The Publishing Pipeline That Compiles a Book Into Audio, Video, and EPUB

A single Markdown source becomes synchronized audiobooks, browser-rendered video, print-ready PDFs, and hacker-friendly text formats through deterministic builds and AST-level transforms.

8 min read • View on GitHub • More from sebastiancarlos

A single manuscript sits at the center of a mechanical print shop, splitting into several output paths. One path becomes a bound book and PDF pages, another becomes an audio waveform, and another becomes a strip of browser frames. The image explains the core idea that one source file can compile into many synchronized media artifacts. — hacker-press treats a book like build input, then fans it out into multiple finished formats without changing the source of truth.

Key Takeaways

hacker-press is not a document converter, but a media compiler that treats a manuscript like build input.
Its most unusual move is using the browser as the renderer for synchronized audio video output.
The pipeline relies on AST-level transforms and content-addressed caching so small edits do not force full rebuilds.
Its format support is broad by design, but the deeper goal is deterministic control over every artifact.

The strange thing about hacker-press is not that it exports many formats. Plenty of tools do that. The real trick is that it behaves less like a converter and more like a compiler, where one Markdown source can become EPUB, PDF, MP4, MP3, and terminal-native output without losing structure or sync.

That changes the authoring problem. Instead of juggling separate edit passes for print, audio, and video, Sebastian Carlos builds one canonical source and lets the pipeline derive everything else. The result is a publishing system that feels closer to software release engineering than traditional book production.

The book that ships like software

The project was built for Hacker Fables, and that origin matters. The point is not generic CMS convenience. It is a workflow where a manuscript can be rebuilt deterministically, tested, and distributed in multiple media forms from one repository.

A Pandoc pipeline to build documents and audiobooks out of a single source markdown (used for the novel "Hacker Fables").

Sebastian Carlos, Author/Maintainer · sebastiancarlos/hacker-press

That framing explains the repo’s personality. It is opinionated about source of truth, opinionated about reproducibility, and deeply comfortable with the idea that a book can have a build graph.

Why the browser is part of the publishing stack

The browser is not a preview tool here. It is the renderer that turns spoken text into frames, then hands those frames to FFmpeg.

A close-up of a browser window acting like a print head. The page text is highlighted word by word while a waveform advances below it, and a camera frame and video strip sit in a tight mechanical loop. The image explains how live HTML becomes synchronized video output rather than a passive preview. — The browser drives the visual side of the audiobook and MP4 pipeline, while the audio and highlight state stay locked together.

This is the most important mental shift in the repo. HTML is not an output to inspect and then discard. HTML is the rendering surface that the video pipeline uses to create the final artifact.

Markdown is not text here. It is an AST

-- Conceptual example of the Pandoc filter approach
function Para(el)
  if el.content then
    el.identifier = el.identifier or make_utterance_id(el)
  end
  return el
end

function Div(el)
  if has_class(el, 'audio-ignore') then
    return {}
  end
  return el
end

The repo leans hard on Pandoc Lua filters because strings are the wrong abstraction for this job. If a block is an utterance, then it needs an ID, a cache key, and rules about whether it should participate in speech at all.

That is why files like utterance-ids.lua and audio-ignore.lua matter. They let the build system reason about meaning, not raw Markdown syntax.

How synchronized audio stays aligned

Problem	Typical publishing stack	hacker-press
Audio reuse	Re-record or regenerate whole chapters	Cache utterances by content hash
Text sync	Best-effort manual timing	Block IDs drive highlight timing
Video creation	Edit in a separate NLE	Render browser frames from the same HTML source
Build behavior	Often partial and ad hoc	Deterministic and reproducible

The reliability story is in the small details. Utterances are hashed, cached, and regenerated only when content changes. Audio duration is measured, padded, and kept in step with the frame rate so the spoken and visual tracks do not drift apart.

That makes the system feel less like TTS glued onto a document converter and more like an artifact pipeline with real build discipline.

Why EPUB, PDF, and man pages all matter

Format	Why it exists here	What it signals
EPUB	Portable long-form reading on dedicated devices	The book still matters as a book
PDF	Print-ready and layout-stable export	Typography and preservation matter
MP3	Synchronized audiobook delivery	Speech is a first-class output
MP4	Video with highlighted text	The browser is part of the media pipeline
man page	Unix-native reference format	This is built for hacker culture, not just mainstream publishing

The spread of outputs is not bloat. It is the point. The project says a serious authoring system should meet readers where they are, including the terminal.

The editorial philosophy behind hacker-press

Carlos is not building a general-purpose CMS. He is building a publishing system for a specific worldview: local-first, deterministic, hacker-friendly, and deeply suspicious of handwork that can be automated.

The pipeline strips visual-only AST nodes, injects @@BLOCK:X@@ sync markers, spins up a Dockerized Piper TTS instance across 4 parallel threads, and generates an MP3 audiobook (with caching for speed on source changes).

Sebastian Carlos, Author/Maintainer · Hacker Fables README

That quote captures the ethos perfectly. The ambition is not just multi-format output. It is turning creative work into a reproducible system where edits, builds, and distributions stay in lockstep.

Where it sits in the publishing ecosystem

Tool	Strength	What it is not
Pandoc	Excellent document transformation engine	A full media compilation stack
Quarto	Polished technical publishing platform	A hacker-first audiobook and video compiler
GitBook / HonKit	Good web documentation workflows	A deterministic multi-media build pipeline
Softcover / Bookbind	Strong self-publishing output	A browser-rendered synchronized audio system

So the right comparison is not “which tool wins.” It is category fit. hacker-press lives at the intersection of publishing, build systems, and media generation, which is a narrower and more interesting space than ordinary documentation tooling.

The cost of this kind of power

The tradeoff is real. This kind of control asks authors to think a bit like build engineers. They need to care about filters, caches, renderers, and artifacts, not just prose and layout.

But that is also the appeal. If you want a book that behaves like software, then software discipline is the price of admission.