Documentation added.

2026-06-08 13:16:21 +02:00
parent 8e8b9a00c0
commit 5eefacacba
7 changed files with 610 additions and 35 deletions
@@ -1,14 +1,79 @@
 # racket-audio

-Integration of common audio libraries in racket.
+Integration of common audio libraries in Racket.

-## Mac OS X
+The package contains decoder, player and encoder bindings.  Playback uses the
+existing audio player modules.  Encoding is provided by `audio-encoder.rkt` with
+Opus and FLAC backends.

-Make sure you have libao, libFLAC, mpg123 and ffmpeg-full installed using brew.
+## Native dependencies

-% brew install libao
-% brew install flac
-% brew install mpg123
-% brew install ffmpeg-full
+For playback and decoding, install the native libraries used by the selected
+backends:

+- libao
+- libFLAC
+- mpg123
+- FFmpeg libraries, including libavutil, libavcodec, libavformat and
+  libswresample

+For encoding, also install:
+
+- libopusenc
+- libopus
+- libogg
+- TagLib with the C binding, usually provided as `taglib` / `taglib_c`
+
+The Opus encoder backend uses libopusenc directly.  The FLAC encoder backend
+uses libFLAC directly.  FLAC sample-rate conversion uses the existing FFmpeg
+swresample layer.
+
+## macOS
+
+Using Homebrew, install the native libraries before using the package:
+
+```sh
+brew install libao
+brew install flac
+brew install mpg123
+brew install ffmpeg
+brew install opus
+brew install libopusenc
+brew install taglib
+```
+
+Some Homebrew installations provide FFmpeg as `ffmpeg`; older local setups may
+use `ffmpeg-full`.
+
+## Encoder examples
+
+Encode to Opus:
+
+```racket
+(require "audio-encoder.rkt")
+
+(audio-encode "input.flac"
+              "output.opus"
+              (hash 'bitrate 224000
+                    'vbr? #t
+                    'complexity 10)
+              #:encoder 'opus)
+```
+
+Encode 96 kHz FLAC to 48 kHz FLAC:
+
+```racket
+(audio-encode "input-96k.flac"
+              "output-48k.flac"
+              (hash 'sample-rate 48000
+                    'bits-per-sample 24
+                    'compression-level 8)
+              #:encoder 'flac)
+```
+
+A small test wrapper is available in `encoder-test.rkt`:
+
+```sh
+racket encoder-test.rkt --encoder opus --input input.flac --output output.opus --bitrate-kbps 224
+racket encoder-test.rkt --encoder flac --input input-96k.flac --output output-48k.flac --sample-rate 48000
+```