---
title: Scriptorium
emoji: 🏆
colorFrom: pink
colorTo: blue
sdk: gradio
sdk_version: 6.18.0
python_version: '3.12'
app_file: app.py
pinned: false
short_description: Convert your books to the spoken word
tags:
- track:backyard-ai
- sponsor:openai
- sponsor:nvidia
- sponsor:modal
- badge:off-brand
---

# Scriptorium

Scriptorium is a Gradio-based app for turning EPUB books into audiobooks. It provides a custom front-end for uploading and configuring a book, previewing voices, running long-form synthesis, and exporting the finished audiobook once generation completes.

## Demo video

<video controls width="100%" src="https://huggingface.co/spaces/build-small-hackathon/Scriptorium/resolve/main/Video.mp4">
  Your browser does not support the video tag.
</video>

[Open video directly](https://huggingface.co/spaces/build-small-hackathon/Scriptorium/resolve/main/Video.mp4)

## Social media post
https://bsky.app/profile/unlimiteddreamco.xyz/post/3moe744qpos2m

## What it does

- Parses EPUB uploads into chapter text and metadata.
- Lets users select which chapters to include.
- Supports preview generation before committing to a full render.
- Runs full-book synthesis with progress updates and an export flow after completion.
- Exports finished renders from session-scoped storage.

## Project structure

- `app.py`
  - Main Gradio server entrypoint and API registration.
- `frontend/`
  - Custom HTML/CSS/JS interface for the three-step app flow.
- `backend/epub.py`
  - EPUB validation, parsing, metadata extraction, and chapter shaping.
- `backend/synthesis_service.py`
  - Main orchestration layer that routes preview/render work to local or Modal-backed synthesis.
- `backend/modal_client.py`
  - Client for the optional remote Modal synthesis service.
- `modal_app.py`
  - Modal FastAPI worker app for remote preview and render jobs.
- `backend/export.py`
  - Audiobook packaging and export helpers.
- `tests/`
  - Backend and integration-oriented test coverage for parsing, synthesis routing, Modal client behavior, and API wiring.

## Models and synthesis backends

Scriptorium currently supports these speech models:

- `OmniVoice`
  - Main model for presets, design-prompt voices, and voice cloning.
- `Magpie TTS`
  - Multilingual synthesis with speaker presets and optional text normalization.

It can run them through two execution backends:

- `HF/local`
  - Runs synthesis inside the Hugging Face Space runtime.
- `Modal`
  - Offloads synthesis to a separately deployed Modal worker.

The in-app voice presets such as `The Archivist`, `The Novice`, `The Warden`, and `The Illuminator` are themed preset layers on top of the underlying synthesis configuration.

## Modal backend configuration

Set these as Hugging Face Space secrets if you want to use the optional Modal backend:

- `SCRIPTORIUM_MODAL_BASE_URL`
- `SCRIPTORIUM_MODAL_AUTH_TOKEN`

`SCRIPTORIUM_MODAL_BASE_URL` must be the deployed `modal.run` web endpoint, not the Modal dashboard URL under `modal.com/apps/...`.