Audio Multi-Source Organizer (AMSO)
AMSO (Audio Multi-Source Organizer) is a modern, responsive, cross-platform desktop audio player (Windows, Linux, macOS). Built to give audiophiles complete control over their local music library (MP3, FLAC, OGG…), it now supports playlist files (M3U, PLS, XSPF, WPL), CUE sheets (single-file albums split into tracks) and features an interactive audio blind test game! The project is expanding to become a unified command center capable of organizing, deduplicating, and synchronizing hybrid music collections across local storage, cloud services (Google Drive), and streaming platforms (Spotify, Deezer, Amazon Music).
📌 Features & Project Status
| Feature | Description | Status |
|---|
| Audio Playback Engine | Lightweight, standalone audio player (portable VLC set up automatically on Windows). Two engines to choose from: direct VLC output, or a continuous buffer engine for smooth transitions between two tracks (Gapless 0 ms, equal-power crossfade, no cut in the audio output) | 🟢 Implemented |
| Library Management | Multithreaded recursive scan of local folders (MP3, FLAC, AAC, OGG...), manual, scheduled or real-time synchronization, trash and library statistics | 🟢 Implemented |
| Metadata & Artwork Extraction | ID3 tags, Vorbis Comments, and audio fingerprinting extraction (mutagen) | 🟢 Implemented |
| Playlist Files Support (M3U, PLS, XSPF, WPL) & CUE sheets | Tree-based indexing (🎶), natural sequential track ordering, visual missing track alerts; .cue files (💿) open like a folder of virtual tracks with their duration and play like real tracks | 🟢 Implemented |
| Playlist & Queue Management | Virtualized queue table, smooth drag & drop reordering, reversible shuffle, and repeat modes | 🟢 Implemented |
| Interactive « 🎲 Blind Test » Mode | Immersive music guessing game with animated pulsing countdown, soft audio fade-out, smooth reveal, and auto-progression | 🟢 Implemented |
| In-App Update Checker | Automatic and manual version checking via GitHub Releases | 🟢 Implemented |
| Linux & macOS versions | .AppImage / .tar.gz packages (Linux) and unsigned .dmg (macOS), VLC required | 🟡 Experimental (untested) |
| Artists & Discography Hub | Dedicated artist overview with albums, singles, and full discographies | 🟡 Planned |
| Graphical Equalizer (EQ) | Curated sound presets and multi-band parametric equalizer | 🟡 Planned |
| Google Drive Cloud Connector | Remote audio library indexing and streaming via OAuth 2.0 | ⚪ Planned |
| Amazon Music Connector | Remote music folder scanning and cloud sync via OAuth 2.0 | ⚪ Planned |
| Spotify / Deezer Streaming Integration | Playlist import and hybrid collection track matching | ⚪ Planned |
| Intelligent Deduplication | Duplicate detection based on fuzzy metadata and acoustic audio fingerprints | ⚪ Planned |
💡 For detailed milestones and version planning, refer to the Project Roadmap.
🚀 Quick Start
Prerequisites
Installation
# 1. Clone the repository
git clone https://github.com/LEF97/Audio-Multi-Source-Organizer.git
cd audio-multi-source-organizer
# 2. Create virtual environment
python -m venv .venv
# 3. Activate virtual environment
# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# Linux / macOS:
source .venv/bin/activate
# 4. Install dependencies
pip install -r requirements.txt
# For development & running tests:
pip install -e .[dev]
# 5. Configure environment variables
cp .env.example .env
# 6. Launch AMSO
python main.py
🐧🍎 Linux and macOS: experimental versions (untested)
The Linux (.AppImage / .tar.gz) and macOS (.dmg) packages are provided without having been tested: AMSO has only been validated on Windows. The continuous buffer audio engine (buffer) in particular has not been verified on these systems. Your feedback is valuable.
- VLC is required (AMSO only downloads it on Windows):
- Linux:
sudo apt install vlc (Debian / Ubuntu), sudo dnf install vlc (Fedora) or sudo pacman -S vlc (Arch).
- macOS: install VLC.app from videolan.org into the Applications folder.
- Linux, system libraries: the Qt interface notably needs
libpulse0 (sound), libxcb-cursor0 and libxkbcommon-x11-0 (for example sudo apt install libpulse0 libxcb-cursor0 libxkbcommon-x11-0).
- macOS, unsigned
.dmg: on first launch, right-click AMSO then choose Open, or run xattr -dr com.apple.quarantine /Applications/AMSO.app.
- Linux, AppImage: make it executable with
chmod +x AMSO*.AppImage.
- If you run into a problem, please send the
startup.log and crash.log files (if it exists) located in the data folder: ~/Library/Application Support/AMSO/ on macOS, ~/.local/share/AMSO/ on Linux. Please mention your system and your VLC version.
🧪 Running Tests
The test suite is built with pytest covering unit and integration scenarios:
pytest -v
Tests run automatically across Windows, macOS, and Ubuntu on every push via GitHub Actions.
🔒 Security & API Keys
- Never commit real API keys, secrets, or OAuth tokens.
- The project
.gitignore file is pre-configured to exclude .env, credentials.json, token.json, and local SQLite database files.
- Use
.env.example as a template for your local development environment.
📋 Documentation & Project Tracking
💖 Support the Project & Distribution
AMSO is 100% free and open-source software. If you enjoy the project and want to support ongoing development:
📄 License
This project is licensed under the GNU General Public License v3.0 (GPL-3.0) — see the LICENSE file for full details.
