# Settings


# Change the voice or the speed of every episode

This is the change most people want. Open `earmark.toml` in your library and edit these lines. On GitHub, the file is in your repo after the first run, and the pencil icon opens it. Locally, `earmark config` opens it.

``` toml
voice = "bf_emma"   # hear every voice below
speed = 1.1         # 0.5 to 2.0
lang = "en-gb"      # en-gb for a British voice, en-us for an American one
```

Commit the change, or save it locally. Every episode made after that uses the new voice and speed. Episodes you already have keep the voice they were made with. On GitHub, delete an episode's MP3 in `audio/` to dictate it again with the new voice.

You do not need to repeat these settings in `sources.yml`. An entry uses them unless it sets its own.


# Where settings go

You can change a setting in three places. They are the same settings, whether you use earmark on GitHub or on your own computer.

| Where | Applies to | How |
|----|----|----|
| **`earmark.toml`** | every new episode | Edit the file in your library. On GitHub, use the web editor. Locally, run `earmark config`. |
| **`sources.yml`** | one entry | Write the entry as a `source:` with the setting under it. |
| **A command-line flag** | one command | Add the flag, such as `--voice bf_emma`. Local only. |

When one setting is in more than one place, the more specific one wins:

1.  a flag, or a setting on a `sources.yml` entry
2.  `earmark.toml`
3.  the built-in default

A setting changes new episodes only. To make an existing episode again with a new setting, delete its MP3 on GitHub (see [Dictate something again](../github/add.md#dictate-something-again)), or run `earmark publish SOURCE --refresh` locally.


# The voice

| Setting | `earmark.toml` | `sources.yml` | Flag | Default |
|----|----|----|----|----|
| Voice | `voice = "bf_emma"` | `voice: bf_emma` | `--voice bf_emma` | `af_heart` |
| Speed, `0.5` to `2.0` | `speed = 1.2` | `speed: 1.2` | `--speed 1.2` | `1.0` |
| Pronunciation language | `lang = "en-gb"` | `lang: en-gb` | `--lang en-gb` | `en-us` |

- **Voice.** The first letter of a voice name is its language: `a` is American English, `b` is British English. The second letter is `f` for female or `m` for male. To hear any voice read your own text, use the [Kokoro demo](https://huggingface.co/spaces/hexgrad/Kokoro-TTS), or locally run `earmark voices --try bf_emma`. `af_heart` and `af_bella` are the best voices.
- **Speed.** `1.0` is the voice's natural pace. Your podcast app can also play faster. A setting here is useful when you want every episode faster without changing the app.
- **Pronunciation language.** Set it to match the voice, such as `en-gb` for a `b` voice.


## Hear the suggested voices

Each voice says the same line. Kokoro grades every voice, from A down to F, and these are the ones graded C or better. For a British voice, also set `lang` to `en-gb`.

| Voice         | Accent   | Gender | Grade | Listen |
|---------------|----------|--------|-------|--------|
| `af_heart`    | American | female | A     |        |
| `af_bella`    | American | female | A-    |        |
| `af_nicole`   | American | female | B-    |        |
| `af_aoede`    | American | female | C+    |        |
| `af_kore`     | American | female | C+    |        |
| `af_sarah`    | American | female | C+    |        |
| `af_alloy`    | American | female | C     |        |
| `af_nova`     | American | female | C     |        |
| `am_fenrir`   | American | male   | C+    |        |
| `am_michael`  | American | male   | C+    |        |
| `am_puck`     | American | male   | C+    |        |
| `bf_emma`     | British  | female | B-    |        |
| `bf_isabella` | British  | female | C     |        |
| `bm_fable`    | British  | male   | C     |        |
| `bm_george`   | British  | male   | C     |        |


# The text

| Setting | `earmark.toml` | `sources.yml` | Flag | Default |
|----|----|----|----|----|
| Profile | `profile = "paper"` | `profile: paper` | `--profile paper` | `article` |
| Words to say differently | a `[replace]` table |  |  | none |

A **profile** is a set of cleaning rules for one kind of text:

| Profile | For | What it changes |
|----|----|----|
| `article` | web articles and blog posts | nothing; these are the defaults |
| `paper` | academic papers | removes author-year citations such as "(Smith, 2020)" and skips everything before the abstract |
| `book` | books and long reports | describes tables instead of skipping them, and keeps the reference list |

**Words to say differently.** When a word is dictated wrongly in every episode, fix it once in `earmark.toml`:

``` toml
[replace]
BEV = "battery electric vehicle"
NIMBY = "nimby"
```

Locally, you can also fine-tune the cleaning of one document with flags such as `--keep-references`, `--keep-citations`, `--tables describe` and `--drop-sections "Appendix"`. See [`earmark text`](../reference/text.md) for all of them.


# The episode

| Setting | `sources.yml` | Flag | Default |
|----|----|----|----|
| Title | `title: A better title` | `--title "A better title"` | found in the source |
| Author | `author: Jane Doe` | `--author "Jane Doe"` | found in the source |
| Date | `date: 2026-01-31` | `--date 2026-01-31` | found in the source, else today |
| Spoken title |  | `--no-title-card` | on |

Each episode starts by saying its title and author. `--no-title-card` turns that off.


# The podcast

These are in the `[feed]` table of `earmark.toml` and apply to the whole feed.

| Setting | `earmark.toml` | Default |
|----|----|----|
| Podcast title | `title = "My Reading Pile"` | the repo name on GitHub, `earmark` locally |
| Author | `author = "Jane Doe"` | none |
| Description | `description = "Things I meant to read."` | none |
| Cover image | `cover = "art.png"` | none |

For `cover`, put a PNG or JPEG in the library, such as `art.png` next to `earmark.toml`, and name it in the setting. It does not have to be square or the right size. earmark makes a copy that podcast apps accept and leaves your file as it is. Apps can take hours to show a new cover.


# The audio file

| Setting     | `earmark.toml`        | Flag                  | Default |
|-------------|-----------------------|-----------------------|---------|
| MP3 bitrate | `bitrate = "48k"`     | `--bitrate 48k`       | `64k`   |
| Sample rate | `sample_rate = 24000` | `--sample-rate 24000` | `44100` |

The defaults suit speech. A lower bitrate makes smaller files, which helps on GitHub, where one file cannot be larger than 100 MB and the site stops at about 1 GB.


# Example

An `earmark.toml` with a British voice, a little faster, and a podcast title:

``` toml
voice = "bf_emma"
lang = "en-gb"
speed = 1.1

[replace]
BEV = "battery electric vehicle"

[feed]
base_url = "https://you.github.io/my-library"
title = "My Reading Pile"
cover = "art.png"
```

A `sources.yml` where one paper uses its own settings:

``` yaml
- https://example.com/an-article
- source: files/attention-is-all-you-need.pdf
  profile: paper
  voice: am_michael
  lang: en-us
```

The [configuration reference](../reference/configuration.md) lists every key, including the rarely needed ones, with the errors that each wrong value gives.