Connect and manage your music library

Use CONNECT MUSIC FOLDER in the left sidebar. Select the folder containing your music. It can be the included MUSIC folder or another folder on your computer or USB drive. Subfolders are scanned too. If you choose the app folder that contains MUSIC, BLACKBOX can also recognise it as the portable drive root when the other folders are present.

1. Choose CONNECT MUSIC FOLDER and approve the browser's folder-access prompt.
2. Choose RESCAN LIBRARY after adding, removing or renaming files.
3. If the normal folder chooser does not open, try BROWSER COMPATIBILITY PICKER. This fallback lets you select files from a folder; it may need to be repeated later because it does not offer the same persistent folder handle.

The default formats listed in config.json are MP3, WAV, M4A, WMA, AAC and FLAC. Browser codec support varies; WMA and some M4A/FLAC files may be indexed but still fail to decode in a particular browser. Track tags supply title, artist and album information when available. If tags are missing, BLACKBOX uses the filename as a fallback; a filename such as Artist - Track Title.mp3 is easier to identify. Use a track's context menu to edit displayed title, artist, album, genre, year, rating, custom tags, per-track gain or cover art. These changes are stored as BLACKBOX metadata and do not rewrite your original audio file.

Playback, queue and search

Select a track row to play it. The playback bar stays available while you move between sections. Use the transport controls to play or pause, move to the previous or next track, seek, change volume, shuffle and cycle repeat modes.

• Queue: add tracks to the queue, move them up or down, drag rows to reorder, and clear upcoming tracks from the Queue view.
• Search: use the Search section or press / to search the indexed local library.
• Smart Mix: create a varied selection from tracks already in your library. Smart shuffle and similar-track suggestions also use your local collection and listening data. The Duplicate Finder compares file size and fingerprints to identify possible duplicate candidates; it does not delete files. The Missing Artwork Scan identifies tracks without a detected cover.
• Recently Played and Statistics: review listening history, play counts, listening-time estimates, formats and top artists.

Favorites, playlists and smart collections

Mark a track as a favorite from its row or the Now Playing controls. Open Favorites to see liked tracks. Use Playlists to create your own lists and add or remove tracks.

Smart playlists are rule-based lists. Depending on the fields available in your library, you can build rules around artist, album, genre, tags, year, rating, duration, play count or favorite status. Their contents update as matching metadata and listening data change.

Smart Collections provide ready-made views such as discovery and other local listening groupings. They do not search the internet or add music you do not already have.

Now Playing, artwork and lyrics

The Now Playing view shows the current track, artwork, progress, playback controls, audio visualizer, lyrics panel and up-next preview. Track Actions can also expose metadata editing and related library tools.

Local lyrics: place an .lrc or .txt file next to the audio track and give it the same base filename. For example, Song.mp3 can use Song.lrc. LRC files can contain timestamps for synchronised lines; TXT files are displayed as plain text.

Get Lyrics: when you explicitly press the Get Lyrics control, BLACKBOX can request a match from LRCLIB. This is the app's optional internet request. Lyrics already stored locally or in its cache can work offline. A match is not guaranteed.

Studio, Void, Deck, Record and Mini

Visualizers, themes and Visualizer Studio Pro

BLACKBOX includes six selectable visualizer modes:

Choose a mode with the numbered controls or keyboard shortcuts. In Tools & Colors, change among the 13 themes and four color variants. Disco effects have separate styles and can be switched off.

Visualizer Studio Pro includes glow, smoothing and quality controls, custom palettes and saved looks. Use Performance quality if Trap Ring is too demanding for your computer. A saved look stores the visual settings so you can apply them again.

Equalizer and audio controls

• 10-band EQ: choose a preset, adjust individual frequency bands and save your own presets.
• Level matching: uses embedded ReplayGain values where available, otherwise an RMS estimate. It is not calibrated LUFS mastering.
• Stereo width: optional mid-side widening. 100% is unchanged. This is not Dolby Atmos or object-based surround.
• Output device: refresh the device list and apply a device when your browser supports audio-output routing. Device listing alone does not guarantee routing support.
• Playback speed: use the speed control or [ and ] to step through supported speeds.

Audio processing applies to tracks played inside BLACKBOX. It does not process sound from other apps or the rest of Windows.

Listening Profiles and Track Moments

Listening Profiles save a named snapshot of supported preferences, including the workspace, theme, visualizer, EQ and playback settings. Create a profile when your current setup is the way you like it; apply it later to restore that combination. Profiles can be renamed, updated and deleted.

Track Moments save a timestamp and optional note against a track. Use them to mark a favorite passage, a point to revisit or a section you want to remember. Select a saved moment to jump back to its position in the track.

Backups and using BLACKBOX on USB

BLACKBOX stores preferences and library data in the browser profile. When you connect a portable drive root, it can also mirror supported data files into the drive's Data folder.

1. In Settings, choose CONNECT DRIVE ROOT.
2. Select the main BLACKBOX folder that contains MUSIC, Playlists and Data. Do not select only the Data folder.
3. Grant read/write permission when requested. Check the status messages if a portable save fails.
4. Use EXPORT EVERYTHING ZIP regularly and store a copy somewhere separate from the USB drive.
5. On another computer, copy the project rather than moving your only copy, launch it, reconnect the folders and grant permission again. Use RESTORE / MERGE BACKUP if you need to restore data.

Getting music files onto your computer

BLACKBOX is a local player, not a music-download service. Add audio files that you own or are allowed to download: artist-provided downloads, music with a licence that permits downloading, your own recordings, or public-domain recordings.

Using spotDL with a Spotify playlist

spotDL uses Spotify links as track and playlist references, then searches supported audio sources (the standard setup uses YouTube) for matching recordings. A Spotify playlist being public does not grant permission to download the recordings in it. Only use this workflow for tracks you are legally authorised to download and keep. Respect copyright and the terms that apply to the source.

1. Install prerequisites. Follow the current spotDL installation guide. Its Windows instructions list Python 3.11–3.15, FFmpeg 4.2 or newer and the Visual C++ 2019 Redistributable. Select the Python option that adds it to PATH.
2. Open Command Prompt. Press Win + R, type cmd and press Enter.
3. Install or update spotDL. Run py -m pip install --upgrade spotdl. If Windows cannot find py, fix the Python installation/PATH first using the official Python instructions. If the spotdl command itself is not recognised, check the PATH troubleshooting page or use the Python module form shown in the official usage guide.
4. Install its FFmpeg helper. Run spotdl --download-ffmpeg. The spotDL documentation also recommends Deno for some YouTube downloads; install it with spotdl --download-deno when needed.
5. Prepare your destination. In File Explorer, open the folder where you want downloads saved. Click the address bar, type cmd and press Enter. Command Prompt opens in that folder.
6. Copy the playlist URL. In Spotify, use Share to copy the playlist link. Confirm you have permission to download the recordings you intend to use.
7. Run the playlist command. Replace the example URL with your own permitted playlist link:

spotdl download "YOUR_COPIED_SPOTIFY_PLAYLIST_URL"

spotDL saves the files in the working folder by default. Check the output, correct any mismatched tracks, then move or copy the authorised audio files into your BLACKBOX music folder and press RESCAN LIBRARY.

Keyboard shortcuts

Shortcuts work when you are not typing into a text field. Some shortcuts change the active visualizer or view immediately.

Troubleshooting