Installation

uv, ffmpeg, and the one Python version constraint that matters.

earmark needs three things:

Only the ffmpeg line differs by platform:

brew install ffmpeg

Debian or Ubuntu:

sudo apt install ffmpeg

Fedora:

sudo dnf install ffmpeg
winget install Gyan.FFmpeg

choco install ffmpeg and scoop install ffmpeg work too. Any of them puts ffmpeg.exe on your PATH, which is all earmark looks for. Open a new terminal afterwards so the new PATH is picked up.

The rest is the same everywhere:

git clone https://github.com/jhelvy/earmark.git
cd earmark
uv tool install --python 3.12 -e .

That puts earmark on your PATH in an environment of its own. You never activate anything to use it. The -e makes the install track the repo, so a git pull takes effect immediately.

Check it:

earmark --version

Why Python 3.11 or 3.12 specifically

The Kokoro toolchain does not support 3.13 or newer, and earmark pins requires-python = ">=3.11,<3.13" to keep the optional misaki[en] extra installable. If your system Python is newer than 3.12 (and on a current macOS it probably is), the --python 3.12 flag above is what makes the install work: uv downloads a suitable interpreter rather than using the system one.

Why ffmpeg

ffmpeg encodes the MP3 and normalizes cover art. It is a runtime prerequisite rather than a Python dependency, so it has to be installed separately with your system’s package manager, using one of the commands above. earmark finds it by looking for ffmpeg on your PATH and stops with an error before doing any work if it is not there.

Which platforms this runs on

macOS, Linux and Windows. Nothing in earmark is platform-specific: the dependencies are pure Python plus onnxruntime, which ships wheels for all three, and paths come from platformdirs, so the model, the cache and the default-library pointer land in the right place on each.

Two caveats worth stating plainly:

  • Windows is untested. It is expected to work and there is no known reason it would not, but nobody has run the suite there yet. If you try it, an issue saying so either way is welcome.
  • The say engine is macOS-only. It shells out to the built-in macOS say command and refuses to start anywhere else. It exists so earmark can narrate something before the 354 MB download finishes; Kokoro, the default engine and the reason to use earmark at all, runs everywhere.

One Windows-specific nuisance: a path with a space in it (C:\Users\me\My Drive\earmark) has to be quoted, exactly as ~/pCloud Drive does on macOS.

The model downloads itself

The first time you convert something, earmark asks before pulling the 354 MB Kokoro model, then shows a progress bar. There is no separate download command; it happens once and then never again.

The model lives with your application data, not in your library: you do not want 354 MB syncing to a public folder. The same is true of the synthesis cache and the one-line pointer naming your default library. Everything else earmark writes goes in the library.

Running the tests

The .venv/ in the repo is for running the tests, not for running the tool:

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

Tests marked slow load the real Kokoro model and are excluded by default.

Next: Quickstart.