A high-performance, private music meta-search and personal streaming platform. Mindinguflac allows users to aggregate metadata from multiple open sources, discover new artists through high-fidelity discography mapping, and manage a local media library with a modern, responsive interface.
Built with a Python backend and a Vanilla JS/CSS frontend, it functions as both a local web server and a native desktop application for macOS and Windows.
- Local taste profiles now learn from actual listening, likes, dislikes, and blacklists.
- Playlist recommendations continue from the end of manual playlists with dynamic replenishment; add or dismiss individual suggestions with automatic replacement.
- Playlist origins are stored explicitly so album-derived playlists stay separate from user-created playlists.
- Search, artist pages, and playlist recommendations now favor ID-first matching and taste-aware ranking.
- Stats month picker rebuilt as a proper dropdown overlay; home pill shows a house icon.
- Fixed SQLite database lock storms caused by background migration threads cascading on startup.
Personal listening stats with time-based filtering and listening-over-time chart
Top tracks ranked by play count and listened time, with top artists discovery
Playlist recommendations based on listening taste with quick-action context menu
Genre affinity chart and top albums derived from real listening history
- Metadata Centralization: Aggregates data from MusicBrainz, Discogs, and other open databases to provide a comprehensive view of musical history.
- Privacy First: Operates entirely locally. No user accounts, no tracking, and no external subscriptions required.
- High Fidelity: Supports FLAC and high-bitrate audio management with automatic quality-tiering.
- Interoperability: Seamlessly bridges web technologies with native desktop capabilities (Media Sessions, System Integrations).
- Modern UI: A sleek, dark-themed interface inspired by professional digital audio workstations.
- Smart Discovery: Dynamic multi-source search that maps artist discographies across studio albums, compilations, and live recordings.
- Local Library Management: Organizes your personal music collection into a structured
Artist/Album/Trackhierarchy. - Native Integration:
- macOS: Full "Now Playing" integration, Touch Bar support, and Media Key handling.
- Windows: Native audio output device selection and silent background processing.
- Advanced Streaming: Intelligent buffer management allowing you to listen while your media is being indexed or moved, with stable pause/resume across active-download and cached-file handoffs.
- Spotify Playlists: Import any public Spotify playlist by link — Mindinguflac loads the full track list, artwork, and metadata, then lets you stream or download each track in lossless quality (see the 70s 80s 90s playlist below).
- Discogs Integration: Optionally provide a Discogs personal token in Settings to fetch high-resolution vinyl sleeves, booklet images, and extended metadata for your album galleries.
- Playlist Engine: Create local playlists, manage queues, and import metadata from public share links.
- High-Quality Trackers: Integrated real-time health monitoring for public metadata swarms to ensure the most reliable connection.
- Smart Parallel Prefetching: Automatically downloads the next 5 tracks in your queue in parallel, ensuring instant transitions between songs.
- Persistent SQLite Engine: All successfully resolved Torrent magnets, YouTube URLs, and enriched metadata (Spotify IDs, ISRCs, MusicBrainz IDs) are now saved in a local SQLite database for instant offline access and to prevent redundant searches.
- Torrent Safety Filters: Adult/video vocabulary is stored in the local SQLite database and checked before fuzzy scoring and again after torrent metadata exposes internal file paths. Terms found in the requested track title or album are allowed only for that request; unrelated adult/video terms are still blocked.
- Optional AI Advisor: Clean torrent and YouTube candidates can be ranked in parallel by Gemini or DuckDuckGo/Duck.ai. AI never sees candidates blocked by the local adult/video filter and cannot override metadata checks or the "first real byte progress wins" torrent race.
- Improved YouTube Engine: Smart quality-scoring and automatic skipping of age-restricted or blocked videos with persistent blacklisting.
- Visual Quality Indicators: Real-time HI-RES and HQ badges in the player sidebar indicating the actual audio fidelity being streamed.
- Rich Now Playing Sidebar: Spotify-style right rail with artwork, quality badges, related music, artist information, credits, tour dates, and the next queue item.
- Live Tour Dates: A dedicated Spotify-style "All events" page lists an artist's upcoming concerts (venue, city, date, time, price), fetched via Hypebot/Bandsintown or the selected AI backend and cached locally with 12-hour renewal metadata.
Home - Discover and search your music
Artists - Explore your library by artist
Artist Detail - Rich metadata and discography browsing
About Artist - Extended biographies, follower counts, and global listening stats
Albums - High-fidelity album browsing
Album Booklet - View high-resolution liner notes and booklets (Discogs integration)
Playlists - Import and manage your Spotify collections
Queue - Now playing and upcoming tracks with drag-to-reorder
Now Playing Sidebar - Artwork, quality badge, and related music
Tour Sidebar - Live tour dates and the next-in-queue preview
Credits - Full artist, composer, writer, and performer credits
Tour Page - "All events" page with location-aware "near me" grouping
Tour Page - Upcoming concerts by country with venue, date, and time
Recently Played - Full playback history inside the queue panel
Now Playing Sidebar - Cover art, HI-RES/HQ badge, and related music
Sidebar - About the artist, credits, and live tour dates (sourced on-demand via AI web search)
Context Menu - Advanced track actions (Queue, Playlist, Exact Native Links)
Settings - Integration with Qobuz and Discogs for enhanced metadata
- Python 3.12 (the Windows torrent build requires 3.12;
libtorrenthas no 3.13/3.14 wheels) - FFmpeg (for audio processing)
This project is often developed on macOS and built for Windows from the same folder (e.g. a Parallels shared drive). Because a venv contains native, OS-specific binaries, macOS and Windows must use separate virtual environments so they never overwrite each other:
| OS | venv location | Created/used by |
|---|---|---|
| macOS | venv-macos (in project folder) |
run.sh, Mindinguflac.spec |
| Windows | venv-windows (in project folder) |
scripts/build_windows.ps1 |
The macOS and Windows venvs are both git-ignored. Keep them separate and never
point one OS at the other's venv. Override the Windows location with the
MINDINGUFLAC_VENV_DIR environment variable only when needed.
python3.12 -m venv venv-macos
source venv-macos/bin/activate
pip install -r requirements.txt
python app.py # or: ./run.sh (auto-creates venv-macos)# Build the desktop app (uses/creates .\venv-windows automatically):
powershell -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
# Or to run from source, create/use the project venv:
py -3.12 -m venv .\venv-windows
.\venv-windows\Scripts\Activate.ps1
pip install -r requirements.txt
python app.pyWindows desktop builds are always AMD64/x64, including on Windows-on-ARM or
Parallels. The build script rejects ARM64 Python and, when it can't find a usable
AMD64 interpreter, installs AMD64 Python 3.12 under
%LOCALAPPDATA%\mindinguflac\python312-amd64 (falling back to the AMD64
pythonx64 NuGet package under %LOCALAPPDATA%\mindinguflac\python312-amd64-nuget
if the python.org installer exits without creating the target interpreter).
Discovery is deliberately minimal: it uses MINDINGUFLAC_PYTHON if set, then the
hardcoded user install at
C:\Users\<you>\AppData\Local\Programs\Python\Python312\python.exe, then the
installer-target paths.
Windows-on-ARM / Parallels gotcha: do not verify the architecture with
platform.machine()— an AMD64 Python running under x64 emulation printsARM64there (it reports the native host arch viaPROCESSOR_ARCHITEW6432), even though the interpreter is genuinely x64. The build script ignoresplatform.machine()and reads the real architecture from thepython.exePE header instead. To check arch yourself, look at the installed-apps entry (e.g. "Python 3.12.8 (64-bit)") rather thanplatform.machine().
The interpreter must also be a full Python install with venv available. A
runtime/embedded folder that only has python.exe, DLLs, and no standard
library can exist on disk but is not usable for the Windows build.
Open your browser to http://127.0.0.1:8888.
The torrent engine runs an AI advisor in parallel with normal torrent probing by default (powered by DuckDuckGo's free Duck.ai chat API). It is advisory only: the deterministic filters, metadata checks, and libtorrent byte-progress race still decide what downloads.
The AI receives the top 20 search results based on the local scoring algorithm. It evaluates their titles and metadata and returns a sorted list of the IDs it considers to be clean music matches. The torrent engine then attempts to download the AI's ranked candidates in the order provided (up to however many the AI selected), before falling back to the remaining unscored candidates.
Note on DuckDuckGo Anti-Bot: The built-in proxy bypasses DuckDuckGo's anti-bot challenges by using a long-running Playwright browser worker. This worker uses a real Chromium instance (headless) to handle the Duck.ai frontend and challenge flow, ensuring more reliable access than static header spoofing. On first run, the app automatically attempts to fetch the necessary browser binaries if they are missing.
To disable the advisor, explicitly set MINDINGUFLAC_AI_RERANK_PROVIDER to none:
export MINDINGUFLAC_AI_RERANK_PROVIDER=none
./run.shAlternative OpenAI-compatible local/provider endpoint:
export MINDINGUFLAC_AI_RERANK_URL="http://127.0.0.1:1234/v1/chat/completions"
export MINDINGUFLAC_AI_RERANK_MODEL="your-model"
./run.shIf the endpoint, network, or service limit is unavailable, the torrent job continues with the local scoring and fallback path.
- Spotify-style track suggestions and playlist-end recommendations
- Backend: Python (BaseHTTPServer/Threading) optimized for low-latency API responses.
- Frontend: Single Page Application (SPA) using Vanilla JavaScript and CSS variables for theme management.
- Desktop Wrapper: Powered by
pywebview, providing a native app feel while maintaining web-standard flexibility. - Audio Engine: Custom native audio manager for Windows and macOS, bypassing browser limitations for high-bitrate playback.
- Native Output Handoff: On macOS app-only output devices, active browser streaming is paused when a native device is selected and no completed cache file exists. The player remembers the current position and starts native output from that position when the cache file finishes.
Disclaimer: Mindinguflac is a research-oriented meta-search tool. Users are responsible for ensuring that their use of the platform and any media they index complies with local copyright laws and the terms of service of the metadata providers.