ai1y Docs

For developers

Building on ai1y

The open format underneath every ai1y book, for anyone writing a reader, an app or a converter for it.

The format

An ai1y book is a folder of plain files, not an EPUB, so it may not open in your favorite e-book app today. It supports EPUB: it is made from one, points back into it, and carries the same timing data as EPUB 3 Media Overlays, so a book built from an EPUB could be turned back into a read-aloud EPUB.

The format is open and documented, so you’re never locked in: anyone can write a reader for it, put it in an app, or convert it to something else. EPUB is the way in today, and support for more formats is planned.

An ai1y book, as files

  • manifest.jsontitle, reading order, contents, page map, and every file’s hash
  • content/part-001.jsonthe text, sentence by sentence, with pointers into the source
  • annotations/part-001.jsonSSML-style spans: how to say a date, where to pause
  • lexicon.plspronunciations for the whole book
  • renditions/r1/rendition.jsonwhich engine, model and voice made the narration
  • renditions/r1/part-001.jsonwhen every word starts and ends
  • renditions/r1/audio/part-001.m4athe narration
  • images/<sha256>.jpgthe book’s pictures
  • Parts. A book is split into parts, usually chapters, so a reader fetches only the part on screen and its neighbors.
  • Hashes. Every file is listed in the manifest with its SHA-256, so a device can check it, cache it forever and share it between books.
  • Renditions. A book can have more than one narration, each naming the exact model revision that made it. ai1y writes AAC audio (.m4a) or WAV; the format allows other audio types.
  • Overlay books. An overlay carries no text, audio or pictures, only hashes, pointers and timings. Someone with their own copy of the book lines it up and narrates it locally, so the book never changes hands.
  • Serving books. The reader shows a part’s text before its audio arrives and downloads audio one part at a time, the open part first and then the next. ai1y sends the text files (JSON, the lexicon) gzip-compressed to browsers that ask for it, and audio as it is; on your own web host, turn on compression for text files to do the same.
  • Pointers back use EPUB CFI, a PDF page and box, or an HTML path, with a text-quote selector as a fallback.

The draft is read-along 0.1, with JSON Schemas and test vectors beside it, and it will be published openly. It defines four levels a reader can support: read-aloud (a clip per sentence), word sync, phoneme sync, and interactive. Changes go through numbered proposals, such as the one that gives a book’s manifest its description and cover, so a catalog’s feed can offer each title both. Feedback on the format is welcome at support@ai1y.co.

The reader checks every book against the spec as it opens it, in the browser, with ai1y’s Rust core compiled to WebAssembly.

Programs and agents

To make and change books from your own programs or an AI agent, see the API docs: how to call the API, make changes, run jobs after a quote, and let an agent work on a project. Every operation is in the reference.