#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{FLAC 48 kHz manager}

The first tool is @filepath{flac-48khz-manager.rkt}. It keeps a FLAC tree at a
maximum sample rate of 48 kHz. Files with a higher sample rate are converted in
place through a worker place. 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>}

The manager creates these files below @filepath{<base-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.}]

@section{Configuration}

The configuration file is created automatically when it does not exist. The main
settings are:

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

[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{Library API}

@defproc[(manage-flac-tree
          [base-directory path-string?]
          [#:inspect-flac-proc inspect-flac-proc procedure? inspect-flac-sample-rate]
          [#: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 and converter are used.}

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