read-aloud: approved audio versions of WordPress posts

A WordPress plugin that turns a post into an audio file once, through any text-to-speech API, and shows a player after an editor approves it. It resynthesises only when the spoken words change. Written from scratch, v0.1.0.

read-aloud is a WordPress plugin that turns a post into an audio file once, through any text-to-speech API behind a small adapter. Readers see an accessible player only after an editor has listened and approved the file. It synthesises again only when the words that are spoken change. Licence MIT. Version v0.1.0, released 19 November 2026.

It was written from scratch from an idea, as one of the utilities described on the engineering blog. It has not run on a live site, and the PRD says there is no production measurement for it.

The problem

Many readers would rather listen to an article than read it. A site that wants to offer that has three poor options.

  • The browser’s built-in speech engine. The voice depends on the reader’s device, differs between browsers, and cannot be checked by an editor before a reader hears it.
  • Recording each article by hand, which does not scale past a few pieces a week.
  • A hosted text-to-speech API. The voices are good, but every call costs money. A naive integration calls the API on every save, on every settings change, or for the whole archive at once. It may also call the API during a page view, which turns a traffic spike into a spending spike.

The failure that matters most is silent spending: the same article is synthesised again and again because something that is not the spoken text changed, such as a tag, a featured image, a relative date or a related-posts box. The second failure is silent wrongness: an article is corrected, but the audio still reads out the old sentence.

What it does

  • Extracts the spoken text from the stored post content, normalises it and hashes it on every save, with no network call.
  • Synthesises only when that hash changes, after a debounce, in chunks, with a chunk cache so correcting one paragraph costs one chunk.
  • Holds each file for review. An editor previews it in the post editor and approves or rejects it.
  • Shows a native audio player with preload="none" and a disclosure line after approval.
  • Marks an approved file as outdated when settings change, instead of regenerating the archive.

How it works

Hooks on wp_after_insert_post, set_object_terms, trash and untrash call Plugin::defer(). At shutdown each post is triggered once with the strongest reason seen in the request. Planner::plan() returns eligibility, the spoken text and its hash. Unchanged text increments a “saves without resynthesis” counter. Changed text queues a job, on WP-Cron or on a job queue plugin through gen_queue_enqueue_job.

The job reads the kill switch fresh, re-checks eligibility, splits the text at paragraph and sentence ends, and reserves the characters it will send against the daily cap in one atomic database statement through the Ledger. Every response is checked for status, content type, size and magic bytes, so a 200 response holding HTML is a failure, not a file. Chunks are joined and written to a temporary name, then renamed into uploads/read-aloud/. Audio URLs are immutable: a new version always has a new file name. After approval the old file is deleted 48 hours later, because cached pages may still point to it.

A hosted API is configured with a JSON body template, parsed once and filled at the value level, so quotes and backslashes in an article cannot break the request:

{"input": "{text}", "voice": "{voice}", "model": "{model}", "response_format": "{format}", "speed": "{speed}"}

An adapter implements IndianOpinion\ReadAloud\Provider\SpeechProvider. A silent provider makes no network call and costs nothing, for a first try.

Guard rails

  • Nothing reaches readers until a person approves it. There is no automatic approval.
  • A page view never calls the API. Rendering reads post meta only, and the player tracks no listeners.
  • Generation is enabled by default, but nothing is eligible on a fresh install. READ_ALOUD_DISABLED wins over the setting.
  • The daily character cap defaults to 50,000 and the daily generation cap to 20. Work that hits a cap moves to 00:05 the next day. An optional money cap works only if you enter a price, and none is seeded.
  • The first 401 or 403 from the provider holds the whole site until you save the settings, clear the hold or a test call succeeds.
  • Posts that are too short or too long are skipped, never truncated. Unpublished text is never sent.
  • The http adapter never follows redirects, refuses an endpoint if any of its addresses is private, loopback, link-local or otherwise reserved, and pins the connection to the address it checked.
  • The disclosure line cannot be blanked on the settings screen.

What review changed

An independent review of the build PR fixed these before the merge.

  • The http adapter’s address check was widened to every A and AAAA address, including link-local and cloud metadata, carrier-grade NAT, IPv6 unique-local and mapped IPv4. The connection is pinned, there are no redirects and the response is limited to 64 MiB.
  • Jobs now re-read the post before every chunk and stop if it is no longer eligible. Before, unpublished text could still reach the provider mid-run.
  • A cached chunk that vanished after the reservation is never sent unreserved, and settle and the stale sweep can no longer both release one share of the cap.
  • Pending file names are now keyed with a per-site secret, so the URL of audio awaiting approval cannot be derived from public text. Tampered deny files are rewritten, and the chunk cache is turned off if they cannot be.

The review also aligned the spend-meter and gen-queue integrations with the released contracts and fixed mp3 duration, which is now summed per frame.

Limits and what is next

  • One provider per site. The plugin joins mp3 and wav chunks itself. Other formats work only when the adapter says so.
  • Shortcodes are removed, not rendered. Dynamic blocks are read from their saved inner content.
  • Only two adapters ship, a generic HTTPS one and the silent one. There are no named presets.
  • One issue is open, filed on 19 November 2026. In the cap ledger, the day-row update and the reservation claim are separate statements. A crash between them leaves a reservation the stale sweep never releases, so the day’s counters stay charged. The proposed fix is a transaction or a sweep that reconciles day rows against live reservations, with a test for a failure between the two.

Test status: this is v0.1.0. 131 PHPUnit tests with 1,052 assertions pass, including the ledger tests against a throwaway MySQL 8.0, with PHPStan level 8 and phpcs clean. WordPress and provider calls are tested against stubs and mocks. CI has not yet run on GitHub, and it has no production mileage.

Install

It needs PHP 8.1 or later, WordPress 6.4 or later, outbound HTTPS and a writable uploads directory. The intl extension is recommended.

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/read-aloud.

composer require indianopinion/read-aloud

All 47 utilities · read-aloud on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.