Add and remove

Edit sources.yml to add and remove episodes, and earmark.toml to change the settings.

After setup, you edit one file, sources.yml. Each entry in it is one episode. Each commit starts a run that makes the episodes match the list: it dictates new entries, removes deleted ones, and dictates again any entry whose MP3 is missing.

Add something

Edit sources.yml in the GitHub web editor (the pencil icon works on a phone too), add a line, and commit:

- https://example.com/an-article-i-meant-to-read
- files/attention-is-all-you-need.pdf
- source: https://example.com/a-long-read
  title: A better title
  voice: bf_emma
  • A URL is fetched and dictated.
  • A document (PDF, DOCX, PPTX, EPUB, HTML, Markdown) must be in the repo. Upload it into files/ with Add file → Upload files. Then list it by its path, such as files/paper.pdf.
  • An entry can also be a source: with its own title, author, date, voice, speed or profile. See the sources.yml reference.

A run takes about half as long as the audio it makes, so a 25-minute article takes about 12 minutes. The Actions tab shows its progress. When it is done, pull to refresh in your podcast app.

Remove something

Delete the entry’s line in sources.yml and commit. The next run removes the episode, its MP3 and its text.

Deleting only the MP3 does not remove an episode. While the entry is still in sources.yml, the next run dictates it again.

Dictate something again

Delete its MP3 in audio/ and commit. The next run dictates it again with the current settings. Do this after you change the voice, the speed or a [replace] word, because a change to a setting only applies to new episodes.

In the web editor, open audio/, click the MP3, then ⋯ → Delete file.

Change the settings

The first run writes earmark.toml into the repo. Edit it in the web editor to change the defaults for new episodes: the voice, the speed, the feed title, or the cover image. Settings lists every setting you can change, in earmark.toml or on one entry in sources.yml.

Limits

  • Everything in a public repo is public. This includes every file in files/. Only upload what you have the right to share. GitHub Pages on a private repo needs a paid plan.
  • One file cannot be larger than 100 MB. At the default bitrate, that is about 3.4 hours of audio. Split a longer book, or lower bitrate in earmark.toml.
  • A Pages site stops at about 1 GB, which is about 30 hours of audio. The run summary warns you after 800 MB. Delete old entries from sources.yml to stay below the limit.