Confirmed users
656
edits
Audio Data API Review Version: Difference between revisions
→DOM Implementation
| Line 393: | Line 393: | ||
== DOM Implementation == | == DOM Implementation == | ||
===== nsIDOMNotifyAudioWrittenEvent ===== | ===== nsIDOMNotifyAudioWrittenEvent ===== | ||
| Line 427: | Line 407: | ||
{ | { | ||
// mozFrameBuffer is really a Float32Array, via dom_quickstubs | // mozFrameBuffer is really a Float32Array, via dom_quickstubs | ||
readonly attribute nsIVariant | readonly attribute nsIVariant mozFrameBuffer; | ||
readonly attribute | readonly attribute float mozTime; | ||
}; | }; | ||
</pre> | </pre> | ||
| Line 434: | Line 414: | ||
The '''mozFrameBuffer''' attribute contains a typed array ('''Float32Array''') with the raw audio data (32-bit float values) obtained from decoding the audio (e.g., the raw data being sent to the audio hardware vs. encoded audio). This is of the form <nowiki>[channel1, channel2, ..., channelN, channel1, channel2, ..., channelN, ...]</nowiki>. All audio frames are normalized to a length of channels * 1024 by default, but could be any power of 2 between 512 and 32768 if the user has set a different size using '''mozSetFrameBufferSize()'''. | The '''mozFrameBuffer''' attribute contains a typed array ('''Float32Array''') with the raw audio data (32-bit float values) obtained from decoding the audio (e.g., the raw data being sent to the audio hardware vs. encoded audio). This is of the form <nowiki>[channel1, channel2, ..., channelN, channel1, channel2, ..., channelN, ...]</nowiki>. All audio frames are normalized to a length of channels * 1024 by default, but could be any power of 2 between 512 and 32768 if the user has set a different size using '''mozSetFrameBufferSize()'''. | ||
The '''mozTime''' attribute contains | The '''mozTime''' attribute contains a float representing the time in seconds since the start. | ||
===== | ===== nsIDOMHTMLMediaElement additions ===== | ||
Audio metadata is made available via three new attributes on the HTMLMediaElement. By default these attributes have a value of 0 (zero), until the '''LoadedMetadata''' occurs. Users who need this info before the audio starts playing should not use '''autoplay''', since the audio might start before a loadmetadata handler has run. | |||
The three new attributes are defined as follows: | |||
<pre> | <pre> | ||
readonly attribute unsigned long mozChannels; | |||
readonly attribute unsigned long mozSampleRate; | |||
attribute unsigned long mozFrameBufferLength; | |||
</pre> | |||
The '''mozChannels''' attribute contains the number of channels in the audio resource (e.g., 2). The '''mozSampleRate''' attribute contains the number of samples per second that will be played, for example 44100. Both are readonly. | |||
The '''mozFrameBufferLength''' attribute indicates the number of samples that will be returned in the framebuffer of each '''AudioWritten''' event. This number is a total for all channels, and by default is set to be the number of channels * 1024 (e.g., 2 channels * 1024 samples = 2048 total). | |||
The '''mozFrameBufferLength''' attribute can also be set to a new value, if users want lower latency, or larger amounts of data, etc. The size you give '''must''' be a power of 2 between 512 and 32768. The following are all valid lengths: | |||
* 512 | |||
* 1024 | |||
* 2048 | |||
* 4096 | |||
* 8192 | |||
* 16384 | |||
* 32768 | |||
Using any other size will result in an exception being thrown. The best time to set a new length is after the '''loadedmetadata''' event fires, when the audio info is known, but before the audio has started or '''AudioWritten''' events begun firing. | |||
===== nsIDOMHTMLAudioElement additions ===== | |||
The HTMLAudioElement has also been extended to allow write access. Audio writing is achieved by adding three new methods: | |||
<pre> | |||
void mozSetup(in long channels, in long rate, in float volume); | |||
unsigned long mozWriteAudio(array); // array is Array() or Float32Array() | |||
unsigned long long mozCurrentSampleOffset(); | |||
</pre> | </pre> | ||
| Line 468: | Line 472: | ||
The '''mozCurrentSampleOffset()''' method can be called after '''mozSetup()'''. It returns the current position (measured in samples) of the audio stream. This is useful when determining how much data to write with '''mozWriteAudio()'''. | The '''mozCurrentSampleOffset()''' method can be called after '''mozSetup()'''. It returns the current position (measured in samples) of the audio stream. This is useful when determining how much data to write with '''mozWriteAudio()'''. | ||
All of '''mozWriteAudio()''', '''mozCurrentSampleOffset()''', and '''mozSetup()''' will throw exceptions if called out of order. '''mozSetup()''' will also throw if a ''src'' attribute has previously been set on the audio element (i.e., you can't do both at the same time). | |||
== Additional Resources == | == Additional Resources == | ||