Audio versions

Audio versions are coming to FlockStack Cloud, and they are off until then. They need a new sub-processor, a text-to-speech service named on the sub-processors page, and the terms promise 30 days' notice by email before one starts handling data. Until it starts, the dashboard shows nothing of this and the API refuses it. A self-hosted server turns them on by giving the server its own voice service account and a list of voices (see the README).

Open an issue, a draft or one already sent, and use the Audio version card (in the Review step of a draft, and in the report of a sent issue). Pick a voice, listen to its sample, and the card tells you what the audio will use of the month's characters before anything is read. Creating it starts a background job: you can leave the page, and the card follows it. When it is ready you hear it in the card, and the audio.ready webhook fires. Change the issue and create it again, and the new audio replaces the old one; if the issue didn't change since, nothing is read again and nothing is counted.

A job that fails keeps what was read: it stops with a message that says which part failed, counts only the characters actually read, and creating it again goes on from the parts it kept. An issue can be up to 50,000 characters, read in parts of 2,500 characters at most, cut between sentences.

• The issue's title first, then the text in order. Headings and list items are read as sentences, and a link is read as its words.
• A web address in the text is read as the site it goes to, like example.com. Footnotes are read at the end, under Notes.
• Pictures are left out. Tables, code, embeds, polls and file downloads are left out too, and then the audio ends with a line that says some parts are only in the web version.
• An issue for everyone with a paywall break is read up to the break, with a line saying the rest is for paid subscribers: the audio is public, and the paid part never is. An issue for paid subscribers only is read whole and played to paid readers only.

Audio is counted by the character read, for the account, per calendar month in UTC. A plan has a number of characters a month; an audio version that would go past what is left is refused before it starts, with how many are left. There is no overage and nothing to buy on top. The Free plan has no audio. About 825 characters is a minute of speech, so the numbers below are the minutes in brackets.

get_audio_usage says what the month has used and left, and, given an issue, what its audio would use.

On the issue's web page the player sits above the text: play and pause, 15 seconds back and forward, speeds of 1x, 1.25x, 1.5x and 2x, and a slider. It remembers where you stopped in the reader's own browser (local storage) and tells nobody: nothing about listening is counted or sent. Tick Listen to this issue in the card and each email of the issue opens with a link to it, with the length: for example Listen to this issue (12 min). An issue for paid subscribers only has no public page, so it has no such link: paid readers play it on the page after signing in.

Turn the podcast on in the Audio page and the newsletter's website serves an RSS 2.0 feed with the iTunes tags at /podcast.xml, with each issue that has audio as an episode, the newsletter's logo as cover art and the files streamed with byte ranges, which podcast apps and iOS need. An issue for paid subscribers only is never in it. The Audio page shows the feed address and how to give it to Apple Podcasts and Spotify. Apple wants cover art of at least 1400 by 1400 pixels and at least one episode.

list_audio_voices, get_audio_usage, create_audio_version, get_audio_version, update_audio_version, delete_audio_version, get_audio_settings and update_audio_settings work from the REST API and MCP. An issue's ID is its audio version's ID. A voice is read in parts of 2,500 characters, with the voice service's eleven_multilingual_v2 model unless the server sets another.