147 lines
5.5 KiB
Racket
147 lines
5.5 KiB
Racket
#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 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>}
|
|
|
|
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 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
|
|
|
|
[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.}
|