Post

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:

EncodingFile ExtensionMIME Type
MP3.mp3audio/mp3
WAV.wavaudio/wav
OGG.oga, .oggaudio/ogg

Advice

Hint

Warning

  • For longer sounds, such as music soundtracks, streaming such as StreamAudioSource should be used.

See Also

This post is licensed under CC BY 4.0 by the author.