Getting Started

This guide helps you choose between installing a ready-made release and building OperaLibre from source. Once it is running, everyday use happens in the app.

Choose the right starting point

  • You have audiobook files on this computer: download the combined release package below.
  • You want to listen from a phone: finish the local setup first, then see Use it on a phone or tablet.
  • Your files are already on your phone or tablet: use Listen from this device in the native app; no server is needed. See Listen from this device.
  • You want to try it first: choose Explore the on-device demo on the connection screen for bundled audio, an EPUB, and sentence timings that work offline.

Download the combined package for your computer. It includes a background launcher and a ready-to-use configuration; no developer tools are required and no Terminal window stays open.

Follow Install a Release for exact Windows, macOS, and Linux instructions, adding books, phone access, backups, and updates.

Build from source

Use the following steps if you want to develop OperaLibre or build it yourself instead of downloading a release.

Prerequisites

Tool Version Used for
Rust 1.89 or newer (edition 2024) Building and running the server
Node.js 22.12 or newer Building and serving apps/web
npm bundled with Node Workspace + dev scripts
A folder of audiobooks — The library the server will scan

The server and the launcher both need Rust 1.89 or newer. Install the current stable toolchain from rustup.

Tip: If cargo --version and node --version both work, you have everything you need. On a Mac, install Apple’s Command Line Tools too by running xcode-select --install once.

1. Clone and install

git clone https://github.com/DonovanMontoya/OperaLibre.git
cd OperaLibre
npm ci

npm ci installs the web workspace from the checked-in lockfile. The Rust server compiles on first run. Leave VITE_API_BASE unset so development requests use the Vite proxy and native apps can choose their server at runtime.

2. Create your config

cp server.config.example server.config

On Windows PowerShell, use this instead:

Copy-Item server.config.example server.config

Open server.config in a text editor and replace /path/to/audiobooks with the full path to the folder that contains your books. Keep the rest as-is for now. On Windows, use a full path such as C:\Users\you\Audiobooks.

deployment_mode = local
host =
port = 4920
max_upload_gib = 20
max_book_download_gib = 25
max_concurrent_book_downloads = 1
download_temp_dir = data/download-temp
min_download_free_gib = 2
library_root = /path/to/audiobooks

3. Start OperaLibre

npm run dev

This starts the server and the web app together. Leave this Terminal window open while you listen. You should see two color-coded prefixes (server cyan, web magenta).

The Vite web app forwards its requests to the server automatically, so use the Web UI address above—not the API address—in your browser.

4. Create the admin account

Open the app for the one-time setup form. local and lan setup need no extra credential. Every setup in proxy mode asks for the 30-minute, single-use token printed in the server console. Create the initial owner account; subsequent visits show the normal sign-in form. See Users & Accounts for details.

5. Start listening

Pick a book and press play. Progress saves automatically and follows the signed-in reader across devices. See Using OperaLibre for uploading a book, adding family members, installing the web app, readalong, and the optional integrations.

Running on the LAN

To stream to a phone or tablet:

  1. Set deployment_mode = lan and leave host blank in server.config so the server selects 0.0.0.0 automatically.
  2. Find your machine’s LAN IP (ipconfig getifaddr en0 on macOS, ip addr on Linux, ipconfig on Windows).
  3. Allow port 4920 (or whatever you set) through your firewall.
  4. On the other device, open http://<your-lan-ip>:5173 in dev, sign in, and start listening. For a setup that keeps working after you close the development Terminal, use the production setup below.

Safety: LAN mode uses plain HTTP and deliberately allows a non-Secure session cookie. It is suitable only for a trusted home network or private VPN. Do not port-forward it to the public internet; use proxy mode and the HTTPS guidance in Deployment for access away from home.

npm run build

This produces:

  • A release Rust binary at apps/server/target/release/operalibre-server
  • A static web bundle at apps/web/dist/

Then add this line to server.config:

web_dist_dir = apps/web/dist

Start the server with:

./apps/server/target/release/operalibre-server

Now open http://localhost:4920. The server and web app share one address, which is simpler to bookmark and use on another device. To make it start automatically when the computer restarts, follow the macOS or Linux instructions in Deployment.

A server you compile yourself reports the version in apps/server/Cargo.toml under Administration → Overview → OperaLibre software, unless OPERALIBRE_VERSION was set for that compile. It names the latest stable release, so a build from unreleased source reports that release. Published release builds set OPERALIBRE_VERSION to the release tag, so nightlies report their full nightly version. A web bundle built without OPERALIBRE_VERSION is marked Development.

Type-checking everything

npm run typecheck

Runs cargo check and the web app’s TypeScript compiler. Useful before committing.