A command-line tool that scans your local music library, reports lossless vs. lossy albums, and generates a shopping list with purchase links from Bandcamp and Qobuz for any albums not yet in lossless format.
- Scans a music directory structured as
Artist / Album / tracks - Detects lossless formats: FLAC, APE, WAV, AIFF, WV, ALAC
- Flags non-lossless albums (MP3, AAC, OGG, etc.) with a warning
- Displays a summary table (total artists, albums, lossless/non-lossless counts)
- Searches Bandcamp first for purchase links; falls back to Qobuz when no Bandcamp match is found
- Generates a Markdown report (
MD/result.md) with the full library overview
- Python 3.10+
- requests
- beautifulsoup4
- colorama
-
Install Python 3.10+ (most distributions already include it):
# Debian / Ubuntu sudo apt update && sudo apt install python3 python3-pip # Fedora / RHEL sudo dnf install python3 python3-pip # Arch Linux sudo pacman -S python python-pip
-
Clone or download this repository:
git clone https://github.com/Zesseth/AlbumBrowser.git cd AlbumBrowser -
Install dependencies:
pip3 install requests beautifulsoup4 colorama
Tip: Use a virtual environment to keep your system Python clean:
python3 -m venv .venv source .venv/bin/activate pip install requests beautifulsoup4 colorama
-
Install Python 3.10+ from https://www.python.org/downloads/.
During installation, check "Add Python to PATH". -
Clone or download this repository:
git clone https://github.com/Zesseth/AlbumBrowser.git cd AlbumBrowser
Alternatively, download the ZIP from GitHub and extract it.
-
Install dependencies (in Command Prompt or PowerShell):
pip install requests beautifulsoup4 colorama
Tip: Use a virtual environment:
python -m venv .venv .venv\Scripts\activate pip install requests beautifulsoup4 colorama
-
Install Python 3.10+.
The recommended way is via Homebrew:brew install python
Or download from https://www.python.org/downloads/.
-
Clone or download this repository:
git clone https://github.com/Zesseth/AlbumBrowser.git cd AlbumBrowser -
Install dependencies:
pip3 install requests beautifulsoup4 colorama
Tip: Use a virtual environment:
python3 -m venv .venv source .venv/bin/activate pip install requests beautifulsoup4 colorama
Linux / macOS:
python3 album_browser.py "/path/to/your/Music"Windows (Command Prompt):
python album_browser.py "C:\Users\YourName\Music"Windows (PowerShell):
python album_browser.py "C:\Users\YourName\Music"| Option | Description |
|---|---|
--no-bandcamp |
Skip Bandcamp search |
--no-qobuz |
Skip Qobuz search |
--no-report |
Skip Markdown report generation |
Examples:
python album_browser.py "C:\Users\User\Music"
python album_browser.py ~/Music --no-bandcampMusic/
├── Artist Name/
│ ├── Album Title/
│ │ ├── 01 - Track.flac
│ │ └── 02 - Track.flac
│ └── Another Album/
│ └── 01 - Track.mp3
└── Another Artist/
└── ...
Loose audio files placed directly inside an artist folder are grouped under (Irrallisia kappaleita).
The tool prints a colour-coded tree of your library to the terminal and, unless --no-report is given, writes a Markdown summary to MD/result.md next to the script.
After a successful run, a report is saved to MD/result.md next to album_browser.py.
The report contains:
- 🎤 Artist sections listing every album with format, track count, and size.
- 📊 Summary table with total artist, album, lossless, and non-lossless counts.
- 🛒 Shopping list of albums to upgrade, with a purchase link per entry (Bandcamp preferred, Qobuz as fallback).
Ways to view the rendered Markdown:
| Platform | Method |
|---|---|
| GitHub | Push the file to a repository — GitHub renders .md files automatically. |
| VS Code | Open result.md, then press Ctrl+Shift+V (Windows/Linux) or Cmd+Shift+V (macOS) for the built-in preview. |
| Typora | Open the file directly — Typora renders Markdown live. typora.io |
| Obsidian | Add the MD folder to an Obsidian vault and open result.md. obsidian.md |
| Browser | Use a browser extension such as Markdown Viewer (Chrome/Firefox) to open and render the file locally. |
| Command line | Install glow (brew install glow on macOS, or download from github.com/charmbracelet/glow) and run glow MD/result.md. |
Tip: The shopping list contains clickable hyperlinks. These are only interactive in rendered Markdown viewers — plain-text editors will show the raw link syntax.
| Format | Type |
|---|---|
| FLAC | ✅ Lossless |
| WAV | ✅ Lossless |
| AIFF | ✅ Lossless |
| ALAC (.alac) | ✅ Lossless |
| APE | ✅ Lossless |
| WavPack (.wv) | ✅ Lossless |
| MP3 | |
| M4A / AAC (.m4a / .aac) | |
| OGG | |
| WMA | |
| OPUS |
This project is licensed under the GPL-3.0 License. See LICENSE for details.