Returns the static list of voices that can be passed as the voice parameter on the other audio endpoints. The default voice everywhere is alloy.

Returns the static list of line fields audio can be generated for. These map to the Arabic, English and commentary text of a book line.

Creates an AudioJob with status "pending" and responds immediately with its id. Generation then runs in the background inside the API process: the job moves to "in_progress", and for every line of the book and every field (arabic, english, commentary) audio is fetched from the S3 cache or generated with OpenAI TTS and uploaded. progress (0-100) is saved after each line/field, and the job ends as "completed", or "failed" with an error message if the job itself crashes. Failures for an individual line/field (for example an empty field) are only logged, still count towards progress, and do not fail the job. The voice is not validated here. Poll GET /audio/jobs/:jobId to follow the job.

Returns the raw AudioJob document so a client can poll status and progress. status is one of pending, in_progress, completed or failed; progress is a percentage from 0 to 100; error is only present on failed jobs. Any editor or admin can read any job.

Lists all audio objects stored in S3 for the book, keeps those matching the requested voice (case-insensitive), and returns every line of the book with, per field (arabic, english, commentary), the field text, whether audio exists, and a presigned S3 URL valid for 1 hour (null when there is no audio). This endpoint never generates audio. Read access to the book is enforced exactly like GET /books/:bookId: audio of public books is readable by anyone, while a bearer token is needed to read audio of private books (owner, contributors and admins only — everyone else gets a 404) and of subscriber-only books (accessModel "creator_subscription": callers who cannot manage the book need an active subscription to its creator at the required tier, otherwise a 402 is returned). An invalid token is silently treated as anonymous.

Returns every AudioJob, newest first, with bookId populated with the book title, author, category, progress and difficulty. Jobs are not filtered by user: any editor or admin sees all jobs. There is no pagination.

For each requested field, returns the cached MP3 from S3 if one exists for the current line content and voice, otherwise generates it synchronously with OpenAI TTS, uploads it to S3 and removes stale audio for that field. Each result contains the S3 key, a presigned URL valid for 1 hour, and whether it came from the cache. A failure for a single field (for example the field has no text, or the voice is rejected by the TTS provider) does not fail the request: it is reported under errors keyed by field name, and errors is omitted when every field succeeded. Field names are validated against arabic, english and commentary; the voice is not validated up front. Because generation costs money, only editors and admins may call this endpoint; only the role is checked, there is no book ownership check.

Returns the cached MP3 for this line field and voice if one exists for the current line content, otherwise generates it synchronously with OpenAI TTS (long text is split into chunks of up to 4000 characters and concatenated), uploads it to S3 and deletes stale audio for that field. The response carries the S3 key and a presigned URL valid for 1 hour; request GET .../url again for a fresh URL once it expires. Both field and voice are validated. An empty field results in a 500. Because generation costs money, only editors and admins may call this endpoint; only the role is checked, there is no book ownership check.

Looks up the MP3 for the line field and voice in the S3 cache and pipes the S3 object through the API as the response body. For anonymous callers and members this endpoint only serves audio that has ALREADY been generated for the line's current content and voice; if there is none (never generated, or the line was edited since) it answers 404 and nothing is generated. Only when the bearer token belongs to an editor or admin is missing audio generated and uploaded on demand. field must be arabic, english or commentary and voice must be one of the ids from GET /audio/voices, otherwise a 400 is returned. The response is sent with Content-Type: audio/mpeg, Accept-Ranges: bytes and Cache-Control: max-age=31536000. Although Accept-Ranges is advertised, the handler always sends the complete file with status 200 and does not honour Range headers. Book read access is NOT checked on this route, because media players (an audio element src) cannot send an Authorization header; use GET .../url when access control matters. An invalid token is silently treated as anonymous.

Looks up the MP3 for the line field and voice in the S3 cache and returns a fresh S3 presigned GET URL with a caller-chosen lifetime. The URL points directly at S3 (served as audio/mpeg with inline disposition) and stops working after expiresIn seconds. As with the stream endpoint, anonymous callers and members only get audio that has ALREADY been generated for the line's current content and voice (cached is then always true) and receive a 404 otherwise; only editors and admins trigger generation on demand. field must be arabic, english or commentary and voice must be one of the ids from GET /audio/voices, otherwise a 400 is returned. Read access to the book is enforced exactly like GET /books/:bookId: audio of public books is readable by anyone, while a bearer token is needed to read audio of private books (owner, contributors and admins only — everyone else gets a 404) and of subscriber-only books (accessModel "creator_subscription": callers who cannot manage the book need an active subscription to its creator at the required tier, otherwise a 402 is returned). An invalid token is silently treated as anonymous.

Lists every audio object stored in S3 for the line, across all fields and voices, each with a presigned URL valid for 1 hour, together with the text content of the line. This endpoint never generates audio. Read access to the book is enforced exactly like GET /books/:bookId: audio of public books is readable by anyone, while a bearer token is needed to read audio of private books (owner, contributors and admins only — everyone else gets a 404) and of subscriber-only books (accessModel "creator_subscription": callers who cannot manage the book need an active subscription to its creator at the required tier, otherwise a 402 is returned). An invalid token is silently treated as anonymous.

With a voice query parameter, deletes the single S3 object for that voice and the current line content (deletedFiles is always reported as 1, whether or not the object existed). Without voice, deletes every stored audio file for the field, across all voices (deletedFiles is the string "all"). Only the role is checked: there is no book ownership check, so any editor or admin can delete audio of any book. The field value is not validated.

Deletes every audio object stored in S3 for the line, across all fields and voices, and returns how many files were removed. Only the role is checked; there is no book ownership check.

Deletes every audio object stored in S3 under the book, for all lines, fields and voices, and returns how many files were removed. The book itself is not modified. Only the role is checked; there is no book ownership check.

Lists every audio object stored in S3 for the book, optionally filtered by field and voice, and groups them by line and field. Only lines that have at least one matching audio file are returned, in book order, each with its text content and, per field, an array of audio files with presigned URLs valid for 2 hours. totalFiles is the number of matching files. This endpoint never generates audio. Read access to the book is enforced exactly like GET /books/:bookId: audio of public books is readable by anyone, while a bearer token is needed to read audio of private books (owner, contributors and admins only — everyone else gets a 404) and of subscriber-only books (accessModel "creator_subscription": callers who cannot manage the book need an active subscription to its creator at the required tier, otherwise a 402 is returned). An invalid token is silently treated as anonymous.