# 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:

```sh
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:

```sh
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:

```racket
(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.

```ini
[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.