Open a book and press Space.

No. 01

Reading

Books, keys, web serials, audio and settings.

Earmark opens EPUB, PDF, plain text (.txt, .md) and HTML. Plain text is split into chapters at headings like “Chapter 12”.

The first time Earmark opens, a short tour points out the controls. Skip it any time; Help → Show Tutorial plays it again.

Opening books

Open a book with ⌘O, from File → Open Recent, by dragging it onto the Dock icon, or with Open With → Earmark in Finder.

Every book reopens where you left off, and Earmark starts with the last one you were reading. Your place is tied to the book itself, so moving or re-downloading the file keeps it.

• Click any sentence to start reading from it. The status line shows where you are in the book, and the chapter menu follows along.
• Playback carries on into the next chapter by itself, without a gap: the next chapter’s first sentences are prepared while the current one finishes.
• Scroll back to re-read and the page stays put for a few seconds before following the voice again.
• After a pause of more than 30 seconds, the sentence starts over.
• Drag the window by its top edge or the empty parts of the control bar.

Keys

Space or ⌘P

Play / pause

⌘→ ⌘←

Next / previous sentence

⌘] ⌘[

Next / previous chapter

⌘G

Go to a chapter by number or title (a page, in a PDF)

⌘= ⌘-

Faster / slower

⌥⌘= ⌥⌘-

Bigger / smaller text (zoom, in a PDF)

⌥⌘] ⌥⌘[

Wider / narrower column

⌥⌘0

Back to the usual text size and column width

⌘F

Find in the book. Return goes to the next match, moving on to later chapters; Shift-Return goes back.

⌥⌘C

Copy the sentence being read

⇧⌘V

Read the clipboard: text opens as a book, a link opens its page

⌘L

Open a web page, optionally following its “Next” links

⇧⌘E

Export chapters as audio

⌘.

Stop a web page download or an audio export

⌘D

Bookmark the current sentence; the Bookmarks menu lists them

⌘R

Reload settings, skipped lines, pronunciations and plugins

⌘,

Settings

Media keys

Play / pause and next / previous sentence, from the keyboard, AirPods or Control Center

Web serials and pasted text

File → Open Web Page (⌘L) takes a chapter’s address, pulls out the chapter text, and can follow the page’s “Next” links up to a limit you set in Settings. The result is saved as an EPUB in Documents/Earmark and opens right away. Stop it with ⌘. and the chapters so far are kept.

Sites that show a browser check instead of the page can’t be downloaded this way. Save the page from your browser and open the file instead.

File → Read Clipboard (⇧⌘V) opens copied text as a book, or a copied link as its page. Pasted text is kept so it shows up in Open Recent, and is deleted after the number of days set in Settings (30 to start with).

Saving as audio

File → Export Audio (⇧⌘E) saves a range of chapters as M4A files, one per chapter, using the current voice, speed, pronunciations, skipped lines and pauses. It works with system voices and plugin voices, and ⌘. stops it.

Settings and the sleep timer

Earmark → Settings (⌘,) holds the optional extras. All of them start off, so Earmark behaves as described here until you change them:

• Theme: match the system, or always light, sepia or dark
• Font and line spacing
• Start from the first sentence on screen when you press Play after scrolling away
• Jump by: how many sentences the previous and next keys move
• Pauses after each sentence, paragraph and chapter, in milliseconds
• Sleep timer length, and whether to Remember it for every Play
• Keep pasted text for a number of days
• Web serials: the most chapters to follow

Set the sleep timer from Playback → Sleep Timer or in Settings, from 15 minutes to 2 hours, or to the end of the chapter. While it runs, a moon with the minutes left sits in the control bar; click it to start the timer over. Tick Remember in Settings and the same timer starts each time you press Play.

Unplugging headphones pauses reading instead of switching to the speakers.

Skipped lines and pronunciation

Web novels repeat lines like “Translator: … Editor: …” in every chapter. Earmark skips any sentence that matches a pattern in ~/Library/Application Support/Earmark/skip.txt, which starts with a few common ones.

To fix how a word is said, add from => to lines to replacements.txt in the same folder, such as Lv. => level. The page keeps the original text, and the highlight still lands on it.

Both files open from the bottom of the voice menu (Edit Skipped Lines… and Edit Pronunciations…), and File → Reload Settings (⌘R) applies your changes.

No. 02

Voices

The voices on your Mac, and Google’s as a plugin.

The voice menu lists the system voices for the book’s language, best quality first. These include every voice installed in System Settings → Accessibility → Spoken Content, the Enhanced and Premium downloads, and voices added by third-party speech synthesis extensions. System voices report each word as it is spoken, so the word highlight is exact.

Speed runs from 0.75× to 4×. System voices top out at about 3×.

Google voices

Google’s on-device voices from Android and ChromeOS, 51 of them in six languages, can be added as a plugin. They include sfg, Android’s default US English voice, which stays clear at high speeds. They need a Mac with Apple silicon and Homebrew.

Earmark offers to install them the first time it opens, and Help → Install Google Voices does it any time. To run the installer from a terminal instead:

The installer uses Homebrew to add google-tts-local, which runs Google’s speech engine natively on the Mac. It downloads the engine and voices from Google (about 110 MB), starts its voice service at login, and adds a Google entry to the voice menu, filtered to the book’s language. Run it again to update google-tts-local.

To remove it, run gtts-service uninstall and brew uninstall google-tts-local, then choose Edit Plugins… and delete the Google entry.

No. 03

Plugins

Any other speech engine, through one small file.

Other text-to-speech engines can be added as plugins in ~/Library/Application Support/Earmark/engines.json. Choose Edit Plugins… at the bottom of the voice menu to open the file, and File → Reload Settings (⌘R) after editing it.

A plugin is either an HTTP endpoint or a command, and it returns a WAV file for one sentence at a time. Earmark fetches the next sentence while the current one plays, so there are no gaps.

{
  "engines": [
    {
      "name": "My server",
      "url": "http://127.0.0.1:8000/speak",
      "voices": "http://127.0.0.1:8000/voices",
      "speed": "engine"
    },
    {
      "name": "Piper",
      "command": [
        "/opt/homebrew/bin/piper", "--model", "/path/to/voice.onnx",
        "--output_file", "{out}"
      ],
      "speed": "player"
    }
  ]
}

The fields

name

The name shown in the voice menu.

url

Earmark POSTs JSON: your body plus text and rate. The reply is the WAV file.

voices

Optional. A URL returning [{"id", "name", "language", "gender"}]. Each voice gets its own menu entry, and the chosen id is sent as voice.

command

The sentence arrives on stdin. {out} is the WAV path to write, and {text}, {rate} and {voice} are also replaced.

body

Optional extra fields to send with every request.

speed

engine passes the speed to the plugin as rate. player speeds up playback instead, up to 2×.

start

Optional. A command that starts the plugin’s server, such as ["/opt/homebrew/bin/gtts-service", "install"]. Earmark runs it once if the server can’t be reached, then tries again.

enabled

false hides the plugin.

If a plugin still can’t be reached, Earmark carries on with the best system voice for the book and says so on the status line. Choose a voice or press ⌘R to try the plugin again.

Word timing

Plugins return audio only, so Earmark times the words from the audio itself. It finds the pauses the voice makes, matches them to the sentence’s punctuation, and spreads the words between two pauses by syllable count.