135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
# 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 through a Racket
|
|
place. The conversion path uses `racket-audio/audio-encoder` dynamically, so the
|
|
package can still compile on systems where the native audio libraries are not
|
|
installed yet.
|
|
|
|
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 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.
|