Library

Your music folder

Heron reads the music in HERON_MUSIC_DIR. It looks for files at startup, whenever files change, and every hour as a safety net (HERON_SCAN_INTERVAL). On network shares that do not report changes (some NFS or SMB mounts), set HERON_LIBRARY_WATCH=false and rely on the periodic scan.

Formats: MP3, AAC-LC and ALAC in M4A/MP4, FLAC, Ogg Vorbis, WAV and AIFF. HE-AAC and Opus files cannot be decoded yet.
Moves and renames are recognized: the track keeps its categories, history and analysis.
Deleted files are marked missing and come back if the file reappears. If the whole folder looks empty (an unmounted disk), nothing is marked missing.
Only heron-librarian ever writes to the library. The scanner, the analyzer and the engine mount it read-only.

Analysis

Every track is analyzed before it plays (heron-analyzer, one worker per CPU minus one, so the engine always keeps a core):

Measure	Used for
Integrated loudness (EBU R128) and true peak	Loudness normalization
Cue-in and cue-out	Silences at both ends are skipped
Crossfade point	Where the next track starts
Tempo (BPM)	Programming; can be corrected by hand
Waveform	Drawn on the track’s page with the cue points

A frame counts as silent when it is both well below the track’s own loudness and below −50 dBFS, so soft intros of loud masters are kept. Clicks and blips are ignored. A track with nothing audible is never played.

The crossfade point is where the last loud part of the track ends, between 150 ms and 2.5 s before the cue-out: a long fade-out is crossfaded at most 2.5 s before its end, and an abrupt ending still gets a short overlap.

You can drag the cue points on a track’s waveform; they become overrides for that track.

New music: the buffer zone

New files never go straight into the library. Upload them from the Buffer page (files or folders, in resumable chunks), or drop them into HERON_INCOMING_FOLDER. They move into the buffer zone (HERON_STAGING_FOLDER), where heron-librarian:

reads their tags and fingerprints them;
identifies them with AcoustID and MusicBrainz, the files of one folder together, so an album agrees on its release;
flags problems: already in the library, twice in the buffer, the same recording as a library track, unreadable, too short, unsupported.

On the Buffer page you can listen, choose another candidate release or keep a file’s own tags, edit tags, and prepare files with their categories, labels, mood and sound code. Clean files are selected already, so a clean album imports in one click.

Import writes the tags, files each track and saves the cover. You can then follow a link to the new tracks.

Filing

Imported files are filed under the library root following a layout. The default is:

{album_artist}/{album}/{disc-}{track:02} {title}.{ext}

Names are made safe on every file system. A file is never overwritten: a name already taken gets (2), (3)… Every move and tag write is journaled before the file is touched, survives a crash, and can be undone, byte for byte.

Your existing library is reorganized only when you ask, after a dry run (Review & organize, admins), or on the command line:

docker compose exec heron-librarian heron-librarian organize           # dry run
docker compose exec heron-librarian heron-librarian organize --apply   # apply, as one batch
docker compose exec heron-librarian heron-librarian undo <batch>       # undo

The trash

Deleting tracks (from Tracks or a track’s page) moves their files to a hidden trash at the library root. A deleted track leaves rotation at once, but keeps its analysis, categories and history, so restoring it from the Trash page brings it back whole. The trash is emptied after 30 days (trash_days), or at once by an admin.

Permissions

heron-librarian and heron-api run as HERON_LIBRARIAN_USER, which must own the music, incoming and buffer folders. Keep the buffer zone on the same file system as the library, so imports are renames rather than copies.