summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2019-01-09 20:26:28 -0500
committerDavid Thompson <dthompson2@worcester.edu>2020-04-07 16:17:02 -0400
commit159c35f706de14f3e3c6942934532011a1d77277 (patch)
treec2a8ec4cc93a2ca7c823579244fe63052d77d031
parentb5a93156dfc743aec69987e03e89d27735b615dd (diff)
audio: Add public audio API.
* chickadee/audio.scm: New file. * Makefile.am (SOURCES): Add it. * api.texi (Audio): Add docs.
-rw-r--r--Makefile.am1
-rw-r--r--chickadee/audio.scm763
-rw-r--r--doc/api.texi458
3 files changed, 1220 insertions, 2 deletions
diff --git a/Makefile.am b/Makefile.am
index 6183b03..23d7e5a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -59,6 +59,7 @@ SOURCES = \
chickadee/audio/openal.scm \
chickadee/audio/vorbis.scm \
chickadee/audio/wav.scm \
+ chickadee/audio.scm \
chickadee/render/color.scm \
chickadee/render/gl.scm \
chickadee/render/gpu.scm \
diff --git a/chickadee/audio.scm b/chickadee/audio.scm
new file mode 100644
index 0000000..aa56dac
--- /dev/null
+++ b/chickadee/audio.scm
@@ -0,0 +1,763 @@
+;;; Chickadee Game Toolkit
+;;; Copyright © 2020, 2019 David Thompson <davet@gnu.org>
+;;;
+;;; Chickadee is free software: you can redistribute it and/or modify
+;;; it under the terms of the GNU General Public License as published
+;;; by the Free Software Foundation, either version 3 of the License,
+;;; or (at your option) any later version.
+;;;
+;;; Chickadee is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+;;; General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with this program. If not, see
+;;; <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;
+;; Audio API.
+;;
+;;; Code:
+
+(define-module (chickadee audio)
+ #:use-module (chickadee array-list)
+ #:use-module (chickadee audio mpg123)
+ #:use-module ((chickadee audio openal) #:prefix openal:)
+ #:use-module (chickadee audio vorbis)
+ #:use-module (chickadee audio wav)
+ #:use-module (chickadee math)
+ #:use-module (chickadee math vector)
+ #:use-module (ice-9 format)
+ #:use-module (ice-9 match)
+ #:use-module (rnrs bytevectors)
+ #:use-module (srfi srfi-1)
+ #:use-module (srfi srfi-9)
+ #:use-module (srfi srfi-9 gnu)
+ #:export (init-audio
+ quit-audio
+ update-audio
+ load-audio
+ audio?
+ streaming-audio?
+ static-audio?
+ audio-mode
+ audio-duration
+ audio-bits-per-sample
+ audio-channels
+ audio-sample-rate
+ audio-play
+ make-source
+ source?
+ streaming-source?
+ static-source?
+ source-playing?
+ source-paused?
+ source-stopped?
+ source-pitch
+ source-volume
+ source-min-volume
+ source-max-volume
+ source-max-distance
+ source-reference-distance
+ source-rolloff-factor
+ source-cone-outer-volume
+ source-cone-inner-angle
+ source-cone-outer-angle
+ source-position
+ source-velocity
+ source-direction
+ source-relative?
+ source-play
+ source-pause
+ source-toggle
+ source-stop
+ source-rewind
+ set-source-audio!
+ set-source-loop!
+ set-source-pitch!
+ set-source-volume!
+ set-source-min-volume!
+ set-source-max-volume!
+ set-source-max-distance!
+ set-source-reference-distance!
+ set-source-rolloff-factor!
+ set-source-cone-outer-volume!
+ set-source-cone-inner-angle!
+ set-source-cone-outer-angle!
+ set-source-position!
+ set-source-velocity!
+ set-source-direction!
+ set-source-relative!)
+ #:re-export ((openal:listener-volume . listener-volume)
+ (openal:listener-position . listener-position)
+ (openal:listener-velocity . listener-velocity)
+ (openal:listener-orientation . listener-orientation)
+ (openal:set-listener-volume! . set-listener-volume!)
+ (openal:set-listener-position! . set-listener-position!)
+ (openal:set-listener-velocity! . set-listener-velocity!)
+ (openal:set-listener-orientation! . set-listener-orientation!)
+ (openal:doppler-factor . doppler-factor)
+ (openal:speed-of-sound . speed-of-sound)
+ (openal:distance-model . distance-model)
+ (openal:set-doppler-factor! . set-doppler-factor!)
+ (openal:set-speed-of-sound! . set-speed-of-sound!)
+ (openal:set-distance-model! . set-distance-model!)))
+
+(define %default-cone-outer-angle (* 2.0 pi))
+(define %default-max-distance (expt 2 31))
+
+(define-record-type <audio>
+ (%make-audio mode bv duration bits-per-sample channels sample-rate
+ decode-proc seek-proc close-proc)
+ audio?
+ (mode audio-mode)
+ (bv audio-bv)
+ (static-length audio-static-length set-audio-static-length!)
+ (duration audio-duration)
+ (bits-per-sample audio-bits-per-sample)
+ (channels audio-channels)
+ (sample-rate audio-sample-rate)
+ (decode-proc audio-decode-proc)
+ (seek-proc audio-seek-proc)
+ (close-proc audio-close-proc))
+
+(define-record-type <source>
+ (%make-source audio openal-source)
+ source?
+ (audio source-audio %set-source-audio!)
+ (openal-source source-openal-source)
+ (loop? source-loop? %set-source-loop!)
+ (pitch source-pitch %set-source-pitch!)
+ (volume source-volume %set-source-volume!)
+ (min-volume source-min-volume %set-source-min-volume!)
+ (max-volume source-max-volume %set-source-max-volume!)
+ (max-distance source-max-distance %set-source-max-distance!)
+ (reference-distance source-reference-distance %set-source-reference-distance!)
+ (rolloff-factor source-rolloff-factor %set-source-rolloff-factor!)
+ (cone-outer-volume source-cone-outer-volume %set-source-cone-outer-volume!)
+ (cone-inner-angle source-cone-inner-angle %set-source-cone-inner-angle!)
+ (cone-outer-angle source-cone-outer-angle %set-source-cone-outer-angle!)
+ (position source-position %set-source-position!)
+ (velocity source-velocity %set-source-velocity!)
+ (direction source-direction %set-source-direction!)
+ (relative? source-relative? %set-source-relative!))
+
+(define-record-type <sound-system> ; gonna bring me back home
+ (%make-sound-system openal-context free-buffers used-buffers
+ sources streaming-sources free-sources used-sources
+ guardian)
+ sound-system?
+ (openal-context sound-system-openal-context)
+ (free-buffers sound-system-free-buffers)
+ (used-buffers sound-system-used-buffers)
+ (sources sound-system-sources)
+ (streaming-sources sound-system-streaming-sources)
+ ;; free/used temp sources for audio-play procedure.
+ (free-sources sound-system-free-sources)
+ (used-sources sound-system-used-sources)
+ (guardian sound-system-guardian))
+
+(define (make-sound-system)
+ (%make-sound-system (openal:make-context (openal:open-device))
+ (make-array-list)
+ (make-hash-table)
+ (make-weak-key-hash-table)
+ (make-hash-table)
+ (make-array-list)
+ (make-hash-table)
+ (make-guardian)))
+
+(define (register-source sound-system source)
+ (hashq-set! (sound-system-sources sound-system) source source)
+ ((sound-system-guardian sound-system) source))
+
+(define (borrow-buffer sound-system)
+ (let* ((free (sound-system-free-buffers sound-system))
+ (used (sound-system-used-buffers sound-system))
+ (buffer (if (array-list-empty? free)
+ (openal:make-buffer)
+ (array-list-pop! free))))
+ (hashv-set! used (openal:buffer-id buffer) buffer)))
+
+(define (return-buffer sound-system buffer-id)
+ (let* ((free (sound-system-free-buffers sound-system))
+ (used (sound-system-used-buffers sound-system))
+ (buffer (hashv-ref used buffer-id)))
+ (hashv-remove! used buffer-id)
+ (array-list-push! free buffer)))
+
+(define (borrow-source sound-system)
+ (let* ((free (sound-system-free-sources sound-system))
+ (used (sound-system-used-sources sound-system))
+ (source (if (array-list-empty? free)
+ (make-source)
+ (array-list-pop! free))))
+ (hashq-set! used source source)))
+
+(define (return-source sound-system source)
+ (let ((free (sound-system-free-sources sound-system))
+ (used (sound-system-used-sources sound-system)))
+ (when (hashq-remove! used source)
+ (array-list-push! free source))))
+
+(define (start-sound-system sound-system)
+ (openal:set-current-context! (sound-system-openal-context sound-system))
+ (mpg123-init))
+
+(define (stop-sound-system sound-system)
+ (let ((context (sound-system-openal-context sound-system)))
+ ;; Delete sources.
+ (hash-for-each (lambda (key source)
+ (openal:delete-source (source-openal-source source)))
+ (sound-system-sources sound-system))
+ ;; Delete buffers.
+ (array-list-for-each (lambda (i buffer)
+ (openal:delete-buffer buffer))
+ (sound-system-free-buffers sound-system))
+ (hash-for-each (lambda (id buffer)
+ (openal:delete-buffer buffer))
+ (sound-system-used-buffers sound-system))
+ ;; Delete context.
+ (openal:set-current-context! #f)
+ (openal:destroy-context context)
+ (openal:close-device (openal:context-device context))))
+
+(define (update-sound-system sound-system)
+ ;; TODO: Audio should really be handled on a dedicated thread, but
+ ;; that's a task for another day/year.
+ ;;
+ ;; Feed chunks of audio data to streaming sources that need more
+ ;; data.
+ (let ((streaming-sources (sound-system-streaming-sources sound-system)))
+ (hash-for-each (lambda (key source)
+ (let loop ()
+ ;; Unqueue a buffer that has been played, if
+ ;; there is one.
+ (when (source-flush-buffer source)
+ ;; Replace the unqueued buffer with the next
+ ;; chunk of audio. If there is nothing left
+ ;; to decode, remove the source from the list
+ ;; of actively streaming sources.
+ (if (source-buffer/stream source)
+ (loop)
+ (hashq-remove! streaming-sources source)))))
+ streaming-sources))
+ ;; Check if any borrowed sources (used for audio-play procedure) are
+ ;; stopped and return them to the queue for reuse.
+ (hash-for-each (lambda (key source)
+ (when (source-stopped? source)
+ (return-source sound-system source)))
+ (sound-system-used-sources sound-system))
+ ;; Delete OpenAL sources associated with sounds that are ready to be
+ ;; GC'd.
+ (let ((guardian (sound-system-guardian sound-system)))
+ (let loop ((source (guardian)))
+ (when source
+ (when (streaming-source? source)
+ ;; Clean up audio resources, like open file handles.
+ (audio-close (source-audio source))
+ ;; Ensuring that the source is stopped means that we can
+ ;; reliably reclaim all buffers still attached to the source
+ ;; before we delete it, otherwise we could leak memory
+ ;; because the buffers never make it back into the buffer
+ ;; pool.
+ (openal:source-stop (source-openal-source source))
+ (let loop ()
+ (and (source-flush-buffer source) (loop))))
+ (openal:delete-source (source-openal-source source))
+ (loop (guardian))))))
+
+(define (stop-all-sources sound-system)
+ (hash-for-each (lambda (key source)
+ (source-stop source))
+ (sound-system-sources sound-system)))
+
+(define (add-streaming-source sound-system source)
+ (hashq-set! (sound-system-streaming-sources sound-system) source source)
+ ;; Initialize the source's queue with a bunch of buffers, enough to
+ ;; keep OpenAL busy until the next sound system update.
+ ;; update-audio-system will add new buffers as they are unqueued
+ ;; later.
+ (let loop ((i 0))
+ (when (< i 8) ; TODO: allow variable number of buffers?
+ (source-buffer/stream source)
+ (loop (+ i 1)))))
+
+(define (remove-streaming-source sound-system source)
+ ;; Flush buffers.
+ (let loop ()
+ (and (source-flush-buffer source) (loop)))
+ ;; Remove from actively playing sources.
+ (hashq-remove! (sound-system-streaming-sources sound-system) source))
+
+(define current-sound-system (make-parameter #f))
+
+(define (init-audio)
+ "Initialize audio system."
+ (let ((sound-system (make-sound-system)))
+ (start-sound-system sound-system)
+ (current-sound-system sound-system)))
+
+(define (quit-audio)
+ "Stop audio system."
+ (let ((sound-system (current-sound-system)))
+ (when sound-system
+ (stop-sound-system sound-system)
+ (current-sound-system #f))))
+
+(define (update-audio)
+ "Update audio system."
+ (update-sound-system (current-sound-system)))
+
+(define* (make-source #:key
+ audio
+ loop?
+ (pitch 1.0)
+ (volume 1.0)
+ (min-volume 0.0)
+ (max-volume 1.0)
+ (max-distance %default-max-distance)
+ (reference-distance 0.0)
+ (rolloff-factor 1.0)
+ (cone-outer-volume 0.0)
+ (cone-inner-angle 0.0)
+ (cone-outer-angle %default-cone-outer-angle)
+ (position (vec3 0.0 0.0 0.0))
+ (velocity (vec3 0.0 0.0 0.0))
+ (direction (vec3 0.0 0.0 0.0))
+ relative?)
+ "Return a new audio source. AUDIO is the audio data to use when
+playing. LOOP? specifies whether or not to loop the audio during
+playback. PITCH is a scalar that modifies the pitch of the audio
+data. VOLUME is a scalar that modifies the volume of the audio data.
+
+For 3D audio representation, many other arguments are available.
+POSITION is a 3D vector. VELOCITY is a 3D vector. DIRECTION is a 3D
+vector. RELATIVE? specifies whether or not to consider the source
+position as relative to the listener or as an absolute value."
+ (let ((source (%make-source audio (openal:make-source))))
+ (register-source (current-sound-system) source)
+ (set-source-loop! source loop?)
+ (set-source-pitch! source pitch)
+ (set-source-volume! source volume)
+ (set-source-min-volume! source min-volume)
+ (set-source-max-volume! source max-volume)
+ (set-source-max-distance! source max-distance)
+ (set-source-reference-distance! source reference-distance)
+ (set-source-rolloff-factor! source rolloff-factor)
+ (set-source-cone-outer-volume! source cone-outer-volume)
+ (set-source-cone-inner-angle! source cone-inner-angle)
+ (set-source-cone-outer-angle! source cone-outer-angle)
+ (set-source-position! source position)
+ (set-source-velocity! source velocity)
+ (set-source-direction! source direction)
+ (set-source-relative! source relative?)
+ source))
+
+(define (streaming-source? source)
+ "Return #t if SOURCE is currently configured with streaming audio
+data."
+ (let ((audio (source-audio source)))
+ (and audio (streaming-audio? audio))))
+
+(define (static-source? source)
+ "Return #t if SOURCE is currently configured with static audio data"
+ (let ((audio (source-audio source)))
+ (and audio (static-audio? audio))))
+
+(define (set-source-audio! source audio)
+ "Set the playback stream for SOURCE to AUDIO."
+ (%set-source-audio! source audio)
+ (when (static-audio? audio)
+ (source-buffer/static source)))
+
+(define (source-play source)
+ "Begin/resume playback of SOURCE."
+ (unless (source-playing? source)
+ (openal:source-play (source-openal-source source))
+ (when (streaming-source? source)
+ (add-streaming-source (current-sound-system) source))))
+
+(define (source-pause source)
+ "Pause playback of SOURCE."
+ (openal:source-pause (source-openal-source source)))
+
+(define (source-toggle source)
+ "Play SOURCE if it is currently paused or pause SOURCE if it is
+currently playing."
+ (if (source-playing? source)
+ (source-pause source)
+ (source-play source)))
+
+(define* (source-stop #:optional source)
+ "Stop playing SOURCE or, if no source is specified, stop playing *all*
+sources."
+ (cond
+ ((not source)
+ (stop-all-sources (current-sound-system)))
+ ((streaming-source? source)
+ (openal:source-stop (source-openal-source source))
+ (audio-seek (source-audio source) 0)
+ (remove-streaming-source (current-sound-system) source))
+ (else
+ (openal:source-stop (source-openal-source source)))))
+
+(define (source-rewind source)
+ "Rewind SOURCE back to the beginning."
+ (if (streaming-source? source)
+ (audio-seek (source-audio source) 0)
+ (openal:source-rewind (source-openal-source source))))
+
+(define (source-playing? source)
+ "Return #t if SOURCE is currently playing."
+ (eq? (openal:source-state (source-openal-source source)) 'playing))
+
+(define (source-paused? source)
+ "Return #t if SOURCE is currently paused."
+ (eq? (openal:source-state (source-openal-source source)) 'paused))
+
+(define (source-stopped? source)
+ "Return #t if SOURCE is currently stopped."
+ (eq? (openal:source-state (source-openal-source source)) 'stopped))
+
+(define (set-source-loop! source loop?)
+ "Configure whether or not SOURCE should loop the audio stream."
+ (%set-source-pitch! source loop?)
+ (openal:set-source-looping! (source-openal-source source) loop?))
+
+(define (set-source-pitch! source pitch)
+ "Set the pitch multiplier for SOURCE to PITCH."
+ (unless (>= pitch 0.0)
+ (error "pitch must be a positive number" pitch))
+ (%set-source-pitch! source pitch)
+ (openal:set-source-property! (source-openal-source source) 'pitch pitch))
+
+(define (set-source-volume! source volume)
+ "Set the volume of SOURCE to VOLUME. A value of 1.0 is 100% volume."
+ (unless (>= volume 0.0)
+ (error "volume must be a positive number" volume))
+ (%set-source-volume! source volume)
+ (openal:set-source-property! (source-openal-source source) 'gain volume))
+
+(define (set-source-min-volume! source volume)
+ "Set the minimum volume of SOURCE to VOLUME."
+ (unless (>= volume 0.0)
+ (error "minimum volume must be a positive number" volume))
+ (%set-source-min-volume! source volume)
+ (openal:set-source-property! (source-openal-source source) 'min-gain volume))
+
+(define (set-source-max-volume! source volume)
+ "Set the maximum volume of SOURCE to VOLUME."
+ (unless (>= volume 0.0)
+ (error "maximum volume must be a positive number" volume))
+ (%set-source-max-volume! source volume)
+ (openal:set-source-property! (source-openal-source source) 'max-gain volume))
+
+(define (set-source-max-distance! source distance)
+ "Set the distance where there will no longer be any attenuation of
+SOURCE to DISTANCE."
+ (%set-source-max-distance! source distance)
+ (openal:set-source-property! (source-openal-source source) 'max-distance distance))
+
+(define (set-source-reference-distance! source distance)
+ "Set the reference distance of SOURCE to DISTANCE."
+ (%set-source-reference-distance! source distance)
+ (openal:set-source-property! (source-openal-source source) 'reference-distance distance))
+
+(define (set-source-rolloff-factor! source factor)
+ "Set the rolloff factor of SOURCE to FACTOR."
+ (%set-source-rolloff-factor! source factor)
+ (openal:set-source-property! (source-openal-source source) 'rolloff-factor factor))
+
+(define (set-source-cone-outer-volume! source volume)
+ "Set the volume of SOURCE when outside the sound cone to VOLUME."
+ (unless (>= volume 0.0)
+ (error "cone outer volume must be a positive number" volume))
+ (%set-source-cone-outer-volume! source volume)
+ (openal:set-source-property! (source-openal-source source) 'cone-outer-gain volume))
+
+(define (set-source-cone-inner-angle! source angle)
+ "Set the inner angle of the source cone of SOURCE to ANGLE radians."
+ (%set-source-cone-inner-angle! source angle)
+ (openal:set-source-property! (source-openal-source source)
+ 'cone-inner-angle
+ (radians->degrees angle)))
+
+(define (set-source-cone-outer-angle! source angle)
+ "Set the outer angle of the source cone of SOURCE to ANGLE radians."
+ (%set-source-cone-outer-angle! source angle)
+ (openal:set-source-property! (source-openal-source source)
+ 'cone-outer-angle
+ (radians->degrees angle)))
+
+(define (set-source-position! source position)
+ "Set the position of SOURCE to the 3D vector POSITION."
+ (%set-source-position! source position)
+ (openal:set-source-property! (source-openal-source source) 'position position))
+
+(define (set-source-velocity! source velocity)
+ "Set the velocity of SOURCE to the 3D vector VELOCITY."
+ (%set-source-velocity! source velocity)
+ (openal:set-source-property! (source-openal-source source) 'velocity velocity))
+
+(define (set-source-direction! source direction)
+ "Set the direction of SOURCE to the 3D vector DIRECTION."
+ (%set-source-direction! source direction)
+ (openal:set-source-property! (source-openal-source source) 'direction direction))
+
+(define (set-source-relative! source relative?)
+ "If RELATIVE? is #t, set the position of SOURCE to be relative to the
+listener. Otherwise, the position is in absolute coordinates."
+ (%set-source-relative! source relative?)
+ (openal:set-source-property! (source-openal-source source) 'relative relative?))
+
+(define (source-flush-buffer source)
+ (let* ((openal-source (source-openal-source source))
+ (processed (openal:source-buffers-processed openal-source)))
+ (if (> processed 0)
+ (let* ((buffer-id (openal:source-unqueue-buffer openal-source)))
+ (return-buffer (current-sound-system) buffer-id)
+ #t)
+ #f)))
+
+(define (source-buffer/static source)
+ (let* ((audio (source-audio source))
+ (buffer (borrow-buffer (current-sound-system)))
+ (bv (audio-bv audio))
+ (length (audio-static-length audio))
+ (format (audio-format audio))
+ (sample-rate (audio-sample-rate audio)))
+ (openal:set-buffer-data! buffer bv length format sample-rate)
+ (openal:set-source-buffer! (source-openal-source source) buffer)))
+
+(define (source-buffer/stream source)
+ (let* ((audio (source-audio source)))
+ (define (next)
+ (call-with-values (lambda () (audio-decode audio))
+ (lambda (chunk length)
+ (cond
+ ((> length 0)
+ (let ((format (audio-format audio))
+ (sample-rate (audio-sample-rate audio))
+ (buffer (borrow-buffer (current-sound-system))))
+ (openal:set-buffer-data! buffer chunk length format sample-rate)
+ (openal:source-queue-buffer (source-openal-source source) buffer)
+ (when (source-stopped? source)
+ (source-play source))
+ #t))
+ ((source-loop? source)
+ ;; Reset back to the beginning and try again.
+ (audio-seek audio 0)
+ (next))
+ ;; ight imma head out (if the git history is lost,
+ ;; researchers will be able to accurately date the code
+ ;; based upon this meme)
+ (else #f)))))
+ (next)))
+
+(define* (make-audio #:key
+ mode
+ (buffer-size 4096)
+ bits-per-sample
+ channels
+ duration
+ sample-rate
+ decode
+ seek
+ close)
+ (let* ((bv-size (if (eq? mode 'stream)
+ buffer-size
+ ;; Make a buffer big enough to hold the entire
+ ;; decoded audio stream.
+ (inexact->exact
+ (ceiling
+ (* duration
+ (/ bits-per-sample 8)
+ channels
+ sample-rate
+ ;; XXX: Adding extra padding because vorbis files
+ ;; seem to lie about how many audio samples there
+ ;; are.
+ 1.1)))))
+ (audio (%make-audio mode
+ (make-bytevector bv-size)
+ duration
+ bits-per-sample
+ channels
+ sample-rate
+ decode
+ seek
+ close)))
+ (when (eq? mode 'static)
+ (call-with-values (lambda () (audio-decode audio))
+ (lambda (bv length)
+ (set-audio-static-length! audio length)))
+ (audio-close audio))
+ audio))
+
+(define (display-audio audio port)
+ (format port "#<audio mode: ~a duration: ~f bits-per-sample: ~d sample-rate: ~d>"
+ (audio-mode audio)
+ (audio-duration audio)
+ (audio-bits-per-sample audio)
+ (audio-sample-rate audio)))
+
+(set-record-type-printer! <audio> display-audio)
+
+(define (streaming-audio? audio)
+ "Return #t if AUDIO is in streaming mode."
+ (eq? (audio-mode audio) 'stream))
+
+(define (static-audio? audio)
+ "Return #t if AUDIO is in static mode."
+ (eq? (audio-mode audio) 'static))
+
+(define (audio-format audio)
+ (let ((channels (audio-channels audio))
+ (bits-per-sample (audio-bits-per-sample audio)))
+ (cond
+ ((and (= channels 1)
+ (= bits-per-sample 16))
+ 'mono-16)
+ ((and (= channels 1)
+ (= bits-per-sample 8))
+ 'mono-8)
+ ((and (= channels 2)
+ (= bits-per-sample 16))
+ 'stereo-16)
+ ((and (= channels 2)
+ (= bits-per-sample 8))
+ 'stereo-8)
+ (else
+ (error "unsupported audio format" channels bits-per-sample)))))
+
+(define (audio-decode audio)
+ (define (nearest-multiple-of-4 x)
+ (let ((remainder (modulo x 4)))
+ (if (zero? remainder)
+ x
+ (+ x (- 4 remainder)))))
+ (let* ((bv (audio-bv audio))
+ (length ((audio-decode-proc audio) bv)))
+ (values bv (nearest-multiple-of-4 length))))
+
+(define (audio-close audio)
+ ((audio-close-proc audio)))
+
+(define (audio-seek audio t)
+ ((audio-seek-proc audio) t))
+
+(define* (audio-play audio #:key
+ (pitch 1.0)
+ (volume 1.0)
+ (min-volume 0.0)
+ (max-volume 1.0)
+ (max-distance %default-max-distance)
+ (reference-distance 0.0)
+ (rolloff-factor 1.0)
+ (cone-outer-volume 0.0)
+ (cone-inner-angle 0.0)
+ (cone-outer-angle %default-cone-outer-angle)
+ (position (vec3 0.0 0.0 0.0))
+ (velocity (vec3 0.0 0.0 0.0))
+ (direction (vec3 0.0 0.0 0.0))
+ relative?)
+ (let ((source (borrow-source (current-sound-system))))
+ (set-source-audio! source audio)
+ (set-source-pitch! source pitch)
+ (set-source-volume! source volume)
+ (set-source-min-volume! source min-volume)
+ (set-source-max-volume! source max-volume)
+ (set-source-max-distance! source max-distance)
+ (set-source-reference-distance! source reference-distance)
+ (set-source-rolloff-factor! source rolloff-factor)
+ (set-source-cone-outer-volume! source cone-outer-volume)
+ (set-source-cone-inner-angle! source cone-inner-angle)
+ (set-source-cone-outer-angle! source cone-outer-angle)
+ (set-source-position! source position)
+ (set-source-velocity! source velocity)
+ (set-source-direction! source direction)
+ (set-source-relative! source relative?)
+ (source-play source)))
+
+(define (make-wav-audio file-name mode)
+ (let ((wav (open-wav file-name)))
+ (make-audio #:mode mode
+ #:duration (/ (exact->inexact (wav-length wav))
+ (wav-sample-rate wav))
+ #:bits-per-sample (wav-bits-per-sample wav)
+ #:sample-rate (wav-sample-rate wav)
+ #:channels (wav-num-channels wav)
+ #:decode
+ (lambda (bv)
+ (wav-read wav bv))
+ #:seek
+ (lambda (t)
+ (wav-time-seek wav t))
+ #:close
+ (lambda ()
+ (close-wav wav)))))
+
+(define (make-vorbis-audio file-name mode)
+ (let* ((vf (vorbis-open file-name))
+ (info (vorbis-info vf)))
+ (make-audio #:mode mode
+ #:duration (vorbis-time-total vf)
+ #:bits-per-sample 16
+ #:sample-rate (vorbis-info-sample-rate info)
+ #:channels (vorbis-info-channels info)
+ #:decode
+ (lambda (bv)
+ (vorbis-fill-buffer vf bv))
+ #:seek
+ (lambda (t)
+ (vorbis-time-seek vf t))
+ #:close
+ (lambda ()
+ (vorbis-clear vf)))))
+
+(define (make-mp3-audio file-name mode)
+ (let ((handle (mpg123-open file-name)))
+ (call-with-values (lambda () (mpg123-format handle))
+ (lambda (sample-rate channels bits-per-sample)
+ (make-audio #:mode mode
+ #:bits-per-sample bits-per-sample
+ #:channels channels
+ #:duration (exact->inexact
+ (/ (mpg123-length handle) sample-rate))
+ #:sample-rate sample-rate
+ #:decode
+ (lambda (bv)
+ (mpg123-read handle bv))
+ #:seek
+ (lambda (t)
+ (mpg123-time-seek handle t))
+ #:close
+ (lambda ()
+ (mpg123-close handle)))))))
+
+(define* (load-audio file-name #:key (mode 'static))
+ "Load audio source in FILE-NAME. The following audio formats are
+supported:
+
+- WAV
+- Ogg Vorbis
+- MP3
+
+MODE determines the algorithm used for reading audio from the file.
+If MODE is 'static' then the entire file will be read into memory
+immediately. If MODE is 'stream', audio data will be need in small
+pieces as needed from the file. The default mode is 'static'. For
+short sound effects, 'static' is recommended. For music and other
+lengthy audio files, 'stream' is recommended."
+ (unless (file-exists? file-name)
+ (error "file not found" file-name))
+ (let* ((make (match (last (string-split file-name #\.))
+ ("wav" make-wav-audio)
+ ("ogg" make-vorbis-audio)
+ ("mp3" make-mp3-audio)
+ (ext
+ (error "unsupported audio file format:" ext)))))
+ (make file-name mode)))
diff --git a/doc/api.texi b/doc/api.texi
index f1726d9..18e0841 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -2787,8 +2787,462 @@ Return the data type of @var{attribute}.
@node Audio
@section Audio
-Most games need to play audio. Background music to set the mood and
-many sound effects for when things happen.
+A game isn't complete without sound. Most games play some cool
+background music to set the mood and have many sound effects to play
+when events happen. The @code{(chickadee audio)} module provides a
+robust audio API backed by the OpenAL 3D audio system.
+
+@menu
+* Audio Files:: Not audiophiles.
+* Sources:: Audio emitters.
+* The Listener:: The player's ears.
+* The Environment:: Global sound model settings.
+@end menu
+
+The basics of playing audio are very simple. Just load an audio file
+in the load hook (or anywhere else once the game loop is running) and
+play it!
+
+@example
+(use-modules (chickadee audio))
+
+(define audio #f)
+
+(define (load)
+ (set! audio (load-audio "neat-sound-effect.wav"))
+ (audio-play audio))
+
+(run-game #:load load)
+@end example
+
+For more advanced usage, check out the full API reference in the
+following sections.
+
+@node Audio Files
+@subsection Audio Files
+
+Sound data is represented by a special @code{<audio>} data type that
+stores not only the audio samples themselves, but metadata such as
+sample rate, number of channels, and how many bits are used for each
+sample.
+
+@deffn {Procedure} load-audio file-name [#:mode @code{static}]
+Load audio within @var{file-name}. The following file formats are
+currently supported:
+
+@itemize
+@item WAV
+@item MP3
+@item Ogg Vorbis
+@end itemize
+
+Audio files can be loaded in two different ways, as indicated by
+@var{mode}:
+
+@itemize
+@item static:
+Load the entire audio file into memory.
+@item stream:
+Load chunks of the audio file as needed.
+@end itemize
+
+Generally speaking, sound effects don't take up much space and should
+be loaded statically, but music files are much larger and should use
+streaming. Static loading is the default.
+@end deffn
+
+@deffn {Procedure} audio? @var{obj}
+Return @code{#t} if @var{obj} is an audio object.
+@end deffn
+
+@deffn {Procedure} streaming-audio? @var{audio}
+Return @code{#t} if @var{audio} uses stream loading.
+@end deffn
+
+@deffn {Procedure} static-audio?
+Return @code{#t} if @var{audio} uses static loading.
+@end deffn
+
+@deffn {Procedure} audio-mode audio
+Return the loading mode for @var{audio}, either @code{static} or
+@code{stream}.
+@end deffn
+
+@deffn {Procedure} audio-duration audio
+Return the duration of @var{audio} in seconds.
+@end deffn
+
+@deffn {Procedure} audio-bits-per-sample audio
+Return the number of bits per sample in @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-channels audio
+Return the number of channels in @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-sample-rate audio
+Return the sample rate of @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-play audio [#:pitch 1.0] [#:volume 1.0] @
+ [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] @
+ [#:reference-distance 0.0] [#:rolloff-factor 1.0] @
+ [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] @
+ [#:cone-outer-angle] @
+ [#:position @code{(vec3 0.0 0.0 0.0)}] @
+ [#:velocity @code{(vec3 0.0 0.0 0.0)}] @
+ [#:direction @code{(vec3 0.0 0.0 0.0)}] @
+ [#:relative? @code{#f}]
+
+Play @var{audio}. There are many, many knobs to tweak that will
+affect the sound that comes out of the player's speakers.:
+
+@itemize
+@item @var{pitch}:
+Pitch multiplier. The default value of 1.0 means no change in pitch.
+@item @var{volume}:
+Volume multiplier. The default value of 1.0 means no change in volume.
+@item @var{min-volume}:
+Minimum volume.
+@item @var{max-volume}:
+Maximum volume.
+@item @var{max-distance}:
+Used with the inverse clamped distance model (the default model) to
+set the distance where there will no longer be any attenuation of the
+source.
+@item @var{reference-distance}:
+The distance where the volume for the audio would drop by half (before
+being influenced by the rolloff factor or maximum distance.)
+@item @var{rolloff-factor}:
+For slowing down or speeding up the rate of attenuation. The default
+of 1.0 means no attenuation adjustment is made.
+@item @var{cone-outer-volume}:
+The volume when outside the oriented cone.
+@item @var{cone-inner-angle}:
+Inner angle of the sound cone, in radians. The default value is 0.
+@item @var{cone-outer-angle}:
+Outer angle of the sound cone, in radians. The default value is 2pi
+radians, or 360 degrees.
+@item @var{position}:
+The source of the sound emitter in 3D space.
+@item @var{velocity}:
+The velocity of the sound emitter in 3D space.
+@item @var{direction}:
+The direction of the sound emitter in 3D space.
+@item @var{relative?}:
+A flag that determines whether the position is in absolute coordinates
+or relative to the listener's location. Absolute coordinates are used
+by default.
+@end itemize
+
+For games with basic sound needs (that is to say they don't need 3D
+sound modeling), the only things that really matter are @var{volume}
+and @var{pitch}.
+
+@end deffn
+
+@node Sources
+@subsection Sources
+
+While the @code{audio-play} procedure provides a quick and convenient
+way to play audio, it has some limitations. What if the audio is a
+long piece of music that might need to be paused or stopped later?
+What if the audio should be looped? What if the volume or pitch needs
+to be altered? For manipulating audio in these ways, a ``source'' is
+required. Sources can be thought of like a boombox: They sit
+somewhere in the room and play sound. The pause or stop buttons can
+be pressed; it can be moved somewhere else; the volume knob can be
+adjusted; the CD can be changed.
+
+Sources are a great fit for handling background music, among other
+things. For quick, one-off sound effects, @code{audio-play} is a
+better fit.
+
+@deffn {Procedure} make-source audio loop? [#:pitch 1.0] [#:volume 1.0] @
+ [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] @
+ [#:reference-distance 0.0] [#:rolloff-factor 1.0] @
+ [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] @
+ [#:cone-outer-angle] @
+ [#:position @code{(vec3 0.0 0.0 0.0)}] @
+ [#:velocity @code{(vec3 0.0 0.0 0.0)}] @
+ [#:direction @code{(vec3 0.0 0.0 0.0)}] @
+ [#:relative? @code{#f}]
+
+Return a new audio source. @var{audio} is the audio data to use when
+playing. @var{loop?} specifies whether or not to loop the audio
+during playback.
+
+Refer to @code{audio-play} (@pxref{Audio Files}) for information about
+the optional keyword arguments.
+@end deffn
+
+@deffn {Procedure} source? obj
+Return @code{#t} if @var{obj} is an audio source object.
+@end deffn
+
+@deffn {Procedure} streaming-source? source
+Return @code{#t} if @var{source} contains streaming audio.
+@end deffn
+
+@deffn {Procedure} static-source? source
+Return @code{#t} if @var{source} contains static audio.
+@end deffn
+
+@deffn {Procedure} source-playing? source
+Return @code{#t} if @var{source} is currently playing.
+@end deffn
+
+@deffn {Procedure} source-paused? source
+Return @code{#t} if @var{source} is currently paused.
+@end deffn
+
+@deffn {Procedure} source-stopped? source
+Return @code{#t} if @var{source} is currently stopped.
+@end deffn
+
+@deffn {Procedure} source-pitch source
+Return the pitch multiplier of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-volume source
+Return the volume multiplier of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-min-volume source
+Return the minimum volume of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-max-volume source
+Return the maximum volume of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-max-distance source
+Return the maximum distance of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-reference-distance source
+Return the reference distance of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-rolloff-factor source
+Return the rolloff factor of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-cone-outer-volume source
+Return the volume of @var{source} when outside the oriented cone.
+@end deffn
+
+@deffn {Procedure} source-cone-inner-angle source
+Return the inner angle of the sound cone of @var{source} in radians.
+@end deffn
+
+@deffn {Procedure} source-cone-outer-angle source
+Return the outer angle of the sound cone of @var{source} in radians.
+@end deffn
+
+@deffn {Procedure} source-position source
+Return the position of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-velocity source
+Return the velocity of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-direction source
+Return the direction of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-relative? source
+Return @code{#t} if the position of @var{source} is relative to the
+listener's position.
+@end deffn
+
+@deffn {Procedure} source-play source
+Begin/resume playback of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-pause source
+Pause playback of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-toggle source
+Play @var{source} if it is currently paused or pause @var{source} if
+it is currently playing.
+@end deffn
+
+@deffn {Procedure} source-stop [source]
+Stop playing @var{source} or, if no source is specified, stop playing
+@emph{all} sources.
+@end deffn
+
+@deffn {Procedure} source-rewind source
+Rewind @var{source} to the beginning of the audio stream.
+@end deffn
+
+@deffn {Procedure} set-source-audio! source audio
+Set the playback stream for @var{source} to @var{audio}.
+@end deffn
+
+@deffn {Procedure} set-source-loop! source loop?
+Configure whether or not @var{source} should loop the audio stream.
+@end deffn
+
+@deffn {Procedure} set-source-pitch! source pitch
+Set the pitch multiplier of @var{source} to @var{pitch}
+@end deffn
+
+@deffn {Procedure} set-source-volume! source volume
+Set the volume of @var{source} to @var{volume}. A value of 1.0 is
+100% volume.
+@end deffn
+
+@deffn {Procedure} set-source-min-volume! source volume
+Set the minimum volume of @var{source} to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-max-volume! source volume
+Set the maximum volume of @var{source} to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-max-distance! source distance
+Set the distance where there will no longer be any attenuation of
+@var{source} to @var{distance}.
+@end deffn
+
+@deffn {Procedure} set-source-reference-distance! source distance
+Set the reference distance of @var{source} to @var{distance}.
+@end deffn
+
+@deffn {Procedure} set-source-rolloff-factor! source factor
+Set the rolloff factor for @var{source} to @var{factor}.
+@end deffn
+
+@deffn {Procedure} set-source-cone-outer-volume! source volume
+Set the volume for @var{source} when outside the sound cone to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-cone-inner-angle! source angle
+Set the inner angle of the sound cone of @var{source} to @var{angle} radians.
+@end deffn
+
+@deffn {Procedure} set-source-cone-outer-angle! source angle
+Set the outer angle of the sound cone of @var{source} to @var{angle} radians.
+@end deffn
+
+@deffn {Procedure} set-source-position! source position
+Set the position of @var{source} to the 3D vector @var{position}.
+@end deffn
+
+@deffn {Procedure} set-source-velocity! source velocity
+Set the velocity of @var{source} to the 3D vector @var{velocity}.
+@end deffn
+
+@deffn {Procedure} set-source-direction! source direction
+Set the velocity of @var{source} to the 3D vector @var{direction}.
+@end deffn
+
+@deffn {Procedure} set-source-relative! source relative?
+If @var{relative?} is @code{#t}, the position of @var{source} is
+interpreted as relative to the listener's position. Otherwise, the
+position of @var{source} is in absolute coordinates.
+@end deffn
+
+@node The Listener
+@subsection The Listener
+
+The listener is a collection of global state that represents the
+player within the 3D sound model. For games that do not need 3D sound
+modeling, manipulating the listener's master volume is the only
+interesting thing to do here.
+
+@deffn {Procedure} listener-volume
+Return the current master volume of the listener.
+@end deffn
+
+@deffn {Procedure} listener-position
+Return the current position of the listener.
+@end deffn
+
+@deffn {Procedure} listener-velocity
+Return the current velocity of the listener.
+@end deffn
+
+@deffn {Procedure} listener-orientation
+Return the current orientation of the listener.
+@end deffn
+
+@deffn {Procedure} set-listener-volume! volume
+Set the listener's master volume to @var{volume}, a value in the range [0,
+1].
+@end deffn
+
+@deffn {Procedure} set-listener-position! position
+Set the listener's position to the 3D vector @var{position}.
+@end deffn
+
+@deffn {Procedure} set-listener-velocity! velocity
+Set the listener's velocity to the 3D vector @var{velocity}.
+@end deffn
+
+@deffn {Procedure} set-listener-orientation! at up
+Set the listener's orientation to the 3D vectors @var{at} and
+@var{up}.
+@end deffn
+
+@node The Environment
+@subsection The Environment
+
+The environment defines global parameters that govern how sound is
+processed within the 3D modeling space.
+
+@deffn {Procedure} doppler-factor
+Return the current doppler factor.
+@end deffn
+
+@deffn {Procedure} speed-of-sound
+Return the current speed of sound.
+@end deffn
+
+@deffn {Procedure} distance-model
+Return the current distance model.
+
+Possible return values are:
+
+@itemize
+@item @code{none}
+@item @code{inverse-distance}
+@item @code{inverse-distance-clamped} (the default)
+@item @code{linear-distance}
+@item @code{linear-distance-clamped}
+@item @code{exponent-distance}
+@item @code{exponent-distance-clamped}
+@end itemize
+
+@end deffn
+
+@deffn {Procedure} set-doppler-factor! doppler-factor
+Change the doppler factor to @var{doppler-factor}.
+@end deffn
+
+@deffn {Procedure} set-speed-of-sound! speed-of-sound
+Change the speed of sound to @var{speed-of-sound}.
+@end deffn
+
+@deffn {Procedure} set-distance-model! distance-model
+Change the distance model to @var{distance-model}. Valid distance
+models are:
+
+@itemize
+@item @code{none}
+@item @code{inverse-distance}
+@item @code{inverse-distance-clamped}
+@item @code{linear-distance}
+@item @code{linear-distance-clamped}
+@item @code{exponent-distance}
+@item @code{exponent-distance-clamped}
+@end itemize
+
+@end deffn
@node Scripting
@section Scripting