►3s:   positional audio and mixing
3s:   positional audio and mixing
1 User API Reference
audio?
path->audio
sound-state
sound-state/  c
sound/  c
sound-scape/  c
background
sound-at
sound-on
sound-until
2 Internal API Reference
sound-context?
make-sound-context
sound-context-destroy!
system-state?
initial-system-state
sound-pause!
sound-unpause!
sound-destroy!
render-sound
3 Integrating with lux
make-3s
6.3.90.900
  top  ← prev  up  next → 

3s: positional audio and mixing

Jay McCarthy

 (require 3s) package: 3s

The 3s module provides a system for positional audio and mixing of sound effects. It is intended for interactive applications and integrates with lux. Presently it uses the openal library, but in principle does not require its use.

The overall model of 3s is to parameterize sounds over the world state, so that sounds created in the past can be updated (paused, move position, have the content changed, etc) by initially creating them so that they inspect the world state for cues to such updates.

The key function, render-sound, is called regularly (i.e., once per tick) and receives the updated world state, along with any additional sounds created during that tick.

1 User API Reference

procedure

(audio? x) → boolean?

  x : any/c
Identifies audio content.

procedure

(path->audio p) → audio?

  p : path-string?
Loads audio content from a file given by p.

struct

(struct sound-state (audio posn gain relative? looping? paused?))

  audio : audio?
  posn : inexact?
  gain : inexact?
  relative? : boolean?
  looping? : boolean?
  paused? : boolean?
A structure specifying the state of a sound. The audio field identifies the audio content of the sound. The posn field identifies the 2D position of the sound, with the real-part of the number as the X coordinate and imag-part as the Y coordinate. The other fields have their obvious interpretation.

value

sound-state/c : contract?

Equivalent to (or/c #f sound-state?).

value

sound/c : contract?

Equivalent to (-> any/c sound-state/c).

value

sound-scape/c : contract?

Equivalent to (listof sound/c).

procedure

(background a-f    
  [#:gain gain    
  #:pause-f pause-f]) → sound/c
  a-f : (-> any/c audio?)
  gain : inexact? = 1.0
  pause-f : (-> any/c boolean?) = (λ (w) #f)
A sound corresponding to background music. The a-f function selects the audio content based on the world value, while the pause-f function determines whether the sound is paused.

procedure

(sound-at a    
  p    
  [#:gain gain    
  #:looping? looping?    
  #:pause-f pause-f]) → sound/c
  a : audio?
  p : inexact?
  gain : inexact? = 1.0
  looping? : boolean? = #f
  pause-f : (-> any/c boolean?) = (λ (w) #f)
A sound located at point p with audio content a. The pause-f function determines whether the sound is paused.

procedure

(sound-on a    
  p-f    
  [#:gain gain    
  #:looping? looping?    
  #:pause-f pause-f]) → sound/c
  a : audio?
  p-f : (-> any/c inexact?)
  gain : inexact? = 1.0
  looping? : boolean? = #f
  pause-f : (-> any/c boolean?) = (λ (w) #f)
A sound located at the point returned by p-f with audio content a. The pause-f function determines whether the sound is paused.

procedure

(sound-until s until-f) → sound/c

  s : sound/c
  until-f : (-> any/c boolean?)
A sound that plays until until-f returns true.

2 Internal API Reference

procedure

(sound-context? x) → boolean?

  x : any/c
Identifies sound contexts.

procedure

(make-sound-context) → sound-context?

Returns a sound context.

procedure

(sound-context-destroy! sc) → void?

  sc : sound-context?
Destroys a sound context, releasing all resources and stopping all sounds.

procedure

(system-state? x) → boolean?

  x : any/c
Identifies the 3s state.

procedure

(initial-system-state sc) → system-state?

  sc : sound-context?
Constructs an initial 3s state.

procedure

(sound-pause! ss) → void?

  ss : system-state?
Pauses all sounds of ss.

procedure

(sound-unpause! ss) → void?

  ss : system-state?
Unpauses all sounds of ss.

procedure

(sound-destroy! ss) → void?

  ss : system-state?
Destroys ss, releasing all resources and stopping all sounds.

procedure

(render-sound ss scale lp w sounds) → system-state?

  ss : system-state?
  scale : real?
  lp : inexact?
  w : any/c
  sounds : sound-scape/c
Updates all the sounds in ss according to the new sound scale scale, the new position of the listener lp, and the new world value w, as well initializes all sounds in sounds, returning a new 3s system state.

3 Integrating with lux

 (require lux/chaos/3s) package: 3s

3s is designed to integrate with lux through the lux/chaos/3s module, which provides a chaos for sound scapes.

procedure

(make-3s) → chaos?

Returns a chaos that manages sound output.

word-event is never called with events from this chaos.

The values that word-output should return are four element vectors where the elements correspond to the last four arguments of render-sound: the sound scale, the listener position, the world value, and the list of new sounds.

  top  ← prev  up  next →