Audiovault is a powerful, self-hosted application designed to import, manage, and download your music libraries from any major streaming platform directly to your local server. Built with performance, aesthetics, and reliability in mind.
Import playlists, albums, and tracks from:
- Playlists, albums, liked songs, recommendations
- Playlists, mixes, videos, channels
- Native search, artist profiles, playlists
- Tracks, playlists, user libraries
- Playlists, library, recommendations
- Playlists, favorites, discovery
- Playlists, library, recommendations
Never miss a track. If a download fails (e.g., due to geo-restrictions or broken links), Audiovault automatically:
- Tries alternative search queries (Official Audio, Lyrics Video)
- Searches cross-platform (e.g., falls back to SoundCloud if YouTube fails)
- Uses proxies (Invidious) to bypass region locks
- Auto-Sync: Background scheduler checks for new tracks every 60 minutes
- Safe Purge: Automatically removes local tracks that were deleted from remote playlists (with specific user approval & dry-run safety)
- Smart De-duplication: Prevents duplicate downloads by checking both ID3 tags and internal database history
- Universal Search: Unified search bar for all supported providers
- MP3: 128kbps, 192kbps, 320kbps
- FLAC: Lossless audio for audiophiles
- FLAC: Lossless audio for audiophiles
- Automatic format selection based on user preferences
- Scrobbling: Automatically sync your listening history to Last.fm
- Recommendations: Personalized track suggestions based on your taste
- Integration: Easy setup with OAuth connection
- Read the Setup Guide
Note: When creating your API key, use
http://localhost:2137/recommendationsas the Callback URL.
Turn Audiovault into your personal Spotify.
- Subsonic API Support: Native implementation of the Subsonic API (v1.16.1)
- Mobile Apps: Stream your library to your phone using Symfonium, Amperfy, DSub, or any Subsonic-compatible player
- Remote Access: Works seamlessly with Tailscale for secure remote streaming without port forwarding
- Legacy Auth: REQUIRED for most clients. Enable "Legacy Authentication" or "Use plaintext password" in your app settings (Amperfy, Symfonium).
- Hierarchical View: Browse by Service → Playlist → Tracks
- Folders: Organizational structure that keeps your library clean
- Management: Rename files, edit metadata, and manage storage directly from the UI
- Rescan: Detects manually added files or fixes missing entries
- Glassmorphism: Stunning, responsive interface powered by React & TailwindCSS
- Neon Aesthetics: New "Liquid Neon" styling with glowing borders and glass effects
- Audio Visualizer: Real-time frequency equalizer synced to music playback
- Themes: Deep Void (Default), Midnight, Ocean, Forest, Sunset, Neon
- Feedback: Real-time progress updates via WebSocket notifications
- i18n: Multi-language support (English, Polish, German, French, Spanish)
| Component | Technology |
|---|---|
| Backend | Python, FastAPI, yt-dlp, SQLAlchemy (Async), APScheduler |
| Frontend | React, TypeScript, TailwindCSS v4, Framer Motion |
| Database | SQLite (default) / PostgreSQL (supported), Redis (Caching) |
| Infrastructure | Docker & Docker Compose |
The recommended way to run Audiovault is via Docker.
-
Clone the repository:
git clone https://github.com/Bl4nk44/Audiovault.git cd Audiovault -
Configure Environment: Rename
.env.exampleto.envand fill in the necessary secrets.cp .env.example .env
-
Run with Docker:
docker compose up -d --build
- Frontend:
http://localhost:2137 - Backend API:
http://localhost:8000/docs
Note: On first launch, a random admin password will be generated and printed to the container logs (
docker compose logs backend). To set a custom password, addADMIN_PASSWORD=yourpasswordto your.envfile before starting. Default username:admin - Frontend:
Audiovault supports running behind reverse proxies (Nginx, Traefik, etc.) out of the box.
-
Environment Variables: Set
ALLOWED_HOSTSandBACKEND_CORS_ORIGINSin your.envfile to match your domain:ALLOWED_HOSTS=audiovault.example.com,localhost BACKEND_CORS_ORIGINS=https://audiovault.example.com
Docker Configuration: If running behind a proxy or in a custom Docker network, ensure the Frontend container knows how to reach the Backend:
# In docker-compose.yml or env: BACKEND_URL=http://audiovault-backend:8000 -
Docker Setup: The Docker image is already configured to trust
X-Forwarded-*headers from any proxy viauvicorn.middleware.proxy_headers. Ensure your proxy passes these headers correctly.
For detailed guides and documentation, please visit our Wiki:
- Getting Started
- Configuration Guide
- Usage Guide
- Architecture
- Development Setup
- FAQ & Troubleshooting
- Get Help - Troubleshooting guide and FAQ
- Report a Bug - Submit a bug report
- Request a Feature - Suggest new features
- Ask Questions - Community discussions
Contributions are welcome! Please read our Contributing Guide to learn about:
- How to report bugs and suggest features
- Development setup and workflow
- Code style guidelines
- Testing requirements
- Pull request process
Quick contribution process:
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Commit your changes:
git commit -m 'feat: Add my feature' - Push to the branch:
git push origin feature/my-feature - Open a Pull Request
If you discover a security vulnerability, please email bl4nk44@pm.me instead of using the issue tracker.
For more information, see our Security Policy.
This project adheres to a Code of Conduct. By participating, you are expected to uphold this code.
Distributed under the MIT License. See LICENSE for more information.
- yt-dlp - Powerful video/audio downloader
- FastAPI - Modern Python web framework
- React - JavaScript library for building UIs
- TailwindCSS - Utility-first CSS framework
- SQLAlchemy - Python SQL toolkit