A modern, secure, and delightfully over-engineered FastAPI microservice for automated audiobook approval workflows. Built by Quentin with maximum automation and minimum manual intervention in mind.
Last Audit: June 16, 2025 | Status: 13/13 Security Tests Passing | UI: Cyberpunk Theme Secured
- 🔒 Secure Webhook Endpoint - Token-validated integration with Autobrr/MAM
- 📖 Metadata Enrichment - Audnex API and Audible scraping for rich book data
- 💾 Persistent Storage - SQLite database with comprehensive audit trails
- ⏰ Time-Limited Tokens - Cryptographically secure, single-use approval tokens
- 📱 Multi-Platform Notifications - Pushover, Discord, Gotify, and Ntfy support
- 🎨 Beautiful Web Interface - Modern, responsive UI with cyberpunk/anime aesthetics
- 🌐 Social Media Ready - Dynamic OG/Twitter meta tags for all pages
- ⚙️ qBittorrent Integration - Automated torrent handling with MAM cookie support
- 🚀 Async Performance - Threadpool handling for optimal responsiveness
- 📊 Comprehensive Logging - Centralized, rotating logs with detailed audit trails
- ♿ Accessibility First - WCAG 2.1 AA compliance with ARIA labels and keyboard navigation
- 🧪 Test Coverage - Comprehensive unit and integration test suite
Complete documentation is available in the docs/ directory:
- 📖 Getting Started - Installation and setup guide
- ⚙️ Configuration - Configuration options and examples
- 🌐 Web Interface - Using the web UI
- 📱 Notifications - Setting up notification services
- 🔧 Troubleshooting - Common issues and solutions
- 🏗️ Architecture - System design and component overview
- 🔐 Security - Security implementation details
- 🎨 Interactive Fixes - UI/UX improvements
- 📋 Logging - Enhanced logging system
- 🧪 Testing - Testing strategies and guidelines
- 🌐 REST API - Complete API documentation
- 🔗 Webhooks - Webhook configuration and payloads
- 💾 Database - Database schema and queries
- 📋 Configuration - Complete configuration reference
# Clone the repository
git clone https://github.com/kingpaging/audiobook-automation.git
cd audiobook-automation
# Set up virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure the system
cp config/config.yaml.example config/config.yaml
# Edit config/config.yaml with your settings
# Initialize database
python src/db.py
# Start the application
python src/main.pyVisit http://localhost:8000 to access the beautiful web interface!
For detailed setup instructions, see the Getting Started Guide.
audiobook_dev/
├── docs/ # 📚 Comprehensive documentation
│ ├── user-guide/ # User documentation and guides
│ ├── development/ # Developer and architecture docs
│ └── api/ # API reference and webhooks
├── src/ # 🐍 Python source code
│ ├── main.py # FastAPI application entry point
│ ├── webui.py # Web interface and routes
│ ├── metadata.py # Audiobook metadata handling
│ ├── token_gen.py # Secure token generation/validation
│ ├── notify/ # 📱 Notification service modules
│ │ ├── pushover.py # Pushover notifications
│ │ ├── gotify.py # Gotify notifications
│ │ ├── discord.py # Discord notifications
│ │ └── ntfy.py # Ntfy notifications
│ ├── qbittorrent.py # qBittorrent integration
│ ├── db.py # SQLite database operations
│ ├── config.py # Configuration management
│ ├── html.py # Jinja2 template utilities
│ └── utils.py # Shared utility functions
├── templates/ # 🎨 Jinja2 HTML templates
│ ├── base.html # Base template with common elements
│ ├── index.html # Enhanced home page
│ ├── approval.html # Approval workflow page
│ ├── rejection.html # Witty rejection page
│ └── *.html # Additional UI templates
├── static/ # 🌐 Static web assets
│ ├── css/style.css # Enhanced cyberpunk styling
│ └── js/app.js # Interactive JavaScript features
├── tests/ # 🧪 Comprehensive test suite
├── config/ # ⚙️ Configuration files
│ └── config.yaml # Main application configuration
├── logs/ # 📋 Application logs
└── db.sqlite # 💾 SQLite database
-
Clone the repo
git clone <repo-url> cd audiobook_dev
-
Create and activate a virtualenv
python3 -m venv .venv source .venv/bin/activate -
Install dependencies
pip install -r requirements.txt
-
Copy and edit config
- Edit
config/config.yamlfor your environment (API URLs, notification settings, etc). - Create a
.envfile with your secrets (see.env.example).
- Edit
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload- The webhook endpoint is set in
config.yaml(default:/webhook/audiobook-requests). - The web UI is available at
/.
- Pushover: Rich HTML, cover image, approval link.
- Discord: Embed with cover, links, and markdown.
- Gotify: Markdown, cover image, action links.
- ntfy: Markdown, cover image, action links.
Configure each in config/config.yaml and .env.
- Uses Audnex API for fast, reliable metadata.
- Falls back to Audible scraping if needed.
- Cleans and normalizes author, narrator, series, and description fields.
- Caches lookups with LRU cache for efficiency.
-
Run all tests:
pytest -vv
-
Tests cover:
- Metadata cleaning and validation
- Notification formatting
- Web UI endpoints
- Error cases
-
Fixtures in
tests/conftest.pyfor isolation.
- Code style: Black, isort, flake8 recommended.
- Logging is configurable in
config.yaml. - All user input is sanitized before rendering or sending to notification services.
- For async/production, consider running with Gunicorn/Uvicorn workers.
- Webhook endpoints require a token (set in
.env). - Never commit
.envor real secrets. - All user input is sanitized.
MIT License. See LICENSE for details.