Docs

Bòcan is meant to be obvious. If you're reading this, it probably wasn't obvious enough. Sorry. We'll fix that.

Getting started

Drag Bòcan into /Applications.
Open it.
Choose Library → Add Folder… and point at your music.
Wait while it scans, fingerprints, and reads tags. Watch the spectrum analyser bounce.
Listen.

Keyboard shortcuts

Shortcut	What it does
`Space`	Play / Pause
`→`	Next track
`←`	Previous track
`↑` / `↓`	Volume up / down
`⌘F`	Search library
`⌘L`	Toggle lyrics pane
`⌘M`	Toggle mini-player
`⌘I`	Get info / tag editor
`⌘,`	Preferences
`⌘⌥S`	Sleep timer
`⌘⇧L`	Log Console

Supported formats

FLAC, ALAC, WAV, AIFF, MP3, MP2/MP1, AAC/M4A, OGG Vorbis/Speex/FLAC, Opus, WavPack, Monkey's Audio (APE), Musepack, AC-3, DTS, WMA, Wave64, RF64, Matroska/MKV/WebM, AU/SND, DSD (DSF/DFF). Bit-perfect output up to 32-bit / 384 kHz. DSD via DoP. See the full formats page for the breakdown by decoder engine and supported extensions.

Browsing by album

The Artists, Genres, and Composers views each toggle between a plain list and a grid of cover-art cards, where each card shows a 2x2 mosaic of that collection's album covers. The toggle sits next to the sort button, is mirrored in the View menu, and is remembered separately for each section.

Open a genre or composer and you get the same choice for its contents: view the songs as a flat list, or switch to a grid of that genre's or composer's albums and click straight through to any album. That preference is remembered per section too, and Songs stays the default.

Playlists

Manual playlists keep the order you arrange by dragging. Click a column header to sort a playlist for browsing; your hand-arranged order is kept underneath, and a "Playlist Order" button returns to it. Drag-to-reorder pauses while a column sort is active, so the saved order is never scrambled.

Smart playlists

Smart playlists support nested groups, all standard fields (artist, album, year, BPM, rating, play count, last played, date added, key, …), and a "limit by" clause. Sort by several keys with priorities, for example artist, then track number, then title, with an ascending or descending direction per key. In the track list you can also click a column header to re-sort on the fly. Shuffle is reproducible per session, no "shuffle" that mysteriously plays the same five tracks.

Internet radio

The Radio entry in the sidebar holds your station catalog. Three ways to fill it:

By hand: click Add Station in the Radio pane and paste a stream URL.
From a playlist URL: paste a .m3u or .pls link into Add Station's Stream or Playlist URL field and every stream inside is offered as a station, names included.
From a playlist file: import or drop a playlist and its stream entries become stations instead of missing tracks; any local entries still become a normal playlist.

While a station plays, the song title arrives live from the stream and the station name moves to the artist line; the macOS Now Playing widget follows along. The player's info button (or the i on any station row) opens the station's details: homepage, genre, description, and the stream facts as measured by the decoder: container, codec and profile (LC vs HE-AAC), sample rate, channels, and the bitrate the stream claims. Details are remembered per station after the first listen, so the sheet works offline too.

Live radio deliberately behaves differently from files: there is no seeking (live audio has no timeline), stations never scrobble, and station idents never touch your play history. If a stream drops, Bòcan reconnects on its own before giving up.

Want something to try? The Liminal Dial is a twelve-station starter: paste its URL into Add Station's Stream or Playlist URL field, or download it and drop the file on Bòcan.

Viewing logs

Bòcan has a built-in log console you can open without leaving the app. Choose Help → Log Console (⇧⌘L) or go to Settings → Diagnostics → Open Log Console.

The console shows every debug, info, warning, and error line emitted since the app started, up to a 5,000-line ring buffer. You can:

Filter by minimum log level (Trace through Fault) or by category.
Search the message text (case-insensitive, updates live).
Tail new lines automatically as they arrive, or pause to freeze the view.
Copy the visible lines to the clipboard.
Export the visible lines to a .log text file for attaching to a bug report.
Clear the view, or clear the underlying ring buffer via the overflow menu.

Capture can be turned off under Settings → Diagnostics if you need to stop the buffer from filling while the app runs unattended. Disabling capture has no effect on the system log (log stream).

Troubleshooting

Audio drops out for half a second

Almost always a sample-rate mismatch with the output device. Open Audio MIDI Setup and set the device to a fixed rate that matches most of your library (often 48 kHz or 96 kHz). Bòcan resamples on the fly when it has to, but switching rates on the device is what causes the gap.

"Bòcan can't be opened because Apple cannot check it for malicious software"

You probably downloaded an unsigned development build, or Gatekeeper's cache is stale. Right-click the app and choose Open; confirm once. After that it'll launch normally.

Library scan is slow on a NAS

Mount with SMB3 over a wired connection where possible. The first scan fingerprints every file, which means reading every byte. Subsequent scans only look at modified files.

It crashed

Logs land in ~/Library/Logs/Bocan/. Open one and zip it. File an issue on GitHub with the zip attached, and a description of what you were doing.

For the full architecture, build instructions, and how to contribute, see the README and CONTRIBUTING.md.