Unoffical Storytel Player for Desktop — a cross-platform desktop application for playing Storytel audiobooks, built with TypeScript, React, Fastify, and Electron.

Discord - Join our discord server and chat with the maintainers.

See the CHANGELOG for the full list of changes across all releases.

✅ Modern Desktop Interface: Dark theme with Storytel Orange accents, rounded cards and filter pills, laid out for a 1280×800 desktop window

✅ Catalog Search: Search the whole Storytel catalog by title, author or narrator (Ctrl/Cmd+K). Filters, results and a live preview side by side; add to your library or start listening in one click. Results are scoped to your Storytel market and limited to audiobooks

✅ Background Playback: Audio keeps playing while you navigate; a persistent mini-player keeps play/pause, skip, speed, chapters and sleep timer within reach

✅ Native Desktop App: Cross-platform application with system tray integration and single instance lock

✅ Audiobook Library: Browse your Storytel bookshelf with cover art, progress tracking and status filters

✅ Audio Player: Chapters, bookmarks, playback speed, sleep timer, multiple audio tracks and automatic resume

✅ Session Management: Secure authentication with persistent storage via electron-store, automatic session refresh and transparent retry

✅ Internationalization: English, Italian, German, Spanish, French, Swedish and Finnish (i18next) with automatic language detection

✅ Cross-Platform: Available for Windows, macOS (x64/ARM64), and Linux (x64/ARM64/ARMv7)

✅ Action Logging: Internal logging of HTTP requests, responses, and user actions, exportable for debugging. Log rotation is applied automatically (max 10 MB per file, up to 5 archived files)

✅ Development Mode: Hot reload for both client and server during development

✅ Offline Listening: Download audiobooks for offline playback

The application is built with TypeScript and follows a modular architecture:

• Frontend: React 18 with TypeScript, Tailwind CSS, and Vite (port 3000 in dev mode)
• Backend: Fastify server with TypeScript and RESTful API (port 8080)
• Desktop: Electron 43 with TypeScript
  • Window Manager: Main window handling with development/production modes
  • Tray Manager: System tray integration
  • Server Manager: Embedded Fastify server management
  • IPC Manager: Inter-process communication between Electron and React
• Authentication: Session-based authentication with secure storage
• Audio Streaming: Direct integration with Storytel's streaming API
• Logging: In-memory and file-based (app.log in the config directory) logging of system events and HTTP traffic

• Node.js 22+ (see .nvmrc for the recommended version)
• npm 7+

To add our tap, run:

brew tap debba/storytel-player

Then install:

brew install --cask storytel-player

When you install storytel-player on macOS, you need to allow accessibility access (Privacy & Security) to the storytel-player app.

If you are upgrading and you already have storytel-player on the allowed list you will need to manually remove them before accessibility access can be granted to the new version.

macOS users who download directly from releases may need to run:

xattr -c "/Applications/Storytel Player.app"

after copying the app to the Applications directory.

yay -S storytel-player-bin

Storytel Player checks for updates automatically on startup. When a new version is available, a notification will appear, allowing you to download and install the update seamlessly.

You can also manually check for updates or download the latest version directly from the Releases page.

## Development

Start the development environment with hot reload:

```bash
npm run install-all
npm run dev

This will:

• Start the Fastify server on port 3001 (with tsx watch for auto-restart)
• Start the Vite development server on port 3000
• Both servers will reload automatically when files change

You can also run components separately:

# Start only the server (development mode)
npm run server:dev

# Start only the client
npm run client

# Start both (without hot reload)
npm start

To run the Electron app in development mode:

npm run electron:dev

Build all components for production:

npm run build

This command builds the React client with Vite (client/build/).

Create distributable Electron packages:

# Build and create installer/distributable for current platform
npm run electron:dist

# Platform-specific builds
npm run electron:dist:win           # Windows (x64)
npm run electron:dist:mac:x64       # macOS (Intel)
npm run electron:dist:mac:arm64     # macOS (Apple Silicon)
npm run electron:dist:linux         # Linux (all targets)
npm run electron:dist:linux:x64     # Linux x64 (tar.gz, deb, rpm, AppImage)
npm run electron:dist:linux:arm64   # Linux ARM64
npm run electron:dist:linux:arm     # Linux ARMv7

The built applications will be available in the dist/ directory.

Build targets:

• Windows: NSIS installer (.exe)
• macOS: DMG package (.dmg)
• Linux: AppImage, deb, rpm, Pacman packages

Create a .env file in the server/ directory:

# Add your environment variables here
# See server/.env.example for reference

Electron Builder configuration is in package.json under the build key:

• App ID: com.storytel.player
• Product Name: Storytel Player
• Output Directory: dist/

• The Electron app features a compact UI (480x800 window size) optimized for desktop use
• Single instance lock prevents multiple app instances from running simultaneously
• In development mode, the app connects to local dev servers (React on port 3000, Fastify on port 3001)
• In production mode, the app serves static files from client/build/ and runs the bundled server
• The embedded Fastify server is managed by the Electron main process
• TypeScript is used throughout the project (Electron, React, and Fastify)
• Certificate errors are ignored in development mode for local HTTPS testing

• Frontend: React 18, TypeScript, Tailwind CSS, Vite, i18next, Axios
• Backend: Fastify 5, TypeScript, @fastify/cors, dotenv
• Desktop: Electron 38+, electron-store
• Build Tools: Vite, esbuild, electron-builder, TypeScript compiler
• Development: Concurrently, tsx (for server watch mode)

Visit our official documentation

MIT License

Andrea Debernardi (andrea@debbaweb.it)