Skip to content

SoundGenerator

Overview

SoundGenerator is an abstract base class for Web-Audio-based sound-producing elements that work in conjunction with the soundManager to produces sounds.

@author John Blanco (PhET Interactive Simulations)

Class SoundGenerator

import { SoundGenerator } from 'scenerystack/tambo';

Constructor

new SoundGenerator( providedOptions? : SoundGeneratorOptions )

Instance Methods

connect( audioParam : AudioParam | AudioNode )

Connect the sound generator to an audio parameter.

disconnect( audioParam : AudioParam | AudioNode )

Disconnect the sound generator from an audio parameter.

isConnectedTo( audioParam : AudioParam | AudioNode ) : boolean

Test if this sound generator is connected to the provided audio param.

setOutputLevel( outputLevel : number, timeConstant : number )

Sets the output level of the sound generator.

@param outputLevel - generally between 0 and 1, but can be larger than 1 if necessary to amplify a small signal, and can be negative to invert the phase. @param [timeConstant] - time constant for output level change, longer values mean slower transitions, in seconds. Note that timeConstant is NOT a fade time. It's an exponential approach to the target output level, and the argument to setTargetAtTime, documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioParam/setTargetAtTime#timeconstant The document has this suggestion for choosing the value for timeConstant: "Depending on your use case, getting 95% toward the target value may already be enough; in that case, you could set timeConstant to one third of the desired duration."

getOutputLevel() : number

Get the current output level setting. Note that if the sound generator is disabled, this could return a non-zero value but the sound generator won't produce audible sound.

Instance Properties

audioContext : AudioContext

(protected)

fullyEnabledProperty : TReadOnlyProperty<boolean>

(readonly)

A Property that tracks whether this sound generator is fully enabled, meaning that all the enable control Properties are in a state indicating that sound can be produced. This should only be updated in the listener function defined below, nowhere else.

mainGainNode : GainNode

(protected)

main gain control that will be used to control the volume of the sound

soundSourceDestination : AudioNode

(protected)

The audio node to which the sound sources will connect, analogous to AudioContext.destination. If no additional audio nodes were provided upon construction, this will be the main gain node.

Type SoundGeneratorOptions

import type { SoundGeneratorOptions } from 'scenerystack/tambo';
  • initialOutputLevel?: number
    Initial value for the output level. Generally, this should always be between 0 and 1, but values greater than 1 may be needed in some rare cases in order to create enough output to be audible.
  • audioContext?: AudioContext
    By default, the shared audio context is used so that this sound can be registered with the sonification manager, but this can be overridden if desired. In general, overriding will only be done for testing.
  • connectImmediately?: boolean
    This flag controls whether the output of this sound generator is immediately connected to the audio context destination. This is useful for testing, but should not be set to true if this sound generator is being used in conjunction with the sound manager.
  • additionalAudioNodes?: AudioNode[]
    Audio nodes that will be connected in the specified order between the bufferSource and localGainNode, used to insert things like filters, compressors, etc.
  • sonificationLevel?: SoundLevelEnum
    The "level" for which this sound should be played, either BASIC or EXTRA.
  • associatedViewNode?: Node | null
    The associated view node is a Scenery node that, if provided, must be visible in the display for the sound generator to be enabled. This is generally used only for sounds that can play for long durations, such as a looping sound clip, that should be stopped when the associated visual representation is hidden.
  • enabledDuringReset?: boolean
    Controls whether sound should be generated during a reset. Generally the default value should be used, which is false, meaning that sound is not produced during a reset. There are some cases where this is turned on, such as for the sound produced by the Reset All button.
  • enabledDuringPhetioStateSetting?: boolean
    Controls whether sounds should be generated when phet-io state is being set. In almost all cases, this should not be overridden and the default behavior should be used, which is to prevent all sound production during the setting of phet-io state.
  • & EnabledComponentOptions

Source Code

See the source for SoundGenerator.ts in the tambo repository.