audio-library-manager

Tools for maintaining audio library trees.

The package currently contains two managers:

• flac-48khz-manager.rkt: keeps a FLAC tree at a maximum sample rate of 48 kHz.
• flac2opus-manager.rkt: mirrors a FLAC source tree to an Opus target tree.

Both managers use the same administration files in the source tree:

• .music-info.db: keystore state database
• .flac-48khz-manager.ini: configuration
• .flac-48khz-manager.log: log file

The flac2opus state uses its own key prefix in .music-info.db, so it can share the same database with the 48 kHz manager without mixing state entries. State keys use only normalized paths relative to the configured source/base directory: absolute mount points are not stored, and path separators are always /.

FLAC 48 kHz manager

The command keeps a FLAC directory tree at a maximum sample rate of 48 kHz. Files above the configured threshold are converted in place by a direct call to racket-audio/audio-encoder. The conversion code is deliberately synchronous: no places, channels or worker protocol are used.

Run:

racket flac-48khz-manager.rkt /path/to/flac-tree

When a FLAC file has no embedded picture and the same directory contains one of cover.jpg, folder.jpg, cover.png or folder.png, the manager embeds that image as front-cover picture before fingerprinting/conversion. This keeps FLAC artwork consistent before a later Opus mirror is made.

The flac-48khz-manager scanner only processes .flac files. Other files such as .mp3, booklets and cover images are ignored by this manager.

FLAC to Opus mirror manager

The command mirrors a source directory to a target directory. FLAC files are converted to Ogg Opus files with extension .opus; all other regular files are copied unchanged, preserving their relative path and modification time. Examples include booklet.pdf, cover.jpg, folder.png, cue sheets, text files and other sidecar files.

Run:

racket flac2opus-manager.rkt /path/to/flac-tree /path/to/opus-tree
racket flac2opus-manager.rkt --kbps 192 /path/to/flac-tree /path/to/opus-tree

The default Opus bitrate is 224 kbps. The library API exposes the same setting as keyword argument:

(manage-flac2opus-tree source-directory target-directory #:kbps 224)

Metadata is copied through racket-audio/taglib and racket-audio/audio-encoder: ordinary TagLib properties are transferred, embedded pictures are transferred, and an additional FLAC2OPUS comment is written to mark the conversion. The batch converter itself remains a simple synchronous function call.

The manager removes target files that belonged to source files which disappeared since the previous run. It deliberately does not mirror its own root-level administration files: .music-info.db, .flac-48khz-manager.ini and .flac-48khz-manager.log.

Paths are handled as Racket paths rather than by splitting on /, so Windows absolute paths and UNC paths such as \\panderleou\music are preserved by the platform path implementation.

Configuration

Important configuration keys are created automatically in .flac-48khz-manager.ini. The same file is used by both managers. The implementation now reads this file as a simple-ini value directly; there is no separate configuration struct layered on top of the ini model.

[manager]
max-sample-rate=48000
hash-algorithm="sha256"
change-detection="flac-taglib"
dry-run=#f
display-log=#t
log-file=".flac-48khz-manager.log"
compression-level=5

[opus-manager]
log-file=".flac2opus-manager.log"

[mail]
enabled=#f
send-on-success=#f
send-on-error=#t
host=""
port=25
tls=#f
username=""
password=""
from=""
to=""
cc=""
bcc=""
subject-prefix="[flac-48khz-manager]"

SMTP reports are HTML and summarize counters and errors.

Change detection

The default change detection is flac-taglib:

1. unchanged files are skipped with a cheap size + mtime comparison;
2. new or visibly changed files get a semantic fingerprint;
3. for FLAC files, the semantic fingerprint consists of FLAC STREAMINFO data, including the FLAC audio MD5 signature, plus TagLib properties and embedded picture metadata/content hash;
4. for non-FLAC files in the Opus mirror, the default is mtime + size;
5. full-file hashing is available by setting change-detection="hash".

This avoids reading every complete audio file during a normal run, which matters on Windows and network shares.

FLAC files with ID3v2 prefixes

Version 0.1.4 accepts native FLAC files that start directly with fLaC, and FLAC files with an ID3v2 tag before the fLaC marker. The latter occurs in some libraries and is accepted by players such as foobar2000/libFLAC. The fast STREAMINFO reader skips the ID3v2 prefix before reading the FLAC metadata.