A modern, responsive web interface for audiobook-dl - download audiobooks from various online services through an easy-to-use web application.
With Docker (Recommended):
git clone https://github.com/yourusername/audiobook-dl-web.git
cd audiobook-dl-web
docker-compose up -dOpen http://localhost:8000 → Configure Services → Enter credentials → Download → Paste URLs → Start Download
Without Docker:
git clone https://github.com/yourusername/audiobook-dl-web.git
cd audiobook-dl-web
python -m venv venv
source venv/bin/activate # Linux/macOS
# Or: .\venv\Scripts\Activate.ps1 (Windows PowerShell)
pip install -e .
# Install ffmpeg: apt-get install ffmpeg (Linux) | brew install ffmpeg (macOS) | winget install Gyan.FFmpeg (Windows)
python -m app.main # Or on Windows: .\start.ps1Open http://localhost:8000
audiobook-dl-web is a self-hosted web interface for audiobook-dl, making it easy to download audiobooks from multiple services through your browser. Everything that audiobook-dl supports, this web interface supports too.
Configure Your Services: Set up login credentials for any audiobook service supported by audiobook-dl, including Storytel, Saxo, Nextory, eReolen, Podimo, YourCloudLibrary, Everand, and more. Your credentials are stored securely in a local configuration file, so you only need to enter them once.
Track Downloads in Real-Time: Watch your audiobook downloads progress with live percentage updates that reflect actual download status. Each task shows detailed progress messages from authentication through file combining, with metadata automatically extracted when complete—including title, author, narrator, duration, and file size. Service badges identify which platform each audiobook comes from at a glance.
Manage Your Queue Efficiently: Download multiple audiobooks simultaneously with configurable concurrency (1-10 downloads at once). Collapse individual downloads or the entire queue to stay focused on active items while keeping completed ones accessible. The interface maintains your collapsed state even as downloads update, keeping your workspace organized.
Customize Output Properties: Configure how your audiobooks are saved—choose the output format (M4B, MP3, M4A), customize the file naming template with variables like {author}/{series}/{title}, decide whether to combine audio parts into a single file, and control chapter information. Set these options per-download or save them as global defaults.
Self-Host Anywhere: Deploy with Docker for one-command setup, or run manually on any system with Python 3.14+. The responsive web interface works on desktop and mobile, with dark mode support optimized for readability. All downloads are saved to your local storage with full file paths displayed, and comprehensive logging helps you track everything that happens.
- TL;DR - Quick Start
- Features
- Installation
- Usage
- Configuration
- Supported Services
- Advanced Options
- Logging
- Development
- Troubleshooting
- Contributing
- License
The easiest way to run audiobook-dl-web is using Docker:
# Clone the repository
git clone https://github.com/yourusername/audiobook-dl-web.git
cd audiobook-dl-web
# Copy the example environment file
cp .env.example .env
# Edit .env if needed (optional)
nano .env
# Start with docker-compose
docker-compose up -dThe application will be available at http://localhost:8000
The Docker Compose configuration creates three important volumes:
./config- Storesaudiobook-dl.tomlconfiguration file with credentials./downloads- Stores downloaded audiobooks./logs- Stores application logs with timestamps
These directories are automatically created and persisted on your host machine.
Deploy audiobook-dl-web as a custom app in TrueNAS Community Edition:
Create datasets for the deployed app via the UI: Datasets → Add Dataset (create one parent audiobook-dl-web and three children datasets: config, downloads, logs), can be of Generic type.
- Navigate to Apps → Discover Apps → Custom App
- Configure the following settings:
Application Name:
- Name:
audiobook-dl-web
Container Images:
- Image Repository:
ghcr.io/bartekmp/audiobook-dl-web - Image Tag:
<insert a specific version tag here>(orlatestfor the newest version) - Pull Policy:
Always Pull Image
Container Environment Variables:
- Add the following variables (click Add for each):
- Name:
CONFIG_DIR, Value:/app/config - Name:
DOWNLOADS_DIR, Value:/app/downloads - Name:
HOST, Value:0.0.0.0 - Name:
PORT, Value:8000 - Name:
DEBUG, Value:false - Name:
SECRET_KEY, Value:change-this-to-a-random-secret-key
- Name:
Networking:
- Host Network: Leave unchecked
- Add Port:
- Container Port:
8000 - Host Port:
8000 - Protocol:
TCP
- Container Port:
Storage:
- Add three Host Path volumes (click Add for each):
- Host Path:
/mnt/tank/audiobook-dl-web/config, Mount Path:/app/config - Host Path:
/mnt/tank/audiobook-dl-web/downloads, Mount Path:/app/downloads - Host Path:
/mnt/tank/audiobook-dl-web/logs, Mount Path:/app/logs
- Host Path:
Resources Configuration:
- CPU:
2(2 CPUs) - adjust based on your needs - Memory:
2G(2048 MiB / 2 GiB) - adjust based on your needs
- Click Install
The application will be available at http://your-truenas-ip:8000
Note: The built-in health check in the Docker image will automatically monitor the application status in TrueNAS.
If you prefer to run without Docker:
# Clone the repository
git clone https://github.com/yourusername/audiobook-dl-web.git
cd audiobook-dl-web
# Create a virtual environment
python -m venv venv
source venv/bin/activate # Linux/macOS
# On Windows PowerShell: .\venv\Scripts\Activate.ps1
# On Windows CMD: venv\Scripts\activate.bat
# Install dependencies
pip install -e .
# Install ffmpeg (required for combining audio files)
# On Ubuntu/Debian:
sudo apt-get install ffmpeg
# On macOS:
brew install ffmpeg
# On Windows:
winget install -e Gyan.FFmpeg
# Create necessary directories
mkdir -p config downloads logs # Linux/macOS
# On Windows PowerShell: New-Item -ItemType Directory -Path config, downloads, logs -Force
# Copy environment file (optional)
cp .env.example .env # Linux/macOS
# On Windows: copy .env.example .env
# Start the application
python -m app.main # Or on Windows PowerShell: .\start.ps1The application will be available at http://localhost:8000
- Navigate to Configure Services in the menu
- Select a service from the list (e.g., Storytel, Saxo)
- Enter your credentials (username and password)
- Click Save Configuration
Your credentials are stored securely in config/audiobook-dl.toml.
- Navigate to Download in the menu
- Paste one or more audiobook URLs (one per line)
- Important for Storytel: Make sure the book is added to your shelf before downloading!
- (Optional) Configure advanced options:
- Output template (e.g.,
{author}/{series}/{title}) - Output format (M4B, MP3, M4A)
- Combine files into a single file
- Include/exclude chapter information
- Output template (e.g.,
- Click Start Download
- Monitor progress in the download queue
Failed downloads are clearly marked with error details:
Navigate to Settings to configure:
- Default output template - Customize where files are saved
- Skip already downloaded books - Avoid re-downloading
- Create folder for downloaded books - When enabled, each audiobook will be downloaded to a dedicated folder named using the output template (default: disabled)
- Group by author - When enabled, downloads are placed under an author directory in the downloads folder
- Maximum concurrent downloads - Control how many audiobooks download simultaneously (1-10, default: 2)
- View current configuration
The application can be configured using environment variables in .env:
# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=false
# Paths
CONFIG_DIR=/app/config
DOWNLOADS_DIR=/app/downloads
# Security
SECRET_KEY=change-this-to-a-random-secret-key-in-productionThe configuration file (config/audiobook-dl.toml) stores service credentials and global settings:
# Global settings
output_template = "{author}/{title}"
skip_downloaded = true
create_folder = false
group_by_author = false
max_concurrent_downloads = 2
# Service credentials
[sources.storytel]
username = "your_username"
password = "your_password"
[sources.saxo]
username = "your_email@example.com"
password = "your_password"audiobook-dl-web supports all services provided by audiobook-dl, see Supported Services list for more info.
Each service requires specific URL formats. Examples:
- Storytel:
https://www.storytel.com/pl/books/book-name-12345 - Saxo:
https://www.saxo.com/en/book-name - Nextory:
https://nextory.com/book/example
The listening page URL is required, not just the information page.
Customize where audiobooks are saved using these variables:
{title}- Book title{author}- Author name{series}- Series name{narrator}- Narrator name
Examples:
{title}→Book Name.m4b{author}/{title}→Author Name/Book Name.m4b{author}/{series}/{title}→Author Name/Series Name/Book Name.m4b
With "Create folder for downloaded books" enabled:
- Template:
{title}→ Folder:Book Name/, File:Book Name.m4b - Template:
{title} - {author}→ Folder:Book Name - Author Name/, File:Book Name - Author Name.m4b - This is useful when audiobooks consist of multiple files, keeping all parts organized in a dedicated folder
If group_by_author = true, downloads are placed under an author directory in the downloads folder.
- With
create_folder = false:Downloads/{author}/{output_template}.m4b - With
create_folder = true:Downloads/{author}/{output_template}/{output_template}.m4b
This works well with an output_template like {title} - {author} and keeps multi-book libraries organized by author.
Supported output formats:
- M4B - Audiobook format (recommended)
- MP3 - Universal audio format
- M4A - MPEG-4 audio
Enable "Combine all files into a single file" to merge all audio parts into one file. Requires ffmpeg.
# Set DEBUG mode
export DEBUG=true
# Run with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000The application provides a REST API:
GET /- Home pageGET /configure- Configuration pagePOST /configure/{service}- Save service configurationGET /download- Download pagePOST /api/download- Start downloadsGET /api/tasks- Get all download tasksGET /api/tasks/{task_id}- Get specific task statusPOST /api/tasks/{task_id}/cancel- Cancel a taskDELETE /api/tasks/{task_id}- Remove a specific taskPOST /api/tasks/clear- Clear completed tasksGET /settings- Settings pagePOST /settings- Update settingsGET /health- Health check
- Storytel users: Ensure the book is added to your shelf/library
- Check that credentials are correct in the configuration
- Verify the URL format is correct (use the listening page URL)
- Ensure
audiobook-dlis installed:pip install audiobook-dl - In Docker, rebuild the container:
docker-compose build
# Fix permissions for config and downloads directories
sudo chown -R $USER:$USER config downloads- Ensure
ffmpegis installed - In Docker,
ffmpegis included automatically - Manually:
apt-get install ffmpeg,brew install ffmpegorwinget install -e Gyan.FFmpeg
- Check browser console for errors (F12)
- Ensure JavaScript is enabled
- Try refreshing the page
- Adjust Maximum Concurrent Downloads in Settings (default: 2)
- Lower values reduce server load and avoid rate limiting
- Higher values (up to 10) can speed up batch downloads if the service allows it
The configuration file is located at:
- Docker:
./config/audiobook-dl.toml - Manual:
./config/audiobook-dl.tomlor as specified in.env
You can edit this file manually if needed.
This tool is intended for downloading audiobooks you have legal access to. Please respect copyright laws and the terms of service of the audiobook platforms you use.
Some services may have rate limits. The application limits concurrent downloads to 2 by default to avoid triggering rate limits. You can adjust this in Settings → Maximum Concurrent Downloads (range: 1-10) based on your needs and the service's tolerance.
The application logs all important events with timestamps to help you track what's happening:
- Download Queue: When URLs are added to the download queue
- Download Status: Status changes (pending → downloading → completed/failed) with duration
- Configuration Changes: When service credentials are updated or deleted
- Settings Changes: When global settings are modified
Logs use the standard Python logging format:
2024-01-15 14:32:45,123 - app.main - INFO - Adding 3 URL(s) to download queue
2024-01-15 14:32:45,456 - app.download_manager - INFO - Download started - Task: abc-123, URL: https://...
2024-01-15 14:35:12,789 - app.download_manager - INFO - Download completed - Task: abc-123, Duration: 147.3s
2024-01-15 14:35:20,123 - app.config_manager - INFO - Configuration updated - service: storytel, fields: username, password
Docker: Logs are available in the ./logs directory (mounted volume)
tail -f logs/audiobook-dl-web.logManual Installation: Logs are stored in the logs/ directory in your installation path
View in Docker: You can also view logs using Docker commands
docker-compose logs -f audiobook-dl-webThis project is licensed under the MIT License - see the LICENSE file for details.
audiobook-dl - The underlying audiobook download library
If you encounter any issues or have questions:
- Check the Troubleshooting section
- Review audiobook-dl documentation
- Open an issue on GitHub
Disclaimer: This project is not affiliated with or endorsed by any of the supported audiobook services. Use responsibly and in accordance with applicable laws and terms of service.