EDM Tracklist Web App — User Guide

1. Getting Started

• Open the web app in your browser.
• For the best experience, use a modern browser (Chrome, Firefox, Edge, Safari).

2. Uploading a Tracklist

• Click the Upload button or drag and drop your tracklist file (CSV or TXT) into the app.
• The tracklist will be processed and displayed in the main area.
• If the file is invalid, an error message will appear.
• Beatrove automatically detects and supports two tracklist formats.

📊 New CSV Format (Recommended)

Professional organized format with proper column headers:

📄 Legacy Format (Still Supported)

Dash-separated format for backward compatibility:

🔧 Format Details

• Automatic Detection: Beatrove automatically identifies which format your file uses
• Energy Levels: Optional 1-10 scale using "Energy #" format
• Record Labels: Optional field for professional music management
• File Paths: Absolute paths enable direct audio preview and M3U export
• Artwork Support: CSV format includes optional artwork path column

3. Advanced Search & Filtering

• Use the search bar to find tracks by artist, title, genre, or record label.
• Enable 🔤 Fuzzy Search for typo-tolerant searching.
• Use multiple filter dropdowns simultaneously for precise track discovery.
• All filters work together to narrow down results progressively.

Available Filters

• BPM Filter - Filter by specific tempo ranges
• Key Filter - Filter by musical key (Camelot notation)
• Genre Filter - Filter by musical genre categories
• Label Filter - Filter by record label for professional collections
• Year Search - Filter by release year or ranges (e.g., "2020-2023")
• Tag Filter - Filter by custom user-defined tags
• Energy Filter - Filter by energy level (1-10 stars)

4. Multi-Criteria Search

• Combine multiple filters simultaneously for precise track discovery.
• Each filter narrows down the results further using AND logic.
• Perfect for finding tracks with very specific characteristics.

5. Fuzzy Search (Typo-Tolerant)

• Toggle the 🔤 Fuzzy Search checkbox to enable typo-tolerant searching.
• Uses advanced Levenshtein distance algorithm for intelligent matching.
• Finds tracks even with spelling mistakes or variations in names.
• Automatically searches across artist, title, genre, and record label fields.

Fuzzy Search Examples

6. Favorites

• Click the star icon (☆/★) next to a track to mark it as a favorite.
• Favorites are saved in your browser and persist after refreshing.
• Click the star again to remove a track from favorites.

7. Copy Path to Clipboard

• Click the folder icon (📁) next to a track to copy the file path to your clipboard.
• Paste the path into your file manager or terminal to locate the file.

8. Audio Preview

• Click the preview icon (▶️) to listen to a track.
• The first time, you'll be prompted to select your audio files folder.
• After loading, you can preview any track whose file is present.

9. Waveform Visualization

• Select a waveform style from the "Waveform Style" dropdown in the top controls.
• When you play a track, a real-time waveform appears in the audio player popup window.
• Switch between different visualization styles during playback to compare representations.

Available Waveform Styles

10. Cover Art Display

Display album artwork alongside your tracks for a visual music library experience. Cover art helps with quick track identification and adds professional polish to your DJ setup.

🎨 Toggle Cover Art

• Click the 🎨 Cover Art button in the top controls to show/hide artwork
• Your preference is automatically saved and restored when you reload the app
• Cover art appears as 64px thumbnails next to track information

📁 Setting Up Cover Art

Directory Structure

Organize your files with this structure:

Your-Music-Folder/
├── Artist - Title - Key - BPM.flac
├── Artist - Title - Key - BPM.mp3
└── artwork/                    ← Cover art directory
    ├── Artist - Title.jpg      ← Simplified naming (new)
    ├── Artist - Title.jpeg
    ├── Artist - Title.png
    └── Artist - Title.webp

Supported Image Formats

• .jpg (JPEG) - Recommended for smaller file sizes
• .jpeg (JPEG)
• .png (Portable Network Graphics)
• .webp (WebP)

File Naming Convention

Cover art files use a simplified Artist - Title format:

• Audio File: Deadmau5 - Strobe - 8A - 126.flac
• Cover Art: artwork/Deadmau5 - Strobe.jpg

Note: Legacy full filename format is still supported for backward compatibility.

🔄 How It Works

1. Automatic Detection: When you select an audio folder, Beatrove looks for an artwork subdirectory
2. Smart Matching: For each track, searches for cover art in priority order (jpg → jpeg → png → webp)
3. Graceful Fallback: Shows clean SVG placeholder when no cover art is found
4. Performance: Images are cached for faster loading

📱 Responsive Design

• Desktop: 64px × 64px cover art
• Tablet: 56px × 56px cover art
• Mobile: 48px × 48px cover art
• Hover effects and smooth animations enhance the user experience

11. Playlists

• Create new playlists, add or remove tracks, and rename or delete playlists.
• Use the playlist dropdown to switch between playlists.
• Export playlists to save them, or import previously saved playlists.

🎵 Playlist Playback & Auto-Mix

Beatrove includes professional playlist playback features with DJ-style auto-mix crossfading for seamless transitions between tracks.

Starting Playlist Playback

1. Select any playlist from the playlist dropdown menu
2. Click the ▶️ Play All button to begin playing all tracks in sequence
3. The queue controls will appear with playback management buttons
4. Track progress is displayed (e.g., "Playing Track 4 of 156")

Queue Controls

• ▶️ Play All: Start playing all tracks in the current playlist from beginning
• ⏮️ Previous: Jump back to the previous track in the playlist
• ⏸️ Pause / ▶️ Resume: Pause or resume the currently playing track
• ⏭️ Next: Skip forward to the next track (triggers crossfade if auto-mix is enabled)
• ⏹️ Stop: Stop playlist playback completely and close the queue

🎚️ Auto-Mix Crossfade

Enable professional DJ-style crossfading between tracks for smooth, seamless transitions:

• Enable Auto-Mix: Check the "🎚️ Auto-Mix" checkbox to activate crossfading
• Adjust Duration: Use the crossfade slider to set transition time (1-15 seconds)
• Real-time Display: See the current crossfade duration (e.g., "5s")
• Automatic Transitions: Tracks automatically crossfade when songs end
• Manual Skip: Click ⏭️ Next button to trigger crossfade immediately

Crossfade Behavior

Professional DJ Workflow

• Set Preparation: Create playlists for different set sections or moods
• Smooth Transitions: Use 5-8 second crossfades for seamless DJ-style mixing
• Energy Building: Combine with energy level filtering for perfect set progression
• Quick Previewing: Skip through tracks with ⏭️ to find the perfect next track
• Live Mixing: Adjust crossfade duration in real-time to match your mixing style

12. Smart Playlists

Smart playlists automatically populate with tracks that match specific criteria. They update dynamically as your library changes, making them perfect for DJ set preparation and music organization.

Creating Smart Playlists

• Click the 🧠 Smart Playlist button in the playlist controls
• Enter a descriptive name (e.g., "High Energy House", "90s Hip-Hop", "Peak Time Techno")
• Click + Add Rule to create filtering conditions
• Configure each rule with Field, Operator, and Value(s)
• Choose between AND logic (all rules must match) or OR logic (any rule can match)
• See live preview of matching tracks count and track list
• Click Create Smart Playlist to save

Rule Configuration

• Field Options: Genre, BPM, Key, Year, Energy Level, Artist, Title, Record Label
• String Operators: "is" (exact match), "contains" (partial match), "starts with"
• Numeric Operators: "is", "greater than", "less than", "between" (range)
• Between Values: For ranges, enter two values (e.g., BPM between 128 and 132)

Smart Playlist Examples

Using Smart Playlists

• Smart playlists appear in the playlist dropdown with a 🧠 emoji
• Select a smart playlist to instantly filter tracks by its rules
• Tracks automatically update when your library changes
• Export smart playlists to save current matching tracks as text files
• Smart playlists persist across browser sessions

Professional DJ Workflow

13. Playlist Export Formats

Export your playlists in multiple professional formats for sharing, backup, or use with other DJ software and media players.

🎯 Accessing Playlist Export

• Select any playlist (regular or smart) from the playlist dropdown
• Click the Export Playlists button in the playlist controls
• Choose your preferred export format from the interactive modal

📄 TXT Format

• Content: Simple text file with track names, one per line
• Use Cases: DJ software compatibility, lightweight sharing
• Benefits: Universal support, small file size, easy to edit
• Example: Perfect for importing into Serato, Traktor, or Virtual DJ

📊 CSV Format

• Content: Complete track metadata in spreadsheet format
• Includes: Artist, Title, Key, BPM, Track Time, Year, Path, Genre, Energy Level, Record Label
• Use Cases: Data analysis, Excel processing, metadata backup
• Benefits: Proper CSV escaping, complete information, Excel-ready
• Example: Analyze your collection's BPM distribution or track energy levels

🌐 HTML Format

• Content: Professional styled web page with searchable table
• Features: Dark theme styling, energy level stars, responsive design
• Use Cases: Web sharing, printing, offline viewing
• Benefits: Beautiful presentation, interactive table, printer-friendly
• Example: Share your set list on social media or print for gigs

🎵 M3U Format

• Content: Standard playlist format for media players
• Includes: Track duration, file paths, artist/title metadata
• Use Cases: VLC, iTunes, Winamp, media player import
• Benefits: Industry standard, broad compatibility, duration info
• Example: Load your playlist directly into VLC for listening

💡 Smart Playlist Export

📋 Export Tips

• File Names: Exported files use the playlist name with proper extensions (.txt, .csv, .html, .m3u)
• Metadata Quality: Ensure your tracks have complete metadata for best export results
• File Paths: M3U exports include original file paths for direct media player access
• Energy Levels: HTML exports display energy ratings as gold stars (★★★★★☆☆☆☆☆)

14. DJ Set Tracklist Comparison

Compare DJ set tracklists against your library to identify which tracks you already have and which ones you need to acquire. This feature is perfect for DJs who want to recreate sets or build their collection based on other DJs' performances.

🎯 How to Use

1. Click the 🔄 Compare Tracklist button in the top control panel
2. Upload a DJ set tracklist file (TXT or CSV format)
3. View the comparison results showing matched and missing tracks
4. Export missing tracks or create playlists from matched tracks

📋 Supported Tracklist Formats

The comparison feature intelligently parses multiple tracklist formats:

• Timestamped Format: [00:12] Artist - Title [Label]
• Numbered Format: 1. Artist - Title
• Simple Format: Artist - Title
• Full Beatrove Format: artist - title - key - BPM.ext - time - year - path - genre - energy - label

🧠 Smart Matching Algorithm

The comparison uses advanced fuzzy matching to handle real-world variations:

• Artist Variations: Matches "Sama" with "Sama (US)" by removing parenthetical info
• Collaborations: Matches "Jazzy" with "Jazzy & Luuk van Dijk" by comparing first artists
• Reverse Collaborations: Matches "Confidence Man & DJ Seinfeld" with "DJ Seinfeld"
• Typo Tolerance: Uses Levenshtein distance for fuzzy artist and title matching
• Multiple Strategies: Tries exact match, fuzzy artist, fuzzy title, and combined approaches
• Confidence Scores: Shows match confidence percentage for transparency

📊 Results Display

The comparison results show:

• Total Tracks: Number of tracks in the DJ set
• Matched in Library: Tracks you already have (✅ green)
• Missing from Library: Tracks you need to acquire (❌ red)
• Match Rate: Percentage of tracks found in your library

💾 Export Options

• Export Missing as CSV: Creates a spreadsheet with artist, title, BPM, key, and label
• Export Missing as TXT: Creates a text file shopping list of missing tracks
• Create Playlist from Matched: Generates a playlist from tracks found in your library for easy set recreation

15. Tags

• Click the tag icon (🏷️) to add or edit tags for a track.
• Filter tracks by tag using the tag dropdown.

16. Mood & Vibe Tags

• Click the mood & vibe icon (😎) to add emotional and atmospheric tags to tracks.
• Add tags that describe the mood and vibe of your tracks for better set planning.
• Mood & vibe tags appear as orange-gradient pills with a 😎 icon to distinguish from regular tags.
• These tags are saved separately and included in data export/import.

Mood Tag Examples

Vibe Tag Examples

Professional DJ Set Planning

16. Energy Levels

• Rate tracks on a 1-10 star energy scale to organize by intensity level.
• Click the energy icon (⚡) next to any track to set its energy level.
• Choose from 1 star (low energy) to 10 stars (high energy), or clear the rating.
• Energy levels are displayed below the year as: Energy: ★★★☆☆☆☆☆☆☆ (3/10)
• Use the Energy filter dropdown to view tracks by specific energy levels.
• Energy ratings are saved automatically and persist across browser sessions.

Energy Level Guide

Use this guide to consistently rate your tracks for optimal set planning:

17. Record Labels

• Track record label information is automatically imported from CSV files.
• Record labels appear in track details between the year and energy level.
• Labels are displayed as Label: [Record Label Name] in the track information.
• View label distribution in the Library Statistics section.
• Record labels help organize tracks by their release label for professional DJ collections.
• Use the CSV format: ...year - path - genre - Energy # - Record Label to import label data.

18. Library Statistics & Charts

The Library Statistics feature provides comprehensive visual analytics of your music collection through interactive charts and detailed breakdowns.

🎯 Accessing Library Statistics

1. Click the "📊 Library Stats" button in the top control bar
2. The statistics panel will appear below your tracklist with smooth scrolling
3. Click the button again to hide the statistics panel

📊 Interactive Charts

Library Statistics displays beautiful, interactive charts powered by Chart.js:

Chart Types

• Genre Distribution - Interactive donut chart showing your top 12 genres with dynamic colors
• Musical Keys - Blue-themed bar chart displaying key distribution across your collection
• BPM Ranges - Red-themed bar chart showing tempo analysis in organized ranges (60-89, 90-109, etc.)
• Energy Levels - Yellow-themed bar chart displaying the complete 1-10 energy spectrum
• Release Years - Green-themed bar chart showing your collection timeline by year
• Record Labels - Full-width donut chart displaying your top 15 record labels

Chart Features

• Hover Tooltips - Detailed information appears when hovering over chart elements
• Theme Adaptation - Charts automatically adjust colors for light/dark mode
• Responsive Design - Charts work perfectly on desktop, tablet, and mobile devices
• Smart Filtering - Charts show meaningful data by filtering out "Unknown" entries
• Data Grouping - Smaller entries are grouped into "Others" category for cleaner visualization

📋 Layout & Organization

• Professional Grid - Clean 2-column layout for optimal chart viewing
• Full-Width Labels - Record labels section spans both columns to prevent text cutoff
• Overview Section - Total tracks and artists count at the top
• Responsive Layout - Adapts to single column on mobile devices

🔄 Fallback Support

• Graceful Degradation - If charts fail to load, data displays in list format
• Complete Information - List views include all data, including "Unknown" entries
• Browser Compatibility - Works across all modern browsers

19. Python Helper Scripts

Beatrove includes two Python utility scripts to help prepare your music collection for optimal use with the application.

📝 generate_music_list.py

Automatically scans your music directory and generates a properly formatted tracklist.csv file with professional metadata extraction.

Requirements

Install required Python packages:

Get Help

For comprehensive help and usage examples:

Usage Examples

• Basic usage: python generate_music_list.py /path/to/music/directory
• Professional CSV with cover art: python generate_music_list.py /path/to/music/directory --csv --extract-artwork
• Custom artwork directory: python generate_music_list.py /path/to/music/directory --csv --extract-artwork --artwork-dir ./covers
• Custom output location: python generate_music_list.py /path/to/music/directory -o my_tracklist.txt

Features

• Scans directories recursively for audio files (MP3, FLAC, WAV, AIFF, AAC)
• Extracts metadata from ID3 tags and file names
• Supports custom metadata fields (Energy Level, Record Label)
• 🎨 Cover Art Extraction: Extracts album artwork from MP3/FLAC files
• Handles both standardized and non-standardized filenames
• Outputs in professional CSV or legacy text format
• Validates BPM and musical key formats
• Progress reporting and detailed error handling

🎨 Cover Art Extraction

• Supported Formats: MP3 (ID3 tags) and FLAC (embedded pictures)
• Auto-Detection: Automatically detects JPEG/PNG image formats
• Clean Naming: Creates organized artwork directory with clean filenames
• CSV Integration: Adds artwork paths to CSV output for future use
• Example: --extract-artwork --artwork-dir ./album_covers

🔧 music_file_fixer.py

Standardizes your music filenames to match the format expected by Beatrove and the generator script.

Requirements

Install required Python package:

Getting Help

For complete usage information and all available options:

Usage Examples

• Dry run (preview changes): python music_file_fixer.py /path/to/music/directory
• Apply renames with confirmation: python music_file_fixer.py /path/to/music/directory --apply
• Apply all without confirmation: python music_file_fixer.py /path/to/music/directory --apply --auto-yes
• Custom defaults: python music_file_fixer.py /path/to/music/directory --default-key 1A --default-bpm 128

Features

• Analyzes existing filenames and identifies formatting issues
• Suggests standardized renames following the Artist - Title - Key - BPM.ext format
• Dry-run mode to preview changes before applying
• Extracts BPM and key information from filenames
• Uses metadata as fallback for missing information
• Preserves complex track titles with multiple parts

Recommended Workflow

1. Organize Your Files: Ensure your music files contain proper ID3 metadata
2. Fix Filenames: Run music_file_fixer.py to standardize naming
3. Generate Tracklist: Use generate_music_list.py to create your data file
4. Load in Beatrove: Place the generated file as tracklist.csv for auto-loading

20. Visualizer

• When previewing audio, visualizer bars animate in sync with the music.
• Both the top and bottom visualizers show the audio spectrum.

21. Troubleshooting

• Search not finding tracks? Try enabling Fuzzy Search for typo-tolerant matching, or check your spelling.
• Multi-criteria search too restrictive? Remove some filters to broaden results, or check if data exists for your criteria.
• Fuzzy search finding too many results? Disable Fuzzy Search for exact matching, or use additional filters to narrow down.
• Label filter empty? Make sure your tracklist includes record label information in the correct format.
• Audio preview not working? Make sure you have loaded the correct audio files folder and that filenames match the tracklist.
• Waveform not showing? Ensure you've selected a waveform style from the dropdown and that audio is playing.
• Nothing happens when clicking icons? Try refreshing the page or clearing your browser cache.
• Mood & vibe tags not saving? Check that you're clicking the Save button in the popup, and ensure your browser allows localStorage.
• Can't see mood & vibe tags? Look for orange-gradient pills with a 😎 icon - they appear below regular blue tags.
• Mood & vibe popup not appearing? Try clicking directly on the 😎 icon button next to the track.
• Favorites, playlists, or tags missing? These are stored in your browser. If you clear your browser data, they may be lost.
• Still need help? Contact the project maintainer or check the README for more info.

Enjoy managing your EDM music collection!