> For the complete documentation index, see [llms.txt](https://www.lisppad.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.lisppad.app/libraries/lisppad/audio.md).
# (lisppad audio)
Library `(lisppad audio)` implements an API for playing audio files in LispPad. Audio playback is managed through *audio player* objects. A player is created from an audio file path or a bytevector containing audio data, and exposes controls for playback, volume, stereo panning, playback rate, and looping.
## Audio Players
**(make-audio-player *****source*****)** 
\
**(make-audio-player *****source file-type*****)**\
**(make-audio-player *****source file-type rate?*****)**
Creates and returns a new *audio-player* object. *source* is either a string specifying the path of an audio file, or a bytevector containing raw audio data. *file-type* is an optional string providing a file-type hint for the audio decoder (e.g. `"mp3"`, `"aac"`, `"wav"`). If *file-type* is `#f` or omitted, the type is inferred automatically. If *rate?* is `#t`, variable-rate playback is enabled, allowing `set-audio-player-rate!` to change the playback speed. Variable-rate support must be enabled at creation time; it cannot be enabled after the player is created.
**(audio-player? *****obj*****)**
Returns `#t` if *obj* is an *audio-player* object, `#f` otherwise.
## Playback Control
**(play-audio *****player*****)** \
**(play-audio *****player time*****)**
Starts or resumes playback on *player*. If *time* is provided, it specifies a delay in seconds at which playback should begin, allowing multiple players to be synchronized. Resets any previously recorded playback completion status.
**(pause-audio *****player*****)**
Pauses playback of *player*. The current playback position is preserved; playback can be resumed with `play-audio`.
**(stop-audio *****player*****)**
Stops playback of *player* and rewinds to the beginning.
## Playback State
**(audio-player-playing? *****player*****)**
Returns `#t` if *player* is currently playing audio, `#f` otherwise.
**(audio-player-success? *****player*****)**
Returns the completion status of the most recent playback. Returns `#t` if playback finished successfully, `#f` if it was interrupted or failed, and `()` (the empty list) if no playback has finished yet or playback is still in progress.
**(audio-player-decode-error *****player*****)**
Returns the decode error that occurred during the most recent playback, or `#f` if no decode error was recorded.
**(audio-player-duration *****player*****)**
Returns the total duration of the audio loaded into *player*, in seconds, as a flonum.
**(audio-player-elapsed *****player*****)**
Returns the current playback position of *player* in seconds, as a flonum.
**(set-audio-player-elapsed! *****player time*****)**
Seeks *player* to position *time* (in seconds). *time* is clamped to the range `[0.0, duration]`.
## Playback Properties
**(audio-player-volume *****player*****)**
Returns the current volume of *player* as a flonum in the range `[0.0, 1.0]`, where `0.0` is silent and `1.0` is full volume.
**(set-audio-player-volume! *****player vol*****)** \
**(set-audio-player-volume! *****player vol fade*****)**
Sets the volume of *player* to *vol*, a number clamped to `[0.0, 1.0]`. If *fade* is provided, it specifies a fade duration in seconds over which the volume change is applied. Negative fade values are treated as zero.
**(audio-player-pan *****player*****)**
Returns the stereo pan position of *player* as a flonum in the range `[-1.0, 1.0]`, where `-1.0` is fully left, `0.0` is center, and `1.0` is fully right.
**(set-audio-player-pan! *****player pan*****)**
Sets the stereo pan position of *player* to *pan*, a number clamped to `[-1.0, 1.0]`.
**(audio-player-rate *****player*****)**
Returns the current playback rate of *player* as a flonum. A rate of `1.0` is normal speed; `0.5` is half speed; `2.0` is double speed. Rate control is only meaningful if the player was created with *rate?* set to `#t`.
**(set-audio-player-rate! *****player rate*****)**
Sets the playback rate of *player* to *rate*, a number clamped to `[0.5, 2.0]`. The player must have been created with variable-rate support enabled (see `make-audio-player`).
**(audio-player-loops *****player*****)**
Returns the loop count of *player* as an integer. A value of `0` means the audio plays once without looping. A positive value *n* means the audio plays *n + 1* times in total. A negative value means the audio loops indefinitely until stopped.
**(set-audio-player-loops! *****player n*****)**
Sets the loop count of *player* to the integer *n*. A value of `0` means the audio plays once without looping. A positive value *n* means the audio plays *n + 1* times in total. A negative value means the audio loops indefinitely until stopped.