TrackFlow

A desktop DJ track analysis, preview, and download tool built with PyQt6.
Analyze BPM, key, and energy across your library — then preview, loop, cue, find similar tracks,
organize playlists, and auto-download new music from YouTube, Apple Music, Spotify, Shazam, and SoulSeek.

---

Features

📊 Analysis Engine

• BPM detection via onset-based autocorrelation on a mel spectrogram — analyzes first 60s, pure NumPy/SciPy (no librosa/numba overhead)
• Musical key detection using chroma-based Krumhansl–Schmuckler profiles across all 24 major/minor keys, returned in standard, Camelot wheel, and Open Key notation
• Energy level scoring (1–10) from full-track RMS via 65 536-sample chunked reads — constant memory usage regardless of file size
• Genre detection using Essentia's Discogs-EffNet model (400 Discogs genre/style labels) via ONNX Runtime — no TensorFlow required, works on Windows. Top genres appear in the library table and cache per-track
• Audio metadata extraction (format, bitrate, sample rate, duration, file size)
• Batch analysis with background thread pool and JSON cache (skips already-analyzed tracks)

🔍 Track Similarity

• Find the 25 most similar tracks in your library to any loaded track
• 32-dimensional feature vectors: 20 MFCC coefficients (timbral texture, spectral envelope) + 12 chroma means (pitch-class energy across the 12 semitones)
• Cosine similarity — measures the angle between feature vectors, not their magnitude, so loudness differences between tracks don't affect the score. Displayed as 0–100% match
• Results in a dedicated Similar tab with BPM, key, and score; double-click to load

🌊 Waveform & Visualization

• Frequency-colored filled waveform: red = bass (0–200 Hz), amber = mids (200–4000 Hz), cyan = highs (4000+ Hz)
• Overview panel (40px) — full-track minimap, click anywhere to seek
• Main panel (120px) — auto-zooms to a ±15s window around the playhead for beat-level precision
• Beat and bar grid overlay synced to detected BPM
• Hot cue tick marks and loop region overlay rendered on both panels
• Click or drag-to-seek (seeks on mouse release, no audio artifacts)

🎛️ DJ Controls

• 6 color-coded hot cues with persistence across sessions (keys 1–6, Shift+1–6 to clear)
• Seamless A–B looping — loop region decoded into RAM and played via pygame.Sound(loops=-1), eliminating the pop/gap found in timer-based approaches
• Bar-snap loop presets: ½, 1, 2, 4, 8 bars from nearest beat
• Loop in/out controls (I / O keys) with live overlay on both waveform panels
• Volume slider, play/pause, and keyboard-driven seeking

📚 Library & Playlists

• Load individual tracks or entire folders (recursive scan); multi-file select supported
• Sortable columns: track name, BPM, key (Camelot order), energy level
• Low-bitrate flag on tracks below 320 kbps
• Search/filter across library
• Create, delete, and export playlists (copy tracks to folder)
• Multi-select drag-and-drop from library to playlist
• Multi-delete from playlist; sort playlist by BPM or key

⬇️ Downloads (Phase 2)

YouTube

• Paste any YouTube video or playlist URL into the Queue tab
• Downloads as MP3 320 kbps (requires ffmpeg — see Prerequisites). Falls back to native M4A if ffmpeg is missing.
• Parallel downloads — several tracks download at once (default 3, adjustable 1-8 in the Queue tab). Most of the per-track time is metadata lookup and MP3 encoding rather than the transfer itself, so this measured ~1.8x faster at 2 workers and ~2.3x at 4 on a 5-track batch. Past 4 the gain flattens while YouTube rate-limiting risk rises, so 3-4 is the sweet spot.
• Per-row progress indicator with format badge; Import button appears on completion
• ⏹ Stop cancels all active and pending queue items at once
• Per-row ✕ button and ✕ Remove Selected to clear finished or unwanted entries
• Bulk Import Selected adds finished tracks to the library and auto-triggers analysis

Playlist Subscriptions

Subscribe to YouTube, Apple Music, or Spotify playlists, then sync when you want new tracks. Syncing on every launch is available but off by default (see Sync on startup below).

Source	How it works
YouTube Playlist	yt-dlp extract_flat fetches the playlist index; new video IDs are downloaded directly
Apple Music URL	Paste any public music.apple.com playlist URL — TrackFlow extracts the anonymous JWT developer token from Apple's web-player JS bundle and calls the Apple Music catalog API to list tracks
iTunes XML	Parses the iTunes Music Library.xml written by Apple Music for Windows (uses Python stdlib plistlib) — works for private/personal playlists not accessible via URL
Spotify	Paste any public open.spotify.com/playlist/... URL — TrackFlow scrapes embedded track metadata from the playlist page (no API key needed)
Shazam	Shazam syncs to Apple Music — enable the Apple Music integration and add the "Shazam Library" playlist via iTunes XML

For Apple Music, Spotify, and Shazam tracks, TrackFlow searches YouTube using three query variants (Artist - Title, Title Artist, Artist Title official audio) and downloads the best match. Tracks not found on YouTube are shown in a Not Found table for manual retry.

Age-restricted videos: set 🍪 Cookies in the Queue tab — pick your browser or a cookies.txt file — and TrackFlow uses your logged-in YouTube session to download them. The choice is verified as soon as you make it, so an unusable source is reported immediately. Chrome-family browsers lock their cookie database while running (close the browser completely) and recent versions encrypt it in ways yt-dlp cannot always read; a cookies.txt file exported with a browser extension always works. If cookies can't be read, downloads still proceed without them — only age-restricted videos fail. Errored rows can be re-queued with ↻ Retry Errors.

"Sign in to confirm you're not a bot": YouTube applies this to your whole connection once request volume looks automated, so it affects every download, not one track. TrackFlow detects it and pauses the queue rather than failing everything and prolonging the block. Set 🍪 Cookies to a cookies.txt file, give it time to clear, then click ↻ Retry Errors. Lowering Parallel downloads reduces the chance of triggering it.

HTTP 403 errors: usually caused by a stale yt-dlp. Update with pip install -U yt-dlp (source) or grab the latest TrackFlow release — every build ships a fresh yt-dlp.

Sync state is persisted in data/sync_state.json. A track is recorded as synced only once its file actually lands on disk, so an interrupted playlist resumes where it stopped — the next sync fetches just the tracks that never downloaded, rather than starting the playlist over. If a downloaded file is later deleted, that track is fetched again too. Use 🗑 Clear Cache next to any subscription to reset its sync history (useful when testing or re-downloading a playlist).

SoulSeek Watcher

• Point TrackFlow at your SoulSeek "completed downloads" folder
• watchdog monitors the folder in real time (catches both new file creation and SoulSeek's .tmp → final filename rename-on-completion)
• Each detected audio file appears in the watcher table with an Import button

---

Keyboard Shortcuts

Key	Action
Space	Play / Pause
← / →	Seek ±5 seconds
Shift+← / →	Seek ±30 seconds
I	Set loop in-point (A)
O	Set loop out-point (B)
L	Toggle loop on / off
1–6	Jump to hot cue (sets if empty)
Shift+1–6	Clear hot cue
Enter	Play selected track (library or playlist)
Delete	Remove selected track(s) from playlist
F1 / ?	Open help

---

Getting Started

Download (Windows)

1. Grab the latest TrackFlow.zip from the Releases page
2. Extract it somewhere (e.g. C:\TrackFlow\)
3. Install ffmpeg (required — see below)
4. Run TrackFlow.exe from the extracted folder

Distribute/keep the entire extracted folder, not just the .exe — the bundled DLLs and assets sit alongside it.

ffmpeg (required)

TrackFlow needs ffmpeg to produce MP3 320 kbps files. It's auto-detected from your PATH and common install locations.

• Windows: Download from gyan.dev → extract → add bin/ folder to PATH, or use winget install ffmpeg / choco install ffmpeg
• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg (Debian/Ubuntu) or equivalent

⚠️ Without ffmpeg, downloads fall back to native M4A — works but has lower compatibility with some DJ software.

Building from Source

Prerequisites

• Python 3.11+
• Conda (recommended) or pip
• ffmpeg (see above)

Installation

# Clone the repository
git clone https://github.com/ashaydave/TrackFlow.git
cd TrackFlow

# Create conda environment
conda create -n dj-analyzer python=3.11 -y
conda activate dj-analyzer

# Install dependencies
pip install PyQt6 numpy scipy soundfile soxr mutagen pygame yt-dlp watchdog onnxruntime

Genre detection requires onnxruntime (included above). The Discogs-EffNet model (~37 MB) downloads automatically on first use. If onnxruntime is unavailable the rest of the app works normally — the Genre column simply stays empty.

Run

python main.py

Build Executable (Windows)

build.bat
# Output: dist\TrackFlow\TrackFlow.exe

Requires PyInstaller (pip install pyinstaller) and the conda environment above. See build.bat for details.

---

Using the Downloads Tab

YouTube — single track or playlist

1. Click the ⬇ Downloads tab at the top of the window
2. Set your Save to folder (your DJ library folder, or a staging area)
3. Paste a YouTube URL (video or playlist) into the URL bar and click + Add
4. Click ▶ Download All — progress updates per row; the format badge shows MP3 or M4A
5. When a row shows ✓ Done, click ⬆ Import to add it to the library and trigger analysis
6. Use ⏹ Stop to cancel all downloads at once, or ✕ on individual rows to remove them

Playlist Subscriptions

1. Go to ⬇ Downloads → Subscriptions
2. Pick a source in the dropdown (YouTube / Spotify / Apple Music), paste the playlist URL, and click + Add — the source is auto-detected from the URL, so pasting any supported link just works
3. iTunes XML / Shazam: choose iTunes XML / Shazam in the dropdown and click + Add to pick a playlist by name from your local iTunes Music Library.xml (e.g. Shazam Library)
4. Every playlist row in the table has its own controls:
   • 📁 Folder — give this playlist its own download folder ("Default" uses the Queue tab's Save-to folder)
   • 🔄 Sync — sync just this playlist
   • Reset — clear just this playlist's sync history, so its tracks re-queue on the next sync (other playlists untouched, no files deleted)
   • Remove — unsubscribe from this playlist (downloaded files are kept)
5. Click 🔄 Sync All to check every playlist. Automatic syncing on launch is off by default — tick Sync on startup next to Sync All to enable it. It is opt-in because a sync can queue hundreds of downloads, and a large burst of requests risks YouTube rate-limiting
6. 🗑 Clear Cache (next to Sync All) resets the sync history for every playlist at once — it asks for confirmation and reports how many tracks would re-queue, since that can mean a very large batch of downloads. To reset one playlist, use Reset on its row instead.
7. New tracks appear in the Queue tab; click Import Selected to bring them into the library

SoulSeek Watcher

1. Go to ⬇ Downloads → SoulSeek Watcher
2. Click Browse and navigate to your SoulSeek "Finished Downloads" folder
3. Click ▶ Start Watching — the status indicator turns green
4. As SoulSeek completes downloads, files appear in the table automatically
5. Click ⬆ Import on any row (or Import All New) to add files to the library

---

Project Structure

TrackFlow/
├── main.py                    # Application entry point
├── paths.py                   # Path resolution (dev + frozen exe)
├── build.bat                  # One-click Windows build script
├── TrackFlow.spec             # PyInstaller spec (includes all Phase 2 modules)
├── analyzer/
│   ├── audio_analyzer.py      # BPM / key / energy / MFCC / chroma engine
│   ├── batch_analyzer.py      # Background batch analysis + JSON cache
│   ├── genre_detector.py      # Discogs-EffNet ONNX genre detection (400 styles)
│   └── similarity.py          # 32-dim cosine similarity search
├── downloader/
│   ├── yt_handler.py          # DownloadWorker(QThread) — yt-dlp wrapper,
│   │                          #   ffmpeg auto-detection, MP3/M4A format selection
│   ├── watcher.py             # FolderWatcher(QObject) — watchdog wrapper
│   └── playlist_sync.py       # YouTubePlaylistSource, AppleMusicSource,
│                              #   AppleMusicURLSource, SpotifyPlaylistSource,
│                              #   PlaylistSyncWorker, search_youtube()
├── ui/
│   ├── main_window.py         # Main window, Library tab, all DJ controls
│   ├── downloads_tab.py       # Downloads tab (Queue / Subscriptions / SoulSeek)
│   ├── waveform_dj.py         # Frequency-colored waveform widget
│   ├── audio_player.py        # Pygame player (STOPPED/PLAYING/PAUSED/LOOP_PLAYING)
│   └── styles.py              # Centralized cyberpunk QSS stylesheet
├── assets/
│   ├── logo.svg               # Application logo (vector)
│   ├── logo_32.png            # Toolbar icon
│   └── logo_256.png           # Window / tray icon
├── data/
│   ├── cache/                 # Analysis cache (JSON, keyed by path+mtime+size)
│   ├── hot_cues.json          # Saved hot cue positions per track
│   ├── playlists.json         # Saved playlists
│   ├── sync_state.json        # Last-known playlist state (prevents re-downloads)
│   └── downloads_config.json  # Output folder, watch dir, subscriptions
└── tests/
    ├── test_analyzer_speed.py
    ├── test_batch_analyzer.py
    ├── test_similarity.py
    ├── test_genre.py          # 17 tests — genre cache, model manifest, label cleaning,
    │                          #   format_genres edge cases, onnxruntime availability
    └── test_downloads.py      # FolderWatcher, AppleMusicSource, AppleMusicURLSource,
                               #   sync state, yt_handler imports

---

Built With

This project was built entirely with Claude by Anthropic — from the analysis engine and UI layout to the waveform rendering, seamless looping, similarity search, and the full playlist-sync and download pipeline.

License

This project is open source and available under the MIT License.