stories

A modern GTK4 / libadwaita desktop client for Audiobookshelf, the self-hosted audiobook & podcast server.

Status: early development. See MILESTONES below.

Features (planned for v1)

• Log in to an Audiobookshelf server (URL + username/password), token kept in the system keyring
• Browse libraries and items, search, view book details & chapters
• Stream playback with GStreamer — multi-file audiobooks, chapter navigation, playback speed
• Server-side progress sync (resume where you left off, across devices)
• Offline downloads with resumable transfers and local playback
• Offline progress queue that flushes when you reconnect

Tech stack

Python 3 · PyGObject (GTK 4) · libadwaita · GStreamer · SQLite · libsecret. Built with Meson, UI written in Blueprint. Packaged as a Flatpak.

Development (NixOS)

This repo ships a flake.nix dev shell with the full toolchain.

nix develop          # enter a shell with GTK4, libadwaita, GStreamer, blueprint-compiler, meson…
./run.py             # compile resources in-tree and launch straight from src/

./run.py compiles the Blueprints, the GResource bundle, and the GSettings schema into _dev/, then runs the app without needing a full meson install.

Meson build (packaging path)

nix develop
meson setup builddir --prefix="$PWD/install-dev"
meson install -C builddir
./install-dev/bin/stories

Flatpak

flatpak-builder --user --install --force-clean build-flatpak \
    build-aux/flatpak/dev.cremin.Stories.json
flatpak run dev.cremin.Stories

Milestones

• M0 — scaffolding, dev shell, empty window ← current
• M1 — login + token persistence
• M2 — browse libraries & items
• M3 — streaming playback
• M4 — online progress sync
• M5 — offline downloads
• M6 — offline progress + polish

License

GPL-3.0-or-later.