(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.