opus conversie

scribblings/audio-library-manager.scrbl

@@ -9,11 +9,23 @@
 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 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
+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.
 
@@ -21,12 +33,40 @@ Run the manager as:
 
 @verbatim{racket flac-48khz-manager.rkt <base-directory>}
 
-The manager creates these files below @filepath{<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.
 
-@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 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}
 
@@ -37,6 +77,7 @@ settings are:
 [manager]
 max-sample-rate=48000
 hash-algorithm="sha256"
+change-detection="flac-taglib"
 dry-run=#f
 display-log=#t
 log-file=".flac-48khz-manager.log"
@@ -61,11 +102,24 @@ 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
@@ -73,7 +127,18 @@ 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.}
+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.}
 
 @defproc[(summary->lines [summary list?]) (listof string?)]{
 Formats the summary association list as display lines.}