Installation - on22s/Side-Story GitHub Wiki

English · 简体中文 · 日本語

Installation

Use Pinokio for the usual desktop setup. The basic install includes the audiobook app and local Qwen3-TTS runtime. You can complete Setup → Script → Voices → Editor → Result without the native Voice Tools add-on.

Return to Home · Next: LLM Setup and First Audiobook

Before you install

  • Plan for model downloads and working space. TTS model variants are downloaded when first used. Allow several GB per variant, plus the Python/PyTorch environment, any separate LLM weights, source books, reference audio, and rendered audio. A large project can use substantially more disk space than its final MP3.
  • Choose where annotation runs. Automatic script annotation needs a reachable OpenAI-compatible LLM server. This is separate from TTS. An external LLM server, a hosted API, or manual copy/paste can be used; installing the app does not download an LLM.
  • Start with a short passage. Local GPU acceleration is recommended for practical audio generation, but memory requirements depend on the model, voice path, batch size, and other workloads. There is no universal safe batch size or guaranteed render speed.
  • Use material you have permission to process. Remote annotation sends book text and task context to the chosen provider. External TTS can send voice-reference audio and transcripts to the chosen server. See LLM Setup and Voices.

Pinokio: recommended

  1. Install Pinokio.
  2. Choose Download and paste https://github.com/on22s/Side-Story.
  3. Open the downloaded app and click Install. Let the installer finish; do not start another installer against the same checkout while it is working.
  4. Click Start, then Open Web UI when the launcher shows it. Use the URL the launcher provides; Pinokio chooses an available port.
  5. Configure Setup, save it with Save Configuration, and make a short test using First Audiobook.

A fresh install creates app/env with CPython 3.10. It installs the platform-specific PyTorch stack first, records constraints for that stack, then installs the application requirements and qwen-tts==0.1.1. An existing environment is retained rather than recreated automatically.

If the launcher remains at Starting, open its terminal and read the first error. Do not use Reset as a routine installation fix: it removes active work and configuration. See Troubleshooting and Updates and Backups.

Hardware: installer paths, not a compatibility guarantee

The following describes the shipped install and device-selection code. It does not establish that every GPU, driver, operating-system release, or model path works end to end.

Platform Shipped path Important limitation
NVIDIA on Windows/Linux PyTorch 2.7.0 with CUDA 12.8 packages Requires a compatible GPU and driver. Optional attention wheels also depend on the exact Python/platform combination.
AMD on Linux PyTorch 2.10.0 with ROCm 7.0; triton-rocm 3.6.0 The installer identifies RX 9070 XT / RDNA4 as its tested target. This is not a claim for all AMD cards or APUs. Verify the host driver/ROCm and GPU combination.
AMD on Windows Installer includes DirectML packages, but the app's device resolver uses CUDA/ROCm, MPS, or CPU Do not expect AMD GPU acceleration from this install path; use CPU or another supported execution setup.
Apple Silicon macOS PyTorch 2.7.0; runtime chooses MPS when available Availability reported by PyTorch does not guarantee every operation or acceptable performance. Validate a short sample.
Intel macOS Older PyTorch 2.2.2 pin; CPU fallback Validate the environment and a short sample before committing to a book.
Other CPU-only systems CPU fallback Generation may be impractical for long books; measure a short passage first.

Start with Device: auto. The runtime prefers CUDA/ROCm, then MPS, then CPU. PyTorch uses the cuda device namespace for ROCm as well, so a CUDA-style device name alone does not mean an AMD machine has the wrong backend.

No application, GPU, model-download, or audio-generation run was performed to validate this wiki. Hardware descriptions above are source-based, with the installer's own stated test scope kept separate.

Docker: supplied NVIDIA configuration

The provided Compose file targets NVIDIA GPUs. It requires Docker and the NVIDIA Container Toolkit. It is not an AMD deployment recipe.

From a terminal:

git clone https://github.com/on22s/Side-Story.git
cd Side-Story
docker compose up --build

Open http://localhost:4200 on the Docker host. The supplied image uses the PyTorch 2.8.0/CUDA 12.8 runtime base, rather than the Pinokio PyTorch pin. It installs the core audiobook runtime; it does not build the optional native Voice Tools or create preparer_env.

Keep Docker data persistent

The supplied mounts preserve:

  • data/runtime: active state, reports, exports, and other runtime artifacts
  • data/uploads, data/scripts, data/designed_voices, data/clone_voices, data/lora_models, data/lora_datasets, and data/dataset_builder: their respective libraries and inputs
  • data/output: generated voicelines
  • data/config: application configuration
  • The named hf_cache Docker volume: downloaded Hugging Face models

Keep these mounts if you customize Compose. If you use docker run, persist both /alexandria/runtime and /alexandria/config yourself. A container rebuild is not a backup. See Updates and Backups before upgrading.

Inside a container, localhost is the container. If your LLM runs on the host or another machine, use an address reachable from the container; the host's loopback URL will not automatically reach it.

Keep network access private

The default Compose mapping is 127.0.0.1:4200:4200. The app binds 0.0.0.0 inside the container so Docker can forward traffic, but the published host port remains loopback-only.

Authentication is off by default. Before publishing the port on another interface, creating a tunnel, or adding a reverse proxy:

  1. Set ALEXANDRIA_AUTH_PASSWORD in the app/container environment. The default Basic Auth username is alexandria; override it with ALEXANDRIA_AUTH_USERNAME if needed.
  2. Use HTTPS when accessing beyond a trusted local network.
  3. For a domain, set ALEXANDRIA_ALLOWED_HOSTS to the intended hostname. If a separate browser origin needs API access, configure that exact origin with ALEXANDRIA_ALLOWED_ORIGINS; browser CORS response permissions may also require CORS_ORIGINS.
  4. Keep passwords out of the image, repository, shared Compose files, and diagnostic posts.

Host/origin checks are useful protections, but they are not authentication or transport encryption.

Other starting points

  • The repository includes a Colab notebook. Follow its own setup and persistence steps; GPU availability and session limits depend on Colab.
  • For an already installed local environment, running python app.py from app/ uses port 4200 by default unless ALEXANDRIA_PORT is set. Use the app environment's interpreter, not an unrelated system Python.
  • Install Optional Voice Tools only when you need native Preparer/Voice Lab stages or the bundled Start LLM launchers.

Sources

Verified against shipped main at 8c7a33cb310ab9264594a09ca27e48271585094f: README, core installer, PyTorch installer, device resolver, Dockerfile, Compose, app security configuration.