#lang scribble/manual

@(require racket/base
          (for-label racket/base
                     racket/contract
                     racket/path
                     "../libao.rkt"))

@title{libao}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[racket-audio/libao]

This module provides a small high-level interface to an asynchronous
audio output backend. It opens a live output device or a file output,
queues audio buffers for playback, reports playback position, supports
pause and buffer clearing, and exposes a small set of validation
predicates.

The central value is an @tt{ao-handle}, created by
@racket[ao-open-live] or @racket[ao-open-file]. An @tt{ao-handle}
stores the requested playback configuration together with a native
asynchronous player handle. It also records the real bit depth accepted
by the selected libao output device.

@section{Audio handles}

@defproc[(ao-handle? [v any/c]) boolean?]{

Returns @racket[#t] if @racket[v] is an @tt{ao-handle} value, and
@racket[#f] otherwise.
}

@defproc[(ao-valid? [handle ao-handle?]) boolean?]{

Returns @racket[#t] if @racket[handle] still has a native asynchronous
player, and @racket[#f] otherwise.

A handle becomes invalid after @racket[ao-close], or when opening the
native player failed.
}

@defproc[(ao-device-bits [handle ao-handle?]) integer?]{

Returns the real bit depth of the opened output device.

This can differ from the bit depth requested with @racket[ao-open-live]
or @racket[ao-open-file]. For example, when 32-bit output is requested
but the libao driver only accepts 24-bit output, this function returns
@racket[24].
}

@section{Validation predicates}

@defproc[(ao-valid-bits? [bits any/c]) boolean?]{

Returns @racket[#t] if @racket[bits] is one of @racket[8],
@racket[16], @racket[24], or @racket[32], and @racket[#f] otherwise.
}

@defproc[(ao-valid-rate? [rate any/c]) boolean?]{

Returns @racket[#t] if @racket[rate] is one of the sample rates
accepted by this module, and @racket[#f] otherwise.

The accepted rates are:

@itemlist[
 #:style 'compact
 @item{@racket[8000], @racket[11025], @racket[16000], @racket[22050]}
 @item{@racket[44100], @racket[48000], @racket[88200], @racket[96000]}
 @item{@racket[176400], @racket[192000], @racket[352800], @racket[384000]}
]
}

@defproc[(ao-valid-channels? [channels any/c]) boolean?]{

Returns @racket[#t] if @racket[channels] is an integer greater than or
equal to @racket[1], and @racket[#f] otherwise.
}

@defproc[(ao-valid-format? [format any/c]) boolean?]{

Returns @racket[#t] if @racket[format] is one of
@racket['little-endian], @racket['big-endian], or
@racket['native-endian], and @racket[#f] otherwise.
}

@defproc[(ao-supported-music-format? [format any/c]) boolean?]{

Returns @racket[#t] if @racket[format] is one of @racket['ao] or
@racket['flac], and @racket[#f] otherwise.

The symbol does not describe an encoded audio format. It describes the
in-memory layout of the PCM buffer passed to @racket[ao-play].
@racket['ao] means interleaved PCM samples. @racket['flac] means
channel-oriented PCM samples, as produced by the FLAC decoder, which
must be converted to interleaved PCM before playback.
}

@section{Opening and closing}

@defproc[(ao-open-live [bits ao-valid-bits?]
                       [rate ao-valid-rate?]
                       [channels ao-valid-channels?]
                       [byte-format ao-valid-format?])
         ao-handle?]{

Creates an audio output handle for live playback.

This is equivalent to calling @racket[ao-open-file] with
@racket[#f] as the filename.

The handle stores the requested sample size, sample rate, channel count,
and byte format. The native backend first tries to open the device with
the requested bit depth. If that fails, it may fall back to a lower bit
depth accepted by the selected libao driver.

The requested bit depth describes the buffers supplied by the Racket
side. The real device bit depth describes the format accepted by libao
and can be inspected with @racket[ao-device-bits].

If the native player is created successfully, the returned handle is
valid. If player creation fails, the function still returns an
@tt{ao-handle}, but that handle is marked closed and is not valid
for playback.

A finalizer is registered for the handle and calls @racket[ao-close]
when the handle is reclaimed.
}

@defproc[(ao-open-file [bits ao-valid-bits?]
                       [rate ao-valid-rate?]
                       [channels ao-valid-channels?]
                       [byte-format ao-valid-format?]
                       [filename (or/c path? string? #f)])
         ao-handle?]{

Creates an audio output handle.

If @racket[filename] is @racket[#f], the default live libao output
device is opened. Otherwise the native backend opens a file output
target using the given filename.

The requested bit depth is stored in the handle and describes the input
buffers that will be queued with @racket[ao-play]. The native backend
also records the real bit depth accepted by the output device or file
backend. Use @racket[ao-device-bits] to inspect that value.
}

@defproc[(ao-close [handle ao-handle?]) void?]{

Stops playback for @racket[handle] and releases the native player
reference stored in the handle.

If the handle already has no native player, this procedure has no
effect.
}

@section{Playback}

@defproc[(ao-play [handle ao-handle?]
                  [music-id integer?]
                  [at-time-in-s number?]
                  [music-duration-s number?]
                  [buffer any/c]
                  [buf-len integer?]
                  [buf-type ao-supported-music-format?])
         void?]{

Queues audio data for asynchronous playback.

The @racket[music-id] argument identifies the music stream associated
with the buffer. The arguments @racket[at-time-in-s] and
@racket[music-duration-s] describe the position and duration, in
seconds, associated with the buffer. The arguments @racket[buffer] and
@racket[buf-len] provide the audio data and its length. The
@racket[buf-type] argument specifies the in-memory PCM layout.

The buffer description passed to the native layer is completed with the
requested sample size, sample rate, channel count, and byte format
stored in @racket[handle].

Two buffer layouts are supported:

@itemlist[
 #:style 'compact
 @item{@racket['ao]: interleaved PCM samples, for example @tt{L0 R0 L1 R1}.}
 @item{@racket['flac]: channel-oriented PCM samples, for example one channel buffer for left samples and one channel buffer for right samples.}
]

The native backend converts @racket['flac] buffers to interleaved PCM
before playback. It also converts between the requested bit depth and the
real device bit depth when needed. This makes it possible to keep decoder
output at 32-bit signed integer PCM while still playing on devices that
only accept 24-bit or 16-bit integer samples.

The queued buffer is copied by the native backend, so the caller does
not need to keep the original buffer alive after @racket[ao-play]
returns.

If @racket[handle] is not valid, this procedure raises an exception.
}

@defproc[(ao-pause [handle ao-handle?]
                   [pause boolean?])
         void?]{

Pauses or resumes asynchronous playback for @racket[handle].

A true value pauses playback. @racket[#f] resumes playback.
}

@defproc[(ao-clear-async [handle ao-handle?]) void?]{

Clears buffered asynchronous playback data for @racket[handle].
}

@section{Playback state}

@defproc[(ao-at-second [handle ao-handle?]) number?]{

Returns the current playback position, in seconds, as reported by the
native asynchronous player.
}

@defproc[(ao-at-music-id [handle ao-handle?]) integer?]{

Returns the music identifier currently reported by the native
asynchronous player.
}

@defproc[(ao-music-duration [handle ao-handle?]) number?]{

Returns the duration of the current music stream, in seconds, as
reported by the native asynchronous player.
}

@defproc[(ao-bufsize-async [handle ao-handle?]) integer?]{

Returns the current buffered size in bytes for the asynchronous player.
}

@section{Volume control}

@defproc[(ao-set-volume! [handle ao-handle?]
                         [percentage number?])
         void?]{

Sets the playback volume for @racket[handle].

If @racket[percentage] is an exact integer, it is converted to an
inexact number before it is passed to the native layer.
}

@defproc[(ao-volume [handle ao-handle?]) number?]{

Returns the current playback volume as reported by the native
asynchronous player.
}

@section{Notes}

This module is a higher-level wrapper around the asynchronous FFI layer.
It stores the playback configuration in the handle, and reuses that
configuration for each call to @racket[ao-play].

The requested bit depth and the real device bit depth are deliberately
kept separate. The requested value describes the buffers supplied by the
Racket side. The real value describes the format accepted by libao.

The module does not expose the handle fields directly. The public API
is intentionally small: create a handle, queue buffers, inspect
position and buffer state, pause or clear playback, adjust volume, and
close the handle.

A typical usage pattern is to open one live handle for a given stream
format, queue decoded buffers with @racket[ao-play], and query the
playback position with @racket[ao-at-second] while playback proceeds
asynchronously.