Deploying Audioserve

Audioserve is a simple, lightweight, self-hosted audiobook server written in Rust. Designed with a minimalist approach, it serves audio files directly from your folder structure—no complex database setup or metadata management required. Just point it at your audiobook collection and start listening.

With a modern Progressive Web App (PWA) client built with Svelte and TypeScript, Audioserve offers offline listening, shared playback positions across devices, and on-the-fly transcoding to save bandwidth. It’s perfect for personal audio collections where simplicity and performance matter most.

Lightning Fast

Written in Rust for maximum performance with minimal resources

PWA Client

Install as an app with offline support and track caching

Position Sync

Share playback positions across all your devices

Transcoding

On-the-fly conversion to opus/mp3/aac for bandwidth savings

Key Features

Audioserve provides a focused feature set for audiobook enthusiasts:

Feature	Description
Folder-Based	Browse your library exactly as it’s organized on disk
Chapter Support	M4B files and similar formats display chapters as virtual files
Multiple Collections	Serve separate libraries (e.g., different languages)
Shared Positions	Continue listening on any device from where you left off
Smart Caching	Fast search and browsing via embedded key-value database
Transcoding	Convert audio on-the-fly to lower bitrates
Folder Download	Download entire audiobooks as tar/zip archives
Tags Display	Optionally show audio metadata tags

Why Audioserve?

Feature	Audioserve	Full-Featured Servers
Complexity	Minimal, folder-based	Database-driven, complex metadata
Resource Usage	Very lightweight	Higher requirements
Setup Time	Minutes	Hours of configuration
Philosophy	”Your folders, your way"	"Organized by tags/metadata”
Best For	Personal use, well-organized collections	Large multi-user libraries

Prerequisites

Before deploying Audioserve on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment configuration
• Your audiobook collection organized in folders

Project Structure

Set up your Audioserve deployment:

• Directoryaudioserve/

  • Dockerfile
  • docker-compose.yml (local development)
  • config.yaml (optional configuration)
  • README.md

Deployment Configuration

Dockerfile

Create a Dockerfile for your Audioserve deployment:

Dockerfile

FROM izderadicka/audioserve:latest

# Set environment variables
ENV AUDIOSERVE_SHARED_SECRET=your-secure-secret-here
ENV RUST_LOG=info

# Expose the default port
EXPOSE 3000

# Create directories
RUN mkdir -p /audiobooks /home/audioserve/.audioserve

# Default entrypoint runs audioserve with provided arguments
CMD ["--tags", "--behind-proxy", "/audiobooks"]

Custom Dockerfile with Additional Features

For a more feature-rich deployment:

Dockerfile

FROM izderadicka/audioserve:latest

# Environment configuration
ENV AUDIOSERVE_SHARED_SECRET=your-secure-secret-here
ENV RUST_LOG=info

# Create necessary directories
RUN mkdir -p /audiobooks /podcasts /home/audioserve/.audioserve

# Expose port
EXPOSE 3000

# Run audioserve with multiple collections and features
CMD ["--tags", \
     "--behind-proxy", \
     "--compress-responses", \
     "--positions-backup-file", "/home/audioserve/.audioserve/positions-backup.json", \
     "--positions-backup-schedule", "0 3 * * *", \
     "/audiobooks", "/podcasts"]

Environment Variables

Audioserve is configured primarily through command-line arguments and environment variables:

Variable	Description
AUDIOSERVE_SHARED_SECRET	Authentication secret (required for secure access)
RUST_LOG	Log level (error, warn, info, debug, trace)
PORT	HTTP port (defaults to 3000)

Command-Line Arguments

Key arguments for audioserve:

Argument	Description
--tags	Scan and display audio metadata tags
--behind-proxy	Log real client IP when behind reverse proxy
--compress-responses	Enable gzip compression for responses
--no-authentication	Disable authentication (testing only!)
--transcoding-max-parallel-processes N	Max concurrent transcodings
--positions-backup-file PATH	Backup playback positions to JSON file
--positions-backup-schedule CRON	Backup schedule in cron format
--data-dir PATH	Directory for audioserve data
--collapse-cd-folders	Merge CD subfolders into parent

Optional Configuration File

For complex setups, use a YAML config file:

config.yaml

# Transcoding configuration
transcoding:
  low:
    opus-in-ogg:
      bitrate: 32
      compression_level: 3
      cutoff: WideBand
      mono: true
  medium:
    opus-in-ogg:
      bitrate: 48
      compression_level: 6
      cutoff: SuperWideBand
  high:
    opus-in-ogg:
      bitrate: 64
      compression_level: 9
      cutoff: FullBand

# Apple device support (Safari)
# transcoding:
#   alt_configs:
#     "iPhone|iPad|Mac OS":
#       low:
#         aac-in-adts:
#           bitrate: 32
#           mono: true
#       medium:
#         aac-in-adts:
#           bitrate: 48
#       high:
#         aac-in-adts:
#           bitrate: 64

Local Development with Docker Compose

Test your Audioserve setup locally:

docker-compose.yml

services:
  audioserve:
    image: izderadicka/audioserve:latest
    container_name: audioserve
    ports:
      - "3000:3000"
    volumes:
      - ./audiobooks:/audiobooks:ro
      - audioserve-data:/home/audioserve/.audioserve
    environment:
      - AUDIOSERVE_SHARED_SECRET=mydevpassword
      - RUST_LOG=info
    command: ["--tags", "/audiobooks"]
    restart: unless-stopped

volumes:
  audioserve-data:

Tip

Run docker compose up -d to start Audioserve locally. Access it at http://localhost:3000 and use your shared secret to authenticate.

Deploying to Klutch.sh

1. Push your repository to GitHub

   1. Initialize your Git repository and commit the Dockerfile

   git init
   git add .
   git commit -m "Initial Audioserve configuration"
   git remote add origin https://github.com/yourusername/audioserve.git
   git push -u origin main

2. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

3. Configure environment variables

   1. In your app settings, add the following environment variables

   Variable	Value
   AUDIOSERVE_SHARED_SECRET	A strong secret phrase (14+ characters recommended)
   RUST_LOG	info

   Security

   Use a strong shared secret! This is the only authentication mechanism. Never use --no-authentication in production.

4. Configure the internal port

   1. Set the internal port to 3000 (Audioserve’s default port)
   2. Select HTTP as the traffic type

5. Set up persistent storage

   1. Add persistent volumes for your audio library and server data

   Mount Path	Size	Purpose
   /audiobooks	100 GB+	Your audiobook collection
   /home/audioserve/.audioserve	5 GB	Cache, positions, server secret

   Note

   Adjust the /audiobooks volume size based on your collection. You can add multiple collection volumes if needed (e.g., /podcasts, /lectures).

6. Deploy your application

   1. Click Deploy to build and launch your Audioserve server
   2. Monitor the build logs for any issues
   3. Once deployed, your server will be available at https://your-app.klutch.sh

7. Access your server

   1. Visit your deployed URL
   2. Enter your shared secret to authenticate
   3. Browse your audiobook collection

Organizing Your Library

Recommended Directory Structure

Audioserve works best with well-organized folders:

/audiobooks/
├── Asimov, Isaac/
│   └── Foundation Series/
│       ├── 01 - Foundation/
│       │   ├── 001 - First Chapter.mp3
│       │   ├── 002 - Second Chapter.mp3
│       │   └── cover.jpg
│       └── 02 - Foundation and Empire/
│           └── audiobook.m4b
├── Tolkien, J.R.R./
│   └── The Lord of the Rings/
│       ├── 01 - Fellowship of the Ring/
│       └── 02 - The Two Towers/
└── Single Audiobook.m4b

Key Organization Tips

Tip	Description
Author folders	Use “Last Name, First Name” format
Series folders	Group related books together
Numbered prefixes	Ensure correct file ordering (001, 002, etc.)
Cover images	Add cover.jpg or cover.png to folders
Descriptions	Add description.txt or description.html

Single-File Audiobooks

M4B and similar files with chapter metadata are displayed as virtual folders:

The Hobbit.m4b → displays as:
└── The Hobbit.m4b/
    ├── Chapter 01 - An Unexpected Party
    ├── Chapter 02 - Roast Mutton
    └── ...

Using the Web Client

PWA Installation

The web client can be installed as a Progressive Web App:

1. Open your Audioserve URL in Chrome/Firefox
2. Click the install icon in the address bar
3. The app installs with offline support

Shared Playback Positions

To sync positions across devices:

1. On login, set a Device Group name
2. Use the same group name on all your devices
3. Positions automatically sync within the group

Transcoding Quality

Select quality levels during playback:

Level	Default Bitrate	Best For
Low	32 kbps opus	Mobile data, slow connections
Medium	48 kbps opus	Balanced quality/bandwidth
High	64 kbps opus	Good connections
Original	No transcoding	Local network, unlimited data

Multiple Collections

Add multiple libraries by modifying your Dockerfile:

Dockerfile

FROM izderadicka/audioserve:latest

ENV AUDIOSERVE_SHARED_SECRET=your-secure-secret

EXPOSE 3000

RUN mkdir -p /audiobooks /podcasts /lectures /home/audioserve/.audioserve

CMD ["--tags", "--behind-proxy", "/audiobooks", "/podcasts", "/lectures"]

Each collection appears as a separate library in the client.

Apple Device Support

Safari and iOS require AAC transcoding instead of Opus. Add this configuration:

config.yaml

transcoding:
  alt_configs:
    "iPhone|iPad|Mac OS":
      low:
        aac-in-adts:
          bitrate: 32
          sr: "24kHz"
          mono: true
      medium:
        aac-in-adts:
          bitrate: 48
      high:
        aac-in-adts:
          bitrate: 64

Then update your Dockerfile to use the config:

CMD ["--config", "/config.yaml", "--tags", "--behind-proxy", "/audiobooks"]

Security Best Practices

Strong Secret

Use 14+ character shared secret phrase

HTTPS Only

Klutch.sh provides automatic SSL certificates

No Auth = No Production

Never use —no-authentication on the internet

Regular Updates

Keep audioserve updated for security fixes

Changing the Shared Secret

If you suspect your secret is compromised:

1. Stop your deployment
2. Delete the /home/audioserve/.audioserve/audioserve.secret file
3. Update AUDIOSERVE_SHARED_SECRET environment variable
4. Redeploy (this invalidates all existing tokens)

Backup and Restore

Position Backups

Enable automatic position backups in your Dockerfile:

CMD ["--tags", \
     "--positions-backup-file", "/home/audioserve/.audioserve/positions.json", \
     "--positions-backup-schedule", "0 3 * * *", \
     "/audiobooks"]

Restoring Positions

To restore from a backup:

# One-time restore command
audioserve --positions-restore=v1 \
           --positions-backup-file /path/to/positions.json \
           /audiobooks

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
Can’t authenticate	Wrong shared secret	Verify AUDIOSERVE_SHARED_SECRET matches
Slow initial load	Cache being built	Wait for initial scan to complete
Search not working	Cache incomplete	Allow full scan to finish
Files not showing	Wrong permissions	Ensure files are readable
No cover art	Missing image file	Add cover.jpg to folder
Apple devices no audio	Opus not supported	Configure AAC transcoding

Checking Logs

Monitor server activity:

# Set verbose logging
ENV RUST_LOG=debug

Force Cache Rebuild

If the cache becomes inconsistent, trigger a full rescan by redeploying with:

CMD ["--force-cache-update", "--tags", "/audiobooks"]

Remove --force-cache-update after the first successful scan.

API Access

Audioserve provides a simple REST API for custom clients:

# Get collection contents
curl "https://your-app.klutch.sh/0/folder" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search collection
curl "https://your-app.klutch.sh/0/search?q=foundation" \
  -H "Authorization: Bearer YOUR_TOKEN"

API documentation: Audioserve API

Additional Resources

• Audioserve GitHub Repository
• Official Demo Server (password: mypass)
• Web Client Repository
• Docker Hub Image
• API Documentation