earmark

Turn articles into narrated audio, then publish to a public podcast feed

Links

Issues

AI / Agents

Skills
llms.txt
llms-full.txt

Developers

John Paul Helveston

Author

Community

Full license MIT

Install

You need uv, ffmpeg, and Python 3.11 or 3.12 (uv will fetch it for you).

Go to the Installation page for details.

Main commands

Everything earmark makes lands in one folder you choose (your library), which should be a folder served on the public web.

There are 3 main commands:

Get the text: earmark text SOURCE
Narrate the text: earmark audio SOURCE
Publish to your feed: earmark publish SOURCE

In each step, the SOURCE can be an article URL or a document (PDF, DOCX, PPTX, EPUB, HTML, Markdown).

Also, each step will run the prior steps, so step 3 (earmark publish SOURCE) is all you need to run the whole chain from SOURCE to audio published in your feed.

The intermediate steps are there in case you want to edit the raw text before narrating the audio.

The other four commands are setup and housekeeping: init, config, feed, voices.

Start here

Installation	uv, ffmpeg, and the Python version that matters
Quickstart	empty folder to something playing on your phone
The library	why a library is a folder
The pipeline	`text`, `audio`, `publish`, and editing in between
Text cleaning	what gets rewritten before anything is spoken
Choosing a voice	54 voices and how to pick one
Publishing anywhere	GitHub Pages, rclone, rsync: one line each
Subscribing on your phone	where the feed URL goes in each app
Reference	every command, flag and config key

Development

uv venv --python 3.12
uv pip install -e ".[dev]"
.venv/bin/python -m pytest -q

The docs site is built with great-docs:

uv tool install great-docs
great-docs preview