#lang scribble/manual

@(require (for-label racket/base
                     (file "../main.rkt")))

@title{audio-library-manager}
@author{Hans Dijkema}

The @racketmodname[audio-library-manager] package contains command-line tools for
maintaining audio library trees.

@section{Administration files}

The managers use these files below the source directory:

@itemlist[
 @item{@filepath{.music-info.db}: keystore database with file state.}
 @item{@filepath{.flac-48khz-manager.ini}: configuration.}
 @item{@filepath{.flac-48khz-manager.log}: log file.}]

The FLAC-to-Opus manager uses a separate key prefix in @filepath{.music-info.db},
so it can share the same database with the 48 kHz manager.

@section{FLAC 48 kHz manager}

The tool @filepath{flac-48khz-manager.rkt} keeps a FLAC tree at a maximum sample
rate of 48 kHz. Files with a higher sample rate are converted synchronously by the batch process. The conversion path uses
@racketmodname[racket-audio/audio-encoder] dynamically, so the manager module can
still be compiled on systems where the native audio libraries are not available.

Run the manager as:

@verbatim{racket flac-48khz-manager.rkt <base-directory>}

When a FLAC file has no embedded picture and its directory contains
@filepath{cover.jpg}, @filepath{folder.jpg}, @filepath{cover.png} or
@filepath{folder.png}, the manager embeds that image as front-cover picture
before fingerprinting and conversion.

The manager only processes @filepath{.flac} files; @filepath{.mp3} files and
other sidecar files are ignored by this command.

@section{FLAC to Opus mirror manager}

The tool @filepath{flac2opus-manager.rkt} mirrors a source directory to a target
directory. FLAC files are converted to Ogg Opus files with extension
@filepath{.opus}. Other regular files are copied unchanged, preserving their
relative path and modification time. This includes sidecar files such as
@filepath{booklet.pdf}, @filepath{cover.jpg}, cue sheets and text files.

Run the manager as:

@verbatim{racket flac2opus-manager.rkt <source-directory> <target-directory>}

The default Opus bitrate is 224 kbps. A different bitrate can be selected with:

@verbatim{racket flac2opus-manager.rkt --kbps 192 <source-directory> <target-directory>}

Metadata is copied through @racketmodname[racket-audio/taglib] and
@racketmodname[racket-audio/audio-encoder]. TagLib properties and embedded
pictures are transferred to the Opus file. The manager also writes a
@tt{FLAC2OPUS} comment indicating that the file was converted by the manager.

When a source file disappears, the corresponding target file is removed on the
next run. The manager does not mirror its own root-level administration files.
Paths are handled as Racket paths instead of by splitting on @litchar{/}, so
Windows absolute paths and UNC paths are left to the platform path
implementation.

@section{Configuration}

The configuration file is created automatically when it does not exist. The managers read it directly as sections and keys through @racketmodname[simple-ini]; there is no separate configuration struct layered on top of the ini model. The main settings are:

@verbatim{
[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]"
}

When mail is enabled, the report is sent as HTML. The message contains the
summary counters and the error table; it does not dump the full log by default.

@section{Change detection}

The default @tt{change-detection} mode is @tt{flac-taglib}. Unchanged files are
first skipped by comparing @tt{size} and @tt{mtime} from the keystore state. New
or visibly changed files get a semantic fingerprint made from FLAC STREAMINFO
and TagLib metadata. The FLAC part includes the STREAMINFO audio MD5 signature;
the TagLib part includes properties and an embedded-picture content hash.

For non-FLAC files mirrored by @filepath{flac2opus-manager.rkt}, the default
signature is @tt{mtime} plus @tt{size}. A full-file hash remains available by
setting @tt{change-detection="hash"}.

@section{Library API}

@defproc[(manage-flac-tree
          [base-directory path-string?]
          [#:inspect-flac-proc inspect-flac-proc procedure? inspect-flac-sample-rate]
          [#:fingerprint-proc fingerprint-proc procedure? flac-taglib-fingerprint]
          [#:convert-proc convert-proc procedure? convert-flac-to-target-in-place])
         list?]{
Scans @racket[base-directory], updates the keystore state, converts FLAC files
above the configured maximum sample rate, sends the optional HTML mail report,
and returns a summary association list.

The keyword arguments are intended for tests and dry integration work. In normal
use, the default inspector, fingerprint function and converter are used.}

@defproc[(manage-flac2opus-tree
          [source-directory path-string?]
          [target-directory path-string?]
          [#:kbps kbps exact-positive-integer? 224]
          [#:convert-proc convert-proc procedure? convert-flac-to-opus])
         list?]{
Mirrors @racket[source-directory] to @racket[target-directory]. FLAC files are
converted to Opus at @racket[kbps] kbps; all other regular files are copied.
The state is stored in the source directory's @filepath{.music-info.db} using a
separate @tt{flac2opus} prefix. Keystore keys and stored target paths use
normalized paths relative to the configured source or target base directory;
absolute mount points are not stored and separators are always @tt{/}.}

@defproc[(summary->lines [summary list?]) (listof string?)]{
Formats the summary association list as display lines.}