earmark publish
earmark publish [SOURCE] [voice options] [audio options] [behaviour options]
[metadata options] [cleaning options]Runs the whole chain. Extracts, cleans, dictates, writes audio/<name>.mp3, adds the episode to feed.xml, normalizes the cover, and runs the after_publish hook from inside the library.
earmark publish paper.pdf is all you ever need to type. Working from a bare source is the least guessable thing about the design, and the reason the other two commands are optional.
Arguments
| Argument | Means |
|---|---|
SOURCE |
a file path, a Markdown file, an MP3, or a URL. Omit it to sync sources.yml. |
An existing .mp3, .m4a or .wav is adopted onto the feed with no synthesis at all, which is how a recording made elsewhere ends up in the same feed as the things earmark dictated.
With no SOURCE: make the feed match sources.yml
earmark publish on its own reads the library’s sources.yml and makes the feed agree with it:
- An entry with no episode yet is published, exactly as if it had been named on the command line, with the entry’s own
title,voiceand so on overriding the config. - An episode whose entry has been deleted from the list is removed, with its MP3 and its
text/Markdown, the same asearmark feed --remove. - An episode you published by hand, with a SOURCE, is never touched. Only episodes that came from the list can leave because of it.
An entry is matched by its source string exactly as written. Changing an entry’s voice therefore does not dictate it again; delete the entry, sync, and add it back.
One entry failing, such as a dead link, does not stop the others. It is reported, the rest are published, and the command exits 1. A list that does not parse, or that names a file that is not there, stops the sync before anything is removed.
--dry-run prints what would be added and removed and changes nothing. The other flags apply to every new entry, below anything the entry sets itself.
This is how a library in a GitHub repo publishes itself. See Use it on GitHub.
Options
Every flag of earmark audio, unchanged:
- voice:
-v/--voice,-s/--speed,--lang,--model,--engine - audio:
--bitrate,--sample-rate,--no-title-card - behaviour:
--dry-run,--play,-q/--quiet,--no-cache,--refresh - metadata:
--title,--author,--date - cleaning:
--profile,--tables,--keep-references,--keep-citations,--keep-links,--say-code,--drop-sections,--skip-front-matter,--keep-front-matter --library PATH
What it needs from the config
feed.base_url: the public URL your library folder is served at. Without it publishing stops with a message telling you to run earmark config.
If your library is not already a folder on the web, set after_publish to one line of shell. See Host a library.
Re-publishing
Publishing a document you have already published replaces its episode rather than duplicating it. The audio filename follows the slug, and the feed’s guid is a content digest, so an edited document takes the place of its earlier self.
Examples
earmark publish paper.pdf
earmark publish https://example.com/some-long-article
earmark publish text/some-paper.md # after editing the Markdown
earmark publish interview.mp3 # adopt existing audio
earmark publish paper.pdf --profile paper --voice af_bella
earmark publish # sync sources.yml
earmark publish --dry-run # what a sync would do