BufferAudioSource
Overview
BufferAudioSource node represents a memory-resident audio asset that can contain one or more channels. Typically the length of the Pulse Coded Modulation (PCM) data is expected to be fairly short (usually somewhat less than a minute).
The BufferAudioSource node belongs to the Sound component and requires at least level 2, its default container field is children. It is available from X3D version 4.0 or higher.
Hierarchy
1
2
3
4
5
+ X3DNode
+ X3DChildNode
+ X3DTimeDependentNode
+ X3DSoundSourceNode
+ BufferAudioSource (X3DUrlObject)*
Fields
SFNode [in, out] metadata NULL [X3DMetadataObject]
Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
Hint
SFString [in, out] description “”
Author-provided prose that describes intended purpose of the url asset.
Hint
- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as & for & ampersand character, or " for “ quotation-mark character).
SFBool [in, out] enabled TRUE
Enables/disables node operation.
SFBool [in, out] load TRUE
load=true means load immediately, load=false means defer loading or else unload a previously loaded scene.
Hints
- Allows author to design when Inline loading occurs via user interaction, event chains or scripting.
- Use a separate LoadSensor node to detect when loading is complete.
MFString [in, out] url [ ] [URI]
Location and filename of sound file. Support for .wav format is required, .midi format is recommended, other formats are optional.
Hints
- MFString arrays can have multiple values, so separate each individual string by quote marks. “https://www.web3d.org” “https://www.web3d.org/about” “etc.”
- Alternative XML encoding for quotation mark “ is " (which is an example of a character entity).
- Can replace embedded blank(s) in url queries with %20 for each blank character.
- X3D Scene Authoring Hints, urls
Warning
- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
SFTime [in, out] autoRefresh 0 [0,∞)
autoRefresh defines interval in seconds before automatic reload of current url asset is performed.
Hints
- If preceding file loading fails or load field is false, no refresh is performed.
- Repeated refresh attempts to reload currently loaded entry of url list. If that fails, the browser retries other entries in the url list.
Warning
- Automatically reloading content has security considerations and needs to be considered carefully.
SFTime [in, out] autoRefreshTimeLimit 3600 [0,∞)
autoRefreshTimeLimit defines maximum duration that automatic refresh activity can occur.
Hint
- Automatic refresh is different than query and response timeouts performed by a networking library while sequentially attempting to retrieve addressed content from a url list.
Warning
- Automatically reloading content has security considerations and needs to be considered carefully.
SFInt32 [in, out] numberOfChannels 0 [0,∞)
numberOfChannels is number of audio channels found in this buffer source.
SFFloat [in, out] sampleRate 0 [0,∞)
sampleRate field is sample-frames per second.
Hints
- Sample-rate converters (variable speed processors) are not supported in real-time processing.
- Nyquist frequency is half this sampleRate value.
- Wikipedia Nyquist frequency
SFInt32 [in, out] bufferLength
bufferLength is length of buffer field in sample-frames.
MFFloat [in, out] buffer [ ] [−1,1]
buffer is a memory-resident audio asset that can contain one or more channels. buffer data format is non-interleaved 32-bit floating-point linear PCM values with a normal range of [−1,1], but values are not limited to this range.
Hint
SFTime [out] bufferDuration 0 [0,∞)
bufferDuration is duration in seconds to use from buffer field.
Hint
- Duration is a nonnegative SFTime duration interval, not an absolute clock time.
SFFloat [in, out] gain 1 (-∞,∞)
The gain field is a factor that represents the amount of linear amplification to apply to the output of the node.
Hint
- Negative gain factors negate the input signal.
Warning
- Decibel values shall not be used.
SFFloat [in, out] detune 0 [0,∞)
The detune field forms a compound field together with playbackRate that together determine a computedPlaybackRate value.
Hint
- ComputedPlaybackRate(t) = playbackRate(t) * pow(2, detune(t) / 1200)
SFFloat [in, out] playbackRate 1 (-∞,∞)
playbackRate field is speed at which to render the audio stream, and forms a compound field together with detune field
Hint
- Negative values play in reverse.
SFTime [in, out] loopStart 0 [0,∞)
loopStart field is optional playhead position where looping begins if loop=true. If loopStart is greater than duration of buffer, looping starts at buffer end.
Hint
- loopStart represents a nonnegative SFTime duration interval, not an absolute clock time.
SFTime [in, out] loopEnd 0 [0,∞)
loopEnd field is optional playhead position where looping ends if loop=true. If loopEnd value is zero, or if loopEnd is greater than duration of buffer, looping ends at buffer end.
Hint
- loopEnd represents a nonnegative SFTime duration interval, not an absolute clock time.
SFInt32 [in, out] channelCount
channelCount reports number of channels provided by input nodes.
Hint
SFString [in, out] channelCountMode “MAX” [“MAX”, “CLAMPED-MAX”, “EXPLICIT”]
channelCountMode determines how individual channels are counted when up-mixing and down-mixing connections to any inputs.
Hint
SFString [in, out] channelInterpretation “SPEAKERS” [“SPEAKERS”, “DISCRETE”]
channelInterpretation determines how individual channels are treated when up-mixing and down-mixing connections to any inputs.
Hint
SFBool [in, out] loop FALSE
Repeat indefinitely when loop=true, repeat only once when loop=false.
SFTime [in, out] startTime 0 (-∞,∞)
Absolute time: number of seconds since January 1, 1970, 00:00:00 GMT.
Hint
- ROUTE a time value matching system clock to this field, such as output event from TouchSensor touchTime or TimeTrigger triggerTime.
SFTime [in, out] resumeTime 0 (-∞,∞)
When resumeTime becomes <= time now, isPaused becomes false and AudioClip becomes active. Absolute time: number of seconds since January 1, 1970, 00:00:00 GMT.
Hint
- ROUTE a time value matching system clock to this field, such as output event from TouchSensor touchTime or TimeTrigger triggerTime.
SFTime [in, out] pauseTime 0 (-∞,∞)
When time now >= pauseTime, isPaused becomes true and AudioClip becomes paused. Absolute time: number of seconds since January 1, 1970, 00:00:00 GMT.
Hint
- ROUTE a time value matching system clock to this field, such as output event from TouchSensor touchTime or TimeTrigger triggerTime.
SFTime [in, out] stopTime 0 (-∞,∞)
Absolute time: number of seconds since January 1, 1970, 00:00:00 GMT.
Hint
- ROUTE a time value matching system clock to this field, such as output event from TouchSensor touchTime or TimeTrigger triggerTime.
Warnings
- An active TimeSensor node ignores set_cycleInterval and set_startTime events.
- An active TimeSensor node ignores set_stopTime event values less than or equal to startTime.
SFBool [out] isPaused
isPaused true/false events are sent when AudioClip is paused/resumed.
Warning
- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
SFBool [out] isActive
isActive true/false events are sent when playback starts/stops.
Warning
- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
SFTime [out] elapsedTime
Current elapsed time since AudioClip activated/running, cumulative in seconds, and not counting any paused time.
Hint
- elapsedTime is a nonnegative SFTime duration interval, not an absolute clock time.
Warning
- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
Supported File Formats
Any audio file format supported by the web browser, but at least:
| Encoding | File Extension | MIME Type |
|---|---|---|
| MP3 | .mp3 | audio/mp3 |
| WAV | .wav | audio/wav |
| OGG | .oga, .ogg | audio/ogg |
Advice
Hint
Warning
- For longer sounds, such as music soundtracks, streaming such as StreamAudioSource should be used.