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 support 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.