2.4.2 Sources

While the 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, audio-play is a better fit.

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 (vec3 0.0 0.0 0.0)] [#:velocity (vec3 0.0 0.0 0.0)] [#:direction (vec3 0.0 0.0 0.0)] [#:relative? #f]

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.

Refer to audio-play (see Audio Files) for information about the optional keyword arguments.

Procedure: source? obj

Return #t if obj is an audio source object.

Procedure: streaming-source? source

Return #t if source contains streaming audio.

Procedure: static-source? source

Return #t if source contains static audio.

Procedure: source-playing? source

Return #t if source is currently playing.

Procedure: source-paused? source

Return #t if source is currently paused.

Procedure: source-stopped? source

Return #t if source is currently stopped.

Procedure: source-pitch source

Return the pitch multiplier of source.

Procedure: source-volume source

Return the volume multiplier of source.

Procedure: source-min-volume source

Return the minimum volume of source.

Procedure: source-max-volume source

Return the maximum volume of source.

Procedure: source-max-distance source

Return the maximum distance of source.

Procedure: source-reference-distance source

Return the reference distance of source.

Procedure: source-rolloff-factor source

Return the rolloff factor of source.

Procedure: source-cone-outer-volume source

Return the volume of source when outside the oriented cone.

Procedure: source-cone-inner-angle source

Return the inner angle of the sound cone of source in radians.

Procedure: source-cone-outer-angle source

Return the outer angle of the sound cone of source in radians.

Procedure: source-position source

Return the position of source as a 3D vector.

Procedure: source-velocity source

Return the velocity of source as a 3D vector.

Procedure: source-direction source

Return the direction of source as a 3D vector.

Procedure: source-relative? source

Return #t if the position of source is relative to the listener’s position.

Procedure: source-play source

Begin/resume playback of source.

Procedure: source-pause source

Pause playback of source.

Procedure: source-toggle source

Play source if it is currently paused or pause source if it is currently playing.

Procedure: source-stop [source]

Stop playing source or, if no source is specified, stop playing all sources.

Procedure: source-rewind source

Rewind source to the beginning of the audio stream.

Procedure: set-source-audio! source audio

Set the playback stream for source to audio.

Procedure: set-source-loop! source loop?

Configure whether or not source should loop the audio stream.

Procedure: set-source-pitch! source pitch

Set the pitch multiplier of source to pitch

Procedure: set-source-volume! source volume

Set the volume of source to volume. A value of 1.0 is 100% volume.

Procedure: set-source-min-volume! source volume

Set the minimum volume of source to volume.

Procedure: set-source-max-volume! source volume

Set the maximum volume of source to volume.

Procedure: set-source-max-distance! source distance

Set the distance where there will no longer be any attenuation of source to distance.

Procedure: set-source-reference-distance! source distance

Set the reference distance of source to distance.

Procedure: set-source-rolloff-factor! source factor

Set the rolloff factor for source to factor.

Procedure: set-source-cone-outer-volume! source volume

Set the volume for source when outside the sound cone to volume.

Procedure: set-source-cone-inner-angle! source angle

Set the inner angle of the sound cone of source to angle radians.

Procedure: set-source-cone-outer-angle! source angle

Set the outer angle of the sound cone of source to angle radians.

Procedure: set-source-position! source position

Set the position of source to the 3D vector position.

Procedure: set-source-velocity! source velocity

Set the velocity of source to the 3D vector velocity.

Procedure: set-source-direction! source direction

Set the velocity of source to the 3D vector direction.

Procedure: set-source-relative! source relative?

If relative? is #t, the position of source is interpreted as relative to the listener’s position. Otherwise, the position of source is in absolute coordinates.