Web Audio API 1.1

引言

Web 上的音频技术在这一点之前一直相当原始，直到最近还不得不通过 Flash 和 QuickTime 等插件进行交付。HTML5 中 audio 元素的引入非常重要，它实现了基本的流式音频播放。但是，它不足以处理更复杂的音频应用。对于复杂的 Web 游戏或交互式应用程序，需要另一种解决方案。本规范的目标之一是包含现代游戏音频引擎中的功能，以及现代桌面音频制作应用程序中常见的混音、处理和滤波任务。

这些 API 在设计时考虑了各种各样的用例 [webaudio-usecases]。理想情况下，它应该能够支持任何能够合理地通过脚本控制、在浏览器中运行的优化 C++ 引擎所能实现的功能。话虽如此，现代桌面音频软件可能具有非常先进的功能，其中一些用本系统构建将很困难或不可能。Apple 的 Logic Audio 就是这样一种应用程序，它支持外部 MIDI 控制器、任意插件音频效果和合成器、高度优化的直接到磁盘音频文件读写、紧密集成的变速变调等等。尽管如此，本系统将完全有能力支持大量的、相当复杂的游戏和交互式应用程序，包括音乐类的。它还可以作为 WebGL 提供的更高级图形功能的良好补充。该 API 的设计旨在让更高级的功能可以在以后添加。

特性

本 API 支持以下主要特性：

• 模块化路由，用于简单或复杂的混音/效果架构。

• 高动态范围，内部处理使用 32 位浮点数。

• 采样精确的调度声音播放，并具有低延迟，适用于对节奏精度要求极高的音乐应用（如鼓机和定序器）。这还包括动态创建效果的可能性。

• 音频参数的自动化，适用于包络、淡入/淡出、颗粒效果、滤波器扫描、LFO 等。

• 音频流中声道的灵活处理，允许拆分和合并。

• 处理来自 audio 或 video 媒体元素 的音频源。

• 使用来自 getUserMedia() 的 MediaStream 处理实时音频输入。

• 与 WebRTC 集成。

  • 使用 MediaStreamTrackAudioSourceNode 和 [webrtc] 处理从远程对端接收的音频。

  • 使用 MediaStreamAudioDestinationNode 和 [webrtc] 将生成的或处理后的音频流发送到远程对端。

• 直接使用脚本进行音频流合成和处理。

• 空间化音频，支持各种 3D 游戏和沉浸式环境。

  • 声像定位模型：equalpower (等功率)、HRTF、pass-through (直通)。

  • 距离衰减。

  • 声锥。

  • 遮挡 / 掩蔽。

  • 基于源 / 监听者。

• 用于各种线性效果的卷积引擎，特别是极高质量的室内效果。以下是可能效果的一些示例：

  • 小 / 大房间

  • 大教堂

  • 音乐厅

  • 洞穴

  • 隧道

  • 走廊

  • 森林

  • 露天剧场

  • 通过门口传来的远距离房间声音

  • 极端滤波器

  • 奇异的反向效果

  • 极端梳状滤波器效果

• 用于整体控制和优化混音的动态压缩。

• 高效的实时时域和频域分析 / 音乐可视化支持。

• 用于低通、高通和其他常见滤波的高效双二阶滤波器。

• 用于失真和其他非线性效果的波形塑形效果。

• 振荡器。

模块化路由。

模块化路由允许在不同的 AudioNode 对象之间建立任意连接。每个节点都可以有输入和/或输出。源节点没有输入，只有一个输出。目标节点有一个输入，没有输出。其他节点（如滤波器）可以放置在源节点和目标节点之间。当两个对象连接在一起时，开发人员不必担心低级别的流格式细节；系统会自动处理。例如，如果单声道音频流连接到立体声输入，它应该恰当地混合到左声道和右声道。

在最简单的情况下，单个源可以直接路由到输出。所有路由都在包含一个 AudioDestinationNode 的 AudioContext 内进行。

为了说明这种简单的路由，这里有一个播放单个声音的简单示例。

const context = new AudioContext();

function playSound() {
    const source = context.createBufferSource();
    source.buffer = dogBarkingBuffer;
    source.connect(context.destination);
    source.start(0);
}

这是一个更复杂的示例，包含三个源和一个卷积混响发送，在最终输出阶段带有一个动态压缩器。

let context;let compressor;let reverb;let source1, source2, source3;let lowpassFilter;let waveShaper;let panner;let dry1, dry2, dry3;let wet1, wet2, wet3;let mainDry;let mainWet;function setupRoutingGraph () {    context = new AudioContext();    // Create the effects nodes.    lowpassFilter = context.createBiquadFilter();    waveShaper = context.createWaveShaper();    panner = context.createPanner();    compressor = context.createDynamicsCompressor();    reverb = context.createConvolver();    // Create main wet and dry.    mainDry = context.createGain();    mainWet = context.createGain();    // Connect final compressor to final destination.    compressor.connect(context.destination);    // Connect main dry and wet to compressor.    mainDry.connect(compressor);    mainWet.connect(compressor);    // Connect reverb to main wet.    reverb.connect(mainWet);    // Create a few sources.    source1 = context.createBufferSource();    source2 = context.createBufferSource();    source3 = context.createOscillator();    source1.buffer = manTalkingBuffer;    source2.buffer = footstepsBuffer;    source3.frequency.value = 440;    // Connect source1    dry1 = context.createGain();    wet1 = context.createGain();    source1.connect(lowpassFilter);    lowpassFilter.connect(dry1);    lowpassFilter.connect(wet1);    dry1.connect(mainDry);    wet1.connect(reverb);    // Connect source2    dry2 = context.createGain();    wet2 = context.createGain();    source2.connect(waveShaper);    waveShaper.connect(dry2);    waveShaper.connect(wet2);    dry2.connect(mainDry);    wet2.connect(reverb);    // Connect source3    dry3 = context.createGain();    wet3 = context.createGain();    source3.connect(panner);    panner.connect(dry3);    panner.connect(wet3);    dry3.connect(mainDry);    wet3.connect(reverb);    // Start the sources now.    source1.start(0);    source2.start(0);    source3.start(0);}

模块化路由还允许将 AudioNode 的输出路由到控制另一个 AudioNode 行为的 AudioParam 参数。在这种情况下，节点的输出可以作为调制信号，而不是输入信号。

function setupRoutingGraph() {    const context = new AudioContext();    // Create the low frequency oscillator that supplies the modulation signal    const lfo = context.createOscillator();    lfo.frequency.value = 1.0;    // Create the high frequency oscillator to be modulated    const hfo = context.createOscillator();    hfo.frequency.value = 440.0;    // Create a gain node whose gain determines the amplitude of the modulation signal    const modulationGain = context.createGain();    modulationGain.gain.value = 50;    // Configure the graph and start the oscillators    lfo.connect(modulationGain);    modulationGain.connect(hfo.detune);    hfo.connect(context.destination);    hfo.start(0);    lfo.start(0);}

API 概览

定义的接口包括：

• 一个 AudioContext 接口，包含一个代表 AudioNode 之间连接的音频信号图。

• 一个 AudioNode 接口，代表音频源、音频输出和中间处理模块。AudioNode 可以以模块化方式动态连接在一起。AudioNode 存在于 AudioContext 的上下文中。

• 一个 AnalyserNode 接口，一种用于音乐可视化或其他可视化应用的 AudioNode。

• 一个 AudioBuffer 接口，用于处理内存驻留的音频资产。这些可以代表单次播放的声音，或较长的音频剪辑。

• 一个 AudioBufferSourceNode 接口，一种从 AudioBuffer 生成音频的 AudioNode。

• 一个 AudioDestinationNode 接口，一个代表所有渲染音频最终目的地的 AudioNode 子类。

• 一个 AudioParam 接口，用于控制 AudioNode 功能的各个方面，如音量。

• 一个 AudioListener 接口，与 PannerNode 配合使用进行空间化。

• 一个 AudioWorklet 接口，代表用于创建自定义节点的工厂，这些节点可以直接使用脚本处理音频。

• 一个 AudioWorkletGlobalScope 接口，即 AudioWorkletProcessor 处理脚本运行的上下文。

• 一个 AudioWorkletNode 接口，一种代表在 AudioWorkletProcessor 中处理的节点的 AudioNode。

• 一个 AudioWorkletProcessor 接口，代表音频 worker 内部的单个节点实例。

• 一个 BiquadFilterNode 接口，一种用于常见低阶滤波器的 AudioNode，例如：

  • 低通

  • 高通

  • 带通

  • 低频搁架滤波器

  • 高频搁架滤波器

  • 峰值滤波器

  • 陷波滤波器

  • 全通滤波器

• 一个 ChannelMergerNode 接口，一种用于将来自多个音频流的声道合并为单个音频流的 AudioNode。

• 一个 ChannelSplitterNode 接口，一种用于在路由图中访问音频流各个声道的 AudioNode。

• 一个 ConstantSourceNode 接口，一种用于生成名义上恒定的输出值的 AudioNode，带有 AudioParam 以允许对该值进行自动化。

• 一个 ConvolverNode 接口，一种用于应用实时线性效果（如音乐厅的声音）的 AudioNode。

• 一个 DelayNode 接口，一种应用动态可调延迟的 AudioNode。

• 一个 DynamicsCompressorNode 接口，一种用于动态压缩的 AudioNode。

• 一个 GainNode 接口，一种用于显式增益控制的 AudioNode。

• 一个 IIRFilterNode 接口，一种通用 IIR 滤波器的 AudioNode。

• 一个 MediaElementAudioSourceNode 接口，一种来自 audio、video 或其他媒体元素的音频源 AudioNode。

• 一个 MediaStreamAudioSourceNode 接口，一种来自 MediaStream（如实时音频输入或远程对端）的音频源 AudioNode。

• 一个 MediaStreamTrackAudioSourceNode 接口，一种来自 MediaStreamTrack 的音频源 AudioNode。

• 一个 MediaStreamAudioDestinationNode 接口，一种用于发送到远程对端的 MediaStream 的音频目的地 AudioNode。

• 一个 PannerNode 接口，一种用于在 3D 空间中进行空间化/定位音频的 AudioNode。

• 一个 PeriodicWave 接口，用于指定供 OscillatorNode 使用的自定义周期性波形。

• 一个 OscillatorNode 接口，一种用于生成周期性波形的 AudioNode。

• 一个 StereoPannerNode 接口，一种用于在立体声流中进行等功率音频输入定位的 AudioNode。

• 一个 WaveShaperNode 接口，一种应用非线性波形塑形效果以产生失真和其他更微妙温和效果的 AudioNode。

还有一些功能已从 Web Audio API 中弃用，但尚未移除，等待其替代品的实现经验。

• 一个 ScriptProcessorNode 接口，一种直接使用脚本生成或处理音频的 AudioNode。

• 一个 AudioProcessingEvent 接口，这是与 ScriptProcessorNode 对象一起使用的事件类型。

1. 音频 API

1.1. BaseAudioContext 接口

此接口代表一组 AudioNode 对象及其连接。它允许将信号任意路由到 AudioDestinationNode。节点从上下文创建，然后连接在一起。

BaseAudioContext 不直接实例化，而是由具体接口 AudioContext（用于实时渲染）和 OfflineAudioContext（用于离线渲染）扩展。

BaseAudioContext 创建时带有一个内部槽 [[pending promises]]，它是一个最初为空的有序 Promise 列表。

每个 BaseAudioContext 都有一个唯一的 媒体元素事件任务源。此外，BaseAudioContext 还有几个私有槽 [[rendering thread state]] 和 [[control thread state]]，它们取自 AudioContextState，并且初始都设置为 "suspended"，以及一个私有槽 [[render quantum size]]，它是一个无符号整数。

enum AudioContextState {
    "suspended",
    "running",
    "closed"
};

enum AudioContextRenderSizeCategory {
    "default",
    "hardware"
};

callback DecodeErrorCallback = undefined (DOMException error);

callback DecodeSuccessCallback = undefined (AudioBuffer decodedData);

[Exposed=Window]
interface BaseAudioContext : EventTarget {
    readonly attribute AudioDestinationNode destination;
    readonly attribute float sampleRate;
    readonly attribute double currentTime;
    readonly attribute AudioListener listener;
    readonly attribute AudioContextState state;
    readonly attribute unsigned long renderQuantumSize;
    [SameObject, SecureContext]
    readonly attribute AudioWorklet audioWorklet;
    attribute EventHandler onstatechange;

    AnalyserNode createAnalyser ();
    BiquadFilterNode createBiquadFilter ();
    AudioBuffer createBuffer (unsigned long numberOfChannels,
                                unsigned long length,
                                float sampleRate);
    AudioBufferSourceNode createBufferSource ();
    ChannelMergerNode createChannelMerger (optional unsigned long numberOfInputs = 6);
    ChannelSplitterNode createChannelSplitter (
        optional unsigned long numberOfOutputs = 6);
    ConstantSourceNode createConstantSource ();
    ConvolverNode createConvolver ();
    DelayNode createDelay (optional double maxDelayTime = 1.0);
    DynamicsCompressorNode createDynamicsCompressor ();
    GainNode createGain ();
    IIRFilterNode createIIRFilter (sequence<double> feedforward,
                                    sequence<double> feedback);
    OscillatorNode createOscillator ();
    PannerNode createPanner ();
    PeriodicWave createPeriodicWave (sequence<float> real,
                                        sequence<float> imag,
                                        optional PeriodicWaveConstraints constraints = {});
    ScriptProcessorNode createScriptProcessor(
        optional unsigned long bufferSize = 0,
        optional unsigned long numberOfInputChannels = 2,
        optional unsigned long numberOfOutputChannels = 2);
    StereoPannerNode createStereoPanner ();
    WaveShaperNode createWaveShaper ();

    Promise<AudioBuffer> decodeAudioData (
        ArrayBuffer audioData,
        optional DecodeSuccessCallback? successCallback,
        optional DecodeErrorCallback? errorCallback);
};

1.1.1. 属性

audioWorklet, 类型 AudioWorklet, 只读

允许访问 Worklet 对象，该对象可以通过 [HTML] 和 AudioWorklet 定义的算法导入包含 AudioWorkletProcessor 类定义的脚本。

currentTime, 类型 double, 只读

这是紧随上下文渲染图最近处理的音频块中最后一个采样帧之后的采样帧的时间（以秒为单位）。如果上下文的渲染图尚未处理音频块，则 currentTime 的值为零。

在 currentTime 的时间坐标系中，零值对应于图中处理的第一个块中的第一个采样帧。此系统中的已过时间对应于 BaseAudioContext 生成的音频流中的已过时间，它可能与其他系统时钟不同步。（对于 OfflineAudioContext，由于流没有被任何设备主动播放，甚至不存在对实时时间的近似。）

Web Audio API 中的所有调度时间均相对于 currentTime 的值。

当 BaseAudioContext 处于 "running" 状态时，此属性的值单调递增，并由渲染线程以统一的增量（对应于一个渲染量子）进行更新。因此，对于运行中的上下文，currentTime 随着系统处理音频块而稳定增加，并始终代表下一个要处理的音频块的开始时间。这也是当前状态下调度任何更改可能生效的最早时间。

在返回之前，currentTime 必须在控制线程上原子地读取。

destination, 类型 AudioDestinationNode, 只读

一个带有单个输入的 AudioDestinationNode，代表所有音频的最终目的地。通常这将代表实际的音频硬件。所有主动渲染音频的 AudioNode 都将直接或间接地连接到 destination。

listener, 类型 AudioListener, 只读

一个用于 3D 空间化的 AudioListener。

onstatechange, 类型 EventHandler

一个用于为事件设置事件处理程序的属性，该事件在 AudioContext 状态发生变化（即相应 promise 应该解析时）时分发给 BaseAudioContext。此事件处理程序的事件类型为 statechange。一个使用 Event 接口的事件将分发给该事件处理程序，它可以直接查询 AudioContext 的状态。一个新创建的 AudioContext 将始终以 suspended 状态开始，每当状态变为不同状态时，都会触发一个状态更改事件。此事件在 complete 事件触发之前触发。

sampleRate, 类型 float, 只读

BaseAudioContext 处理音频的采样率（每秒采样帧数）。假设上下文中的所有 AudioNode 都以此速率运行。基于此假设，实时处理中不支持采样率转换器或“变速”处理器。奈奎斯特频率 (Nyquist frequency) 是此采样率值的一半。

state, 类型 AudioContextState, 只读

描述 BaseAudioContext 的当前状态。获取此属性会返回 [[control thread state]] 槽的内容。

renderQuantumSize, 类型 unsigned long, 只读

获取此属性会返回 [[render quantum size]] 槽的值。

1.1.2. 方法

createAnalyser()

工厂方法，用于创建一个 AnalyserNode。

无参数。

返回类型： AnalyserNode

createBiquadFilter()

工厂方法，用于创建一个代表二阶滤波器的 BiquadFilterNode，该滤波器可配置为多种常见滤波器类型之一。

无参数。

返回类型： BiquadFilterNode

createBuffer(numberOfChannels, length, sampleRate)

创建一个给定大小的 AudioBuffer。缓冲区中的音频数据将被零初始化（静音）。如果任何参数为负数、零或超出其标称范围，则必须抛出 NotSupportedError 异常。

BaseAudioContext.createBuffer() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
numberOfChannels	unsigned long	✘	✘	确定缓冲区将具有多少个声道。实现必须至少支持 32 个声道。
length	unsigned long	✘	✘	确定缓冲区的大小（以采样帧为单位）。这必须至少为 1。
sampleRate	float	✘	✘	描述缓冲区中线性 PCM 音频数据的采样率（以每秒采样帧数为单位）。实现必须至少支持 8000 到 96000 范围内的采样率。

返回类型： AudioBuffer

createBufferSource()

工厂方法，用于创建一个 AudioBufferSourceNode。

无参数。

返回类型： AudioBufferSourceNode

createChannelMerger(numberOfInputs)

工厂方法，用于创建一个代表声道合并器的 ChannelMergerNode。如果 numberOfInputs 小于 1 或大于支持的声道数，则必须抛出 IndexSizeError 异常。

BaseAudioContext.createChannelMerger(numberOfInputs) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
numberOfInputs	unsigned long	✘	✔	确定输入数量。必须支持最多 32 个输入。如果未指定，则使用 6。

返回类型： ChannelMergerNode

createChannelSplitter(numberOfOutputs)

工厂方法，用于创建一个代表声道拆分器的 ChannelSplitterNode。如果 numberOfOutputs 小于 1 或大于支持的声道数，则必须抛出 IndexSizeError 异常。

BaseAudioContext.createChannelSplitter(numberOfOutputs) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
numberOfOutputs	unsigned long	✘	✔	输出数量。必须支持最多 32 个输出。如果未指定，则使用 6。

返回类型： ChannelSplitterNode

createConstantSource()

工厂方法，用于创建一个 ConstantSourceNode。

无参数。

返回类型： ConstantSourceNode

createConvolver()

工厂方法，用于创建一个 ConvolverNode。

无参数。

返回类型： ConvolverNode

createDelay(maxDelayTime)

工厂方法，用于创建一个 DelayNode。初始默认延迟时间为 0 秒。

BaseAudioContext.createDelay(maxDelayTime) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
maxDelayTime	double	✘	✔	指定允许延迟线使用的最大延迟时间（以秒为单位）。如果指定，该值必须大于零且小于三分钟，否则必须抛出 NotSupportedError 异常。如果未指定，则使用 1。

返回类型： DelayNode

createDynamicsCompressor()

工厂方法，用于创建一个 DynamicsCompressorNode。

无参数。

返回类型： DynamicsCompressorNode

createGain()

工厂方法，用于 GainNode。

无参数。

返回类型： GainNode

createIIRFilter(feedforward, feedback)

BaseAudioContext.createIIRFilter() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
feedforward	sequence<double>	✘	✘	IIR 滤波器传递函数的前馈（分子）系数数组。此数组的最大长度为 20。如果所有值均为零，必须抛出 InvalidStateError。如果数组长度为 0 或大于 20，必须抛出 NotSupportedError。
feedback	sequence<double>	✘	✘	IIR 滤波器传递函数的反馈（分母）系数数组。此数组的最大长度为 20。如果数组的第一个元素为 0，必须抛出 InvalidStateError。如果数组长度为 0 或大于 20，必须抛出 NotSupportedError。

返回类型： IIRFilterNode

createOscillator()

工厂方法，用于创建一个 OscillatorNode。

无参数。

返回类型： OscillatorNode

createPanner()

工厂方法，用于创建一个 PannerNode。

无参数。

返回类型： PannerNode

createPeriodicWave(real, imag, constraints)

工厂方法，用于创建一个 PeriodicWave。

调用此方法时，请执行以下步骤：

1. 如果 real 和 imag 长度不一致，则必须抛出 IndexSizeError。

2. 令 o 为一个新的 PeriodicWaveOptions 类型对象。

3. 分别将传递给此工厂方法的 real 和 imag 参数设置为 o 上同名属性的值。

4. 将 o 上的 disableNormalization 属性设置为传递给该工厂方法的 constraints 属性的 disableNormalization 属性值。

5. 构造一个新的 PeriodicWave 对象 p，将调用此工厂方法的 BaseAudioContext 作为第一个参数传入，以及 o。

6. 返回 p。

BaseAudioContext.createPeriodicWave() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
real	sequence<float>	✘	✘	余弦参数序列。有关更详细的描述，请参见其 real 构造函数参数。
imag	sequence<float>	✘	✘	正弦参数序列。有关更详细的描述，请参见其 imag 构造函数参数。
constraints	PeriodicWaveConstraints	✘	✔	如果不提供，波形将被归一化。否则，波形将根据 constraints 给出的值进行归一化。

返回类型： PeriodicWave

createScriptProcessor(bufferSize, numberOfInputChannels, numberOfOutputChannels)

ScriptProcessorNode 的工厂方法。此方法已弃用，旨在被 AudioWorkletNode 取代。创建用于通过脚本进行直接音频处理的 ScriptProcessorNode。如果 bufferSize、numberOfInputChannels 或 numberOfOutputChannels 超出有效范围，则必须抛出 IndexSizeError 异常。

numberOfInputChannels 和 numberOfOutputChannels 同时为零是不合法的。在这种情况下，必须抛出 IndexSizeError。

BaseAudioContext.createScriptProcessor(bufferSize, numberOfInputChannels, numberOfOutputChannels) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
bufferSize	unsigned long	✘	✔	bufferSize 参数决定了缓冲区的大小（以采样帧为单位）。如果不传递该值，或者如果该值为 0，实现将根据给定环境选择最佳的缓冲区大小，该值在节点生命周期内将保持为 2 的幂。如果作者明确指定了 bufferSize，则它必须是以下值之一：256、512、1024、2048、4096、8192、16384。此值控制 audioprocess 事件的分发频率以及每次调用需要处理多少采样帧。较低的 bufferSize 值会导致更低（更好）的延迟。更高的值对于避免音频中断和故障是必要的。建议作者不要指定此缓冲区大小，而应让实现选择一个好的缓冲区大小，以平衡延迟和音频质量。如果该参数的值不是上述列出的允许的 2 的幂值之一，则必须抛出 IndexSizeError。
numberOfInputChannels	unsigned long	✘	✔	此参数确定此节点的输入通道数。默认值为 2。必须支持最多 32 个通道。如果不支持通道数，则必须抛出 NotSupportedError。
numberOfOutputChannels	unsigned long	✘	✔	此参数确定此节点的输出通道数。默认值为 2。必须支持最多 32 个通道。如果不支持通道数，则必须抛出 NotSupportedError。

返回类型： ScriptProcessorNode

createStereoPanner()

StereoPannerNode 的工厂方法。

无参数。

返回类型： StereoPannerNode

createWaveShaper()

表示非线性失真的 WaveShaperNode 的工厂方法。

无参数。

返回类型： WaveShaperNode

decodeAudioData(audioData, successCallback, errorCallback)

异步解码 ArrayBuffer 中包含的音频文件数据。ArrayBuffer 例如可以在将 responseType 设置为 "arraybuffer" 后从 XMLHttpRequest 的 response 属性加载。音频文件数据可以是 audio 元素支持的任何格式。传递给 decodeAudioData() 的缓冲区其内容类型由嗅探确定，如 [mimesniff] 中所述。

虽然与此函数交互的主要方法是通过其返回的 Promise 值，但仍出于遗留原因提供了回调参数。

鼓励实现在文件损坏时警告作者。无法抛出异常，因为这会是一个破坏性更改。

注意：如果压缩的音频数据字节流已损坏，但解码仍可继续，则鼓励实现通过开发人员工具等方式警告作者。

当调用 decodeAudioData 时，必须在控制线程上执行以下步骤

1. 如果 this 的 相关全局对象的 关联文档不是 完全活跃的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

2. 设 promise 为一个新的 Promise。

3. 如果 audioData 已分离，执行以下步骤

   1. 将 promise 添加到 [[pending promises]] 中。

   2. 分离 audioData ArrayBuffer。如果此操作抛出异常，跳转至第 3 步。

   3. 将解码操作排队，以便在另一个线程上执行。

4. 否则，执行以下错误步骤

   1. 令 error 为 DataCloneError。

   2. 使用 error 拒绝 promise，并将其从 [[pending promises]] 中移除。

   3. 排队一个媒体元素任务，以使用 error 调用 errorCallback。

5. 返回 promise。

当排队一个要在另一个线程上执行的解码操作时，以下步骤必须在一个既不是控制线程也不是渲染线程的线程上发生，该线程称为 解码线程。

注意： 多个 解码线程 可以并行运行，以服务于对 decodeAudioData 的多次调用。

1. 令 can decode 为一个布尔标志，初始设置为 true。

2. 尝试使用 MIME 嗅探 § 6.2 匹配音频或视频类型模式来确定 audioData 的 MIME 类型。如果音频或视频类型模式匹配算法返回 undefined，则将 can decode 设置为 false。

3. 如果 can decode 为 true，尝试将编码后的 audioData 解码为 线性 PCM。如果失败，将 can decode 设置为 false。

   如果媒体字节流包含多个音频轨道，则仅将第一个轨道解码为 线性 pcm。

   注意： 需要对解码过程有更多控制的作者可以使用 [WEBCODECS]。

4. 如果 can decode 为 false， 排队一个媒体元素任务以执行以下步骤

   1. 令 error 为一个名称为 EncodingError 的 DOMException。

      2. 使用 error 拒绝 promise，并将其从 [[pending promises]] 中移除。

   2. 如果 errorCallback 未缺失，则使用 error 调用 errorCallback。

5. 否则

   1. 获取表示解码后的 线性 PCM 音频数据的结果，如果其采样率与 audioData 的采样率不同，则将其重采样为 BaseAudioContext 的采样率。

   2. 排队一个媒体元素任务以执行以下步骤

      1. 令 buffer 为包含最终结果（在可能执行重采样后）的 AudioBuffer。

      2. 使用 buffer 解析 promise。

      3. 如果 successCallback 未缺失，则使用 buffer 调用 successCallback。

BaseAudioContext.decodeAudioData() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
audioData	ArrayBuffer	✘	✘	包含压缩音频数据的 ArrayBuffer。
successCallback	DecodeSuccessCallback?	✔	✔	解码完成时调用的回调函数。此回调的唯一参数是一个 AudioBuffer，表示解码后的 PCM 音频数据。
errorCallback	DecodeErrorCallback?	✔	✔	如果解码音频文件时出现错误，将调用的回调函数。

返回类型： Promise<AudioBuffer>

1.1.3. 回调 DecodeSuccessCallback() 参数

decodedData，类型为 AudioBuffer

包含解码后的音频数据的 AudioBuffer。

1.1.4. 回调 DecodeErrorCallback() 参数

error，类型为 DOMException

解码时发生的错误。

1.1.5. 生命周期

一旦创建，AudioContext 将持续播放声音，直到没有声音可播放，或者页面关闭。

1.1.6. 缺乏内省或序列化原语

Web Audio API 对音频源调度采取发后即忘的方法。也就是说，在 AudioContext 的生命周期内，每个音符都会创建源节点，并且永远不会显式地从图中移除。这与序列化 API 不兼容，因为没有一组可以序列化的稳定节点。

此外，拥有内省 API 将允许内容脚本能够观察垃圾回收。

1.1.7. 与 BaseAudioContext 子类关联的系统资源

子类 AudioContext 和 OfflineAudioContext 应被视为昂贵的对象。创建这些对象可能涉及创建高优先级线程，或使用低延迟系统音频流，这两者都会对能源消耗产生影响。在一个文档中通常没有必要创建多个 AudioContext。

构建或恢复 BaseAudioContext 子类涉及获取该上下文的系统资源。对于 AudioContext，这还需要创建一个系统音频流。当上下文开始从其关联的音频图中生成输出时，这些操作返回。

此外，用户代理可以具有实现定义的 AudioContext 最大数量，超过该数量后，任何创建新 AudioContext 的尝试都将失败，并抛出 NotSupportedError。

suspend 和 close 允许作者释放系统资源，包括线程、进程和音频流。挂起 BaseAudioContext 允许实现释放其部分资源，并允许通过调用 resume 稍后继续操作。关闭 AudioContext 允许实现释放其所有资源，之后它将无法再次使用或恢复。

Note: 例如，这可能涉及等待音频回调定期触发，或等待硬件准备好进行处理。

1.2. AudioContext 接口

此接口表示一个音频图，其 AudioDestinationNode 被路由到产生导向用户的信号的实时输出设备。在大多数用例中，每个文档仅使用单个 AudioContext。

enum AudioContextLatencyCategory {
        "balanced",
        "interactive",
        "playback"
};

enum AudioSinkType {
    "none"
};

[Exposed=Window]
interface AudioContext : BaseAudioContext {
    constructor (optional AudioContextOptions contextOptions = {});
    readonly attribute double baseLatency;
    readonly attribute double outputLatency;
    [SecureContext] readonly attribute (DOMString or AudioSinkInfo) sinkId;
    [SecureContext] readonly attribute AudioRenderCapacity renderCapacity;
    attribute EventHandler onsinkchange;
    attribute EventHandler onerror;
    AudioTimestamp getOutputTimestamp ();
    Promise<undefined> resume ();
    Promise<undefined> suspend ();
    Promise<undefined> close ();
    [SecureContext] Promise<undefined> setSinkId ((DOMString or AudioSinkOptions) sinkId);
    MediaElementAudioSourceNode createMediaElementSource (HTMLMediaElement mediaElement);
    MediaStreamAudioSourceNode createMediaStreamSource (MediaStream mediaStream);
    MediaStreamTrackAudioSourceNode createMediaStreamTrackSource (
        MediaStreamTrack mediaStreamTrack);
    MediaStreamAudioDestinationNode createMediaStreamDestination ();
};

如果用户代理允许上下文状态从 "suspended" 转换为 "running"，则称 AudioContext 被允许启动。用户代理可以禁止此初始转换，并仅当 AudioContext 的 相关全局对象具有 粘性激活时才允许它。

AudioContext 具有以下内部槽位

[[suspended by user]]

一个布尔标志，表示上下文是否由用户代码挂起。初始值为 false。

[[sink ID]]

一个分别表示当前音频输出设备标识符或信息的 DOMString 或 AudioSinkInfo。初始值为 ""，表示默认音频输出设备。

[[pending resume promises]]

用于存储由 resume() 创建的挂起 Promise 的有序列表。它最初为空。

1.2.1. 构造函数

AudioContext(contextOptions)

如果 当前设置对象的 相关全局对象的 关联文档不是 完全活跃的，抛出一个 "InvalidStateError" 并中止这些步骤。

创建 AudioContext 时，执行这些步骤

1. 令 context 为一个新的 AudioContext 对象。

2. 在 context 上设置一个 [[控制线程状态]] 为 suspended。

3. 在 context 上设置一个 [[渲染线程状态]] 为 suspended。

4. 令 messageChannel 为一个新的 MessageChannel。

5. 令 controlSidePort 为 messageChannel 的 port1 属性的值。

6. 令 renderingSidePort 为 messageChannel 的 port2 属性的值。

7. 令 serializedRenderingSidePort 为 StructuredSerializeWithTransfer(renderingSidePort, « renderingSidePort ») 的结果。

8. 将此 audioWorklet 的 port 设置为 controlSidePort。

9. 排队一个控制消息，以在 AudioContextGlobalScope 上设置 MessagePort，使用 serializedRenderingSidePort。

10. 如果提供了 contextOptions，执行以下子步骤

    1. 如果指定了 sinkId，令 sinkId 为 contextOptions.sinkId 的值，并运行以下子步骤

       1. 如果 sinkId 和 [[sink ID]] 均为 DOMString 类型，且它们彼此相等，中止这些子步骤。

       2. 如果 sinkId 为 AudioSinkOptions 类型，而 [[sink ID]] 为 AudioSinkInfo 类型，且 sinkId 中的 type 与 [[sink ID]] 中的 type 相等，中止这些子步骤。

       3. 令 validationResult 为 sink 标识符验证 sinkId 的返回值。

       4. 如果 validationResult 为 DOMException 类型，抛出一个带有 validationResult 的异常并中止这些子步骤。

       5. 如果 sinkId 为 DOMString 类型，将 [[sink ID]] 设置为 sinkId 并中止这些子步骤。

       6. 如果 sinkId 为 AudioSinkOptions 类型，将 [[sink ID]] 设置为使用 sinkId 的 type 值创建的 AudioSinkInfo 的新实例。

    2. 根据 contextOptions.latencyHint 设置 context 的内部延迟，如 latencyHint 中所述。

    3. 如果指定了 contextOptions.sampleRate ，将 context 的 sampleRate 设置为此值。否则，遵循这些子步骤

       1. 如果 sinkId 是空字符串或 AudioSinkOptions 类型，使用默认输出设备的采样率。中止这些子步骤。

       2. 如果 sinkId 为 DOMString，使用 sinkId 标识的输出设备的采样率。中止这些子步骤。

       如果 contextOptions.sampleRate 与输出设备的采样率不同，用户代理必须对音频输出进行重采样以匹配输出设备的采样率。

       Note: 如果需要重采样，context 的延迟可能会受到影响，可能幅度很大。

11. 如果 context 被允许启动，发送一个控制消息以开始处理。

12. 返回 context。

发送一个控制消息以开始处理意味着执行以下步骤

1. 令 document 为 当前设置对象的 相关全局对象的 关联文档。

2. 尝试获取系统资源，以根据 [[sink ID]] 使用以下音频输出设备进行渲染

   • 空字符串的默认音频输出设备。

   • 由 [[sink ID]] 标识的音频输出设备。

   1. 如果资源获取失败，执行以下步骤

      1. 如果 document 不被允许使用由 "speaker-selection" 标识的功能，中止这些子步骤。

      2. 排队一个媒体元素任务，以在 AudioContext 上触发一个名为 error 的事件，并中止以下步骤。

3. 在 AudioContext 上设置 this 的 [[渲染线程状态]] 为 running。

4. 排队一个媒体元素任务以执行以下步骤

   1. 将 AudioContext 的 state 属性设置为 "running"。

   2. 在 AudioContext 上触发一个名为 statechange 的事件。

NOTE: 在 AudioContext 无参数构造且资源获取失败的情况下，用户代理将尝试使用模拟音频输出设备的机制静默渲染音频图。

发送一个控制消息以在 AudioWorkletGlobalScope 上设置 MessagePort 意味着在渲染线程上执行以下步骤，并使用已传输到 AudioWorkletGlobalScope 的 serializedRenderingSidePort

1. 令 deserializedPort 为 StructuredDeserialize(serializedRenderingSidePort, 当前 Realm) 的结果。

2. 将 port 设置为 deserializedPort。

AudioContext.constructor(contextOptions) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
contextOptions	AudioContextOptions	✘	✔	用户指定的控制 AudioContext 应如何构建的选项。

1.2.2. 属性

baseLatency, 类型为 double，只读

这表示 AudioContext 将音频从 AudioDestinationNode 传递到音频子系统所产生的处理延迟（以秒为单位）。它不包括 AudioDestinationNode 的输出与音频硬件之间的任何其他处理可能导致的额外延迟，特别是不包括音频图本身产生的任何延迟。

例如，如果音频上下文以 44.1 kHz 运行，且具有默认渲染量子大小，并且 AudioDestinationNode 在内部实现双缓冲，并且每个 渲染量子 都可以处理和输出音频，那么处理延迟约为 \((2\cdot128)/44100 = 5.805 \mathrm{ ms}\)。

outputLatency, 类型为 double，只读

音频输出延迟的秒数估计，即 UA 请求宿主系统播放缓冲区的时间与缓冲区中的第一个采样实际被音频输出设备处理的时间之间的时间间隔。对于产生声学信号的扬声器或耳机等设备，后者时间指声音产生的时间。

outputLatency 属性值取决于平台和连接的音频输出设备硬件。outputLatency 属性值在上下文运行或相关音频输出设备更改时可能会发生变化。当需要精确同步时，经常查询此值很有用。

renderCapacity, 类型为 AudioRenderCapacity，只读

返回与 AudioContext 关联的 AudioRenderCapacity 实例。

sinkId, 类型为 (DOMString or AudioSinkInfo)，只读

返回 [[sink ID]] 内部槽位的值。此属性在更新时被缓存，并且在缓存后返回相同的对象。

onsinkchange, 类型为 EventHandler

setSinkId() 的事件处理程序。此事件处理程序的事件类型为 sinkchange。当更改输出设备完成时，将分发此事件。

NOTE: 这不会为 AudioContext 构建时的初始设备选择分发。statechange 事件可用于检查初始输出设备的就绪状态。

onerror, 类型为 EventHandler

从 AudioContext 分发的 Event 的事件处理程序。此处理程序的事件类型为 error，用户代理可以在以下情况下分发此事件

• 初始化和激活所选音频设备时遇到失败。

• 当 AudioContext 在 running 时其关联的音频输出设备断开连接。

• 当操作系统报告音频设备故障时。

1.2.3. 方法

close()

关闭 AudioContext，释放正在使用的系统资源。这不会自动释放所有 AudioContext 创建的对象，但会挂起 AudioContext 的 currentTime 的进程，并停止处理音频数据。

当调用 close 时，执行这些步骤

1. 如果 this 的 相关全局对象的 关联文档不是 完全活跃的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

2. 设 promise 为一个新的 Promise。

3. 如果 AudioContext 上的 [[控制线程状态]] 标志为 closed，使用 InvalidStateError 拒绝该 promise，中止这些步骤并返回 promise。

4. 将 AudioContext 上的 [[控制线程状态]] 标志设置为 closed。

5. 排队一个控制消息以关闭 AudioContext。

6. 返回 promise。

运行一个控制消息以关闭 AudioContext 意味着在渲染线程上运行这些步骤

1. 尝试释放系统资源。

2. 将 [[渲染线程状态]] 设置为 suspended。

   这将停止渲染。

3. 如果此控制消息是作为对文档卸载的反应而运行的，则中止此算法。

   在这种情况下，无需通知控制线程。

4. 排队一个媒体元素任务以执行以下步骤

   1. 解析 promise。

   2. 如果 AudioContext 的 state 属性尚未为 "closed"

      1. 将 AudioContext 的 state 属性设置为 "closed"。

      2. 排队一个媒体元素任务以在 AudioContext 上触发一个名为 statechange 的事件。

当一个 AudioContext 被关闭时，任何连接到 AudioContext 的 MediaStream 和 HTMLMediaElement 的输出将被忽略。也就是说，它们将不再导致扬声器或其他输出设备发出任何输出。为了获得更灵活的行为，请考虑使用 HTMLMediaElement.captureStream()。

Note: 当一个 AudioContext 被关闭时，实现可以选择比挂起时更积极地释放资源。

无参数。

返回类型： Promise<undefined>

createMediaElementSource(mediaElement)

根据 HTMLMediaElement 创建一个 MediaElementAudioSourceNode。作为调用此方法的结果，来自 HTMLMediaElement 的音频播放将被重新路由到 AudioContext 的处理图中。

AudioContext.createMediaElementSource() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
mediaElement	HTMLMediaElement	✘	✘	将被重新路由的媒体元素。

返回类型： MediaElementAudioSourceNode

createMediaStreamDestination()

创建一个 MediaStreamAudioDestinationNode

无参数。

返回类型： MediaStreamAudioDestinationNode

createMediaStreamSource(mediaStream)

创建一个 MediaStreamAudioSourceNode。

AudioContext.createMediaStreamSource() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
mediaStream	MediaStream	✘	✘	将作为源的媒体流。

返回类型： MediaStreamAudioSourceNode

createMediaStreamTrackSource(mediaStreamTrack)

创建一个 MediaStreamTrackAudioSourceNode。

AudioContext.createMediaStreamTrackSource() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
mediaStreamTrack	MediaStreamTrack	✘	✘	将作为源的 MediaStreamTrack。其 kind 属性的值必须等于 "audio"，否则必须抛出 InvalidStateError 异常。

返回类型： MediaStreamTrackAudioSourceNode

getOutputTimestamp()

返回一个新的 AudioTimestamp 实例，其中包含两个上下文相关的音频流位置值：contextTime 成员包含当前由音频输出设备渲染的采样帧的时间（即输出音频流位置），其单位和原点与上下文的 currentTime 相同；performanceTime 成员包含估计的时间，表示存储的 contextTime 值对应的采样帧由音频输出设备渲染的时刻，其单位和原点与 performance.now() 相同（如 [hr-time-3] 中所述）。

如果上下文的渲染图尚未处理音频块，则 getOutputTimestamp 调用返回一个两个成员都包含零的 AudioTimestamp 实例。

在上下文的渲染图开始处理音频块后，其 currentTime 属性值总是超过从 getOutputTimestamp 方法调用获得的 contextTime 值。

从 getOutputTimestamp 方法返回的值可用于获取稍后上下文时间值的性能时间估计

function outputPerformanceTime(contextTime) {
    const timestamp = context.getOutputTimestamp();
    const elapsedTime = contextTime - timestamp.contextTime;
    return timestamp.performanceTime + elapsedTime * 1000;
}

在上述示例中，估计的准确性取决于参数值与当前输出音频流位置的接近程度：给定的 contextTime 越接近 timestamp.contextTime，获得的估计准确性越高。

Note: 上下文的 currentTime 值与从 getOutputTimestamp 方法调用获得的 contextTime 值之间的差值不能视为可靠的输出延迟估计，因为 currentTime 可能会以非均匀的时间间隔递增，因此应使用 outputLatency 属性。

无参数。

返回类型： AudioTimestamp

resume()

在挂起时恢复 AudioContext 的 currentTime 的进程。

当调用 resume 时，执行这些步骤

1. 如果 this 的 相关全局对象的 关联文档不是 完全活跃的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

2. 设 promise 为一个新的 Promise。

3. 如果 AudioContext 上的 [[控制线程状态]] 为 closed，使用 InvalidStateError 拒绝该 promise，中止这些步骤并返回 promise。

4. 将 [[suspended by user]] 设置为 false。

5. 如果上下文未被允许启动，将 promise 添加到 [[pending promises]] 和 [[pending resume promises]] 中，并中止这些步骤，返回 promise。

6. 将 AudioContext 上的 [[控制线程状态]] 设置为 running。

7. 排队一个控制消息以恢复 AudioContext。

8. 返回 promise。

运行一个控制消息以恢复 AudioContext 意味着在渲染线程上运行这些步骤

尝试获取系统资源。

将 AudioContext 上的 [[渲染线程状态]] 设置为 running。

开始渲染音频图。

如果失败， 排队一个媒体元素任务以执行以下步骤

1. 按顺序拒绝来自 [[pending resume promises]] 的所有 promise，然后清除 [[pending resume promises]]。

2. 此外，从 [[pending promises]] 中移除这些 promise。

排队一个媒体元素任务以执行以下步骤

1. 按顺序解析来自 [[pending resume promises]] 的所有 promise。

2. 清除 [[pending resume promises]]。此外，从 [[pending promises]] 中移除这些 promise。

3. 解析 promise。

4. 如果 AudioContext 的 state 属性尚未为 "running"

   1. 将 AudioContext 的 state 属性设置为 "running"。

   2. 排队一个媒体元素任务以在 AudioContext 上触发一个名为 statechange 的事件。

无参数。

返回类型： Promise<undefined>

suspend()

挂起 AudioContext 的 currentTime 的进程，允许将已处理的任何当前上下文处理块播放到目的地，然后允许系统释放其对音频硬件的占用。这通常在应用程序知道它将在一段时间内不需要 AudioContext，并希望暂时释放系统资源与 AudioContext 相关联时非常有用。当帧缓冲区为空（已移交给硬件）时，promise 解析；如果上下文已处于 suspended 状态，则立即解析（无其他效果）。如果上下文已关闭，promise 将被拒绝。

当调用 suspend 时，执行这些步骤

1. 如果 this 的 相关全局对象 的 关联文档 不是 完全活动 的，则返回一个被 "InvalidStateError" DOMException 拒绝的 promise。

2. 设 promise 为一个新的 Promise。

3. 如果 AudioContext 上的 [[control thread state]] 为 closed，则用 InvalidStateError 拒绝该 promise，中止这些步骤，并返回 promise。

4. 将 promise 添加到 [[pending promises]] 中。

5. 将 [[suspended by user]] 设置为 true。

6. 将 AudioContext 上的 [[control thread state]] 设置为 suspended。

7. 排队一个控制消息以挂起 AudioContext。

8. 返回 promise。

运行一个用于挂起 AudioContext 的 控制消息，意味着在 渲染线程 上执行以下步骤

1. 尝试 释放系统资源。

2. 将 AudioContext 上的 [[rendering thread state]] 设置为 suspended。

3. 排队一个媒体元素任务以执行以下步骤

   1. 解析 promise。

   2. 如果 AudioContext 的 state 属性尚不是 "suspended"

      1. 将 AudioContext 的 state 属性设置为 "suspended"。

      2. 排队一个媒体元素任务，以在 AudioContext 上触发一个名为 statechange 的事件。

当 AudioContext 被挂起时，MediaStream 的输出将被忽略；也就是说，由于媒体流的实时特性，数据将会丢失。HTMLMediaElement 的输出也将被忽略，直到系统恢复。AudioWorkletNode 和 ScriptProcessorNode 在挂起时将停止调用其处理程序，但会在上下文恢复时恢复。就 AnalyserNode 窗口函数而言，数据被视为连续流——即 resume()/suspend() 不会导致 AnalyserNode 的数据流中出现静音。特别是，当 AudioContext 挂起时，重复调用 AnalyserNode 函数必须返回相同的数据。

无参数。

返回类型: Promise<undefined>

setSinkId((DOMString or AudioSinkOptions) sinkId)

设置输出设备的标识符。当此方法被调用时，用户代理必须运行以下步骤

1. 令 sinkId 为该方法的第一个参数。

2. 如果 sinkId 等于 [[sink ID]]，则返回一个 promise，立即将其解析并中止这些步骤。

3. 令 validationResult 为 sinkId 的 sink 标识符验证 的返回值。

4. 如果 validationResult 不为 null，则返回一个被 validationResult 拒绝的 promise。中止这些步骤。

5. 令 p 为一个新的 promise。

6. 发送一个包含 p 和 sinkId 的 控制消息 以开始处理。

7. 返回 p。

在 setSinkId() 期间发送一个用于开始处理的 控制消息，意味着执行以下步骤

1. 令 p 为传递给此算法的 promise。

2. 令 sinkId 为传递给此算法的 sink 标识符。

3. 如果 sinkId 和 [[sink ID]] 均为 DOMString 类型，且它们彼此相等，则 排队一个媒体元素任务 以解析 p 并中止这些步骤。

4. 如果 sinkId 为 AudioSinkOptions 类型，[[sink ID]] 为 AudioSinkInfo 类型，且 sinkId 中的 type 与 [[sink ID]] 中的 type 相等，则 排队一个媒体元素任务 以解析 p 并中止这些步骤。

5. 令 wasRunning 为 true。

6. 如果 AudioContext 上的 [[rendering thread state]] 为 "suspended"，则将 wasRunning 设置为 false。

7. 在处理完当前渲染量子（render quantum）后暂停渲染器。

8. 尝试 释放系统资源。

9. 如果 wasRunning 为 true

   1. 将 AudioContext 上的 [[rendering thread state]] 设置为 "suspended"。

   2. 排队一个媒体元素任务以执行以下步骤

      1. 如果 AudioContext 的 state 属性尚不是 "suspended"

         1. 将 AudioContext 的 state 属性设置为 "suspended"。

         2. 触发一个名为 statechange 的事件，并在关联的 AudioContext 上触发。

10. 尝试 获取系统资源，以基于 [[sink ID]] 使用后续音频输出设备进行渲染

    • 空字符串的默认音频输出设备。

    • 由 [[sink ID]] 标识的音频输出设备。

    如果失败，则用 "InvalidAccessError" 拒绝 p，中止以下步骤。

11. 排队一个媒体元素任务以执行以下步骤

    1. 如果 sinkId 是 DOMString 类型，将 [[sink ID]] 设置为 sinkId。中止这些步骤。

    2. 如果 sinkId 是 AudioSinkOptions 类型，且 [[sink ID]] 是 DOMString 类型，将 [[sink ID]] 设置为使用 sinkId 的 type 值创建的 AudioSinkInfo 的新实例。

    3. 如果 sinkId 是 AudioSinkOptions 类型，且 [[sink ID]] 是 AudioSinkInfo 类型，将 [[sink ID]] 的 type 设置为 sinkId 的 type 值。

    4. 解析 p。

    5. 触发一个名为 sinkchange 的事件，并在关联的 AudioContext 上触发。

12. 如果 wasRunning 为 true

    1. 将 AudioContext 上的 [[rendering thread state]] 设置为 "running"。

    2. 排队一个媒体元素任务以执行以下步骤

       1. 如果 AudioContext 的 state 属性尚不是 "running"

          1. 将 AudioContext 的 state 属性设置为 "running"。

          2. 触发一个名为 statechange 的事件，并在关联的 AudioContext 上触发。

1.2.4. 验证 sinkId

此算法用于验证为修改 sinkId 而提供的信息

1.2.5. AudioContextOptions

AudioContextOptions 字典用于指定 AudioContext 的用户自定义选项。

dictionary AudioContextOptions {
    (AudioContextLatencyCategory or double) latencyHint = "interactive";
    float sampleRate;
    (DOMString or AudioSinkOptions) sinkId;
    (AudioContextRenderSizeCategory or unsigned long) renderSizeHint = "default";
};

1.2.5.1. 字典 AudioContextOptions 成员

latencyHint, 类型为 (AudioContextLatencyCategory 或 double)，默认为 "interactive"

标识播放类型，这会影响音频输出延迟与功耗之间的权衡。

latencyHint 的首选值是来自 AudioContextLatencyCategory 的值。但是，也可以指定一个 double 类型的值作为延迟秒数，以更精细地控制延迟与功耗的平衡。浏览器有权自行解释该数值。实际使用的延迟由 AudioContext 的 baseLatency 属性给出。

sampleRate, 类型为 float

将创建的 AudioContext 的 sampleRate 设置为此值。支持的值与 AudioBuffer 的采样率相同。如果不支持指定的采样率，则必须抛出 NotSupportedError 异常。

如果未指定 sampleRate，则使用此 AudioContext 的输出设备的首选采样率。

sinkId, 类型为 (DOMString 或 AudioSinkOptions)

音频输出设备的标识符或相关信息。更多详情请参阅 sinkId。

renderSizeHint, 类型为 (AudioContextRenderSizeCategory 或 unsigned long)，默认为 "default"

这允许用户在传入整数时请求特定的 渲染量子大小，在不传参或传入 "default" 时使用默认的 128 帧，或者在指定 "hardware" 时请求用户代理选择一个合适的 渲染量子大小。

这只是一个提示，可能不被采纳。

1.2.6. AudioSinkOptions

AudioSinkOptions 字典用于为 sinkId 指定选项。

dictionary AudioSinkOptions {
    required AudioSinkType type;
};

1.2.6.1. 字典 AudioSinkOptions 成员

type, 类型为 AudioSinkType

AudioSinkType 的一个值，用于指定设备的类型。

1.2.7. AudioSinkInfo

AudioSinkInfo 接口用于通过 sinkId 获取当前音频输出设备的信息。

[Exposed=Window]
interface AudioSinkInfo {
    readonly attribute AudioSinkType type;
};

1.2.7.1. 属性

type, 类型为 AudioSinkType，只读

表示设备类型的一个 AudioSinkType 值。

1.2.8. AudioTimestamp

dictionary AudioTimestamp {
    double contextTime;
    DOMHighResTimeStamp performanceTime;
};

1.2.8.1. 字典 AudioTimestamp 成员

contextTime, 类型为 double

表示 BaseAudioContext 的 currentTime 时间坐标系中的一个点。

performanceTime, 类型为 DOMHighResTimeStamp

表示 Performance 接口实现的时间坐标系中的一个点（详见 [hr-time-3]）。

1.2.9. AudioRenderCapacity

[Exposed=Window]
interface AudioRenderCapacity : EventTarget {
    undefined start(optional AudioRenderCapacityOptions options = {});
        undefined stop();
        attribute EventHandler onupdate;
};

此接口提供了 AudioContext 的渲染性能指标。为了计算这些指标，渲染器会针对每个 系统级音频回调 收集一个 负载值。

1.2.9.1. 属性

onupdate, 类型为 EventHandler

此事件处理程序的事件类型是 update。分发给此事件处理程序的事件将使用 AudioRenderCapacityEvent 接口。

1.2.9.2. 方法

start(options)

开始指标收集和分析。这将根据 AudioRenderCapacityOptions 中给定的更新间隔，反复在 AudioRenderCapacity 上触发一个名为 update 的事件，并使用 AudioRenderCapacityEvent。

stop()

停止指标收集和分析。它也会停止分发 update 事件。

1.2.10. AudioRenderCapacityOptions

AudioRenderCapacityOptions 字典可用于为 AudioRenderCapacity 提供用户选项。

dictionary AudioRenderCapacityOptions {
        double updateInterval = 1;
};

1.2.10.1. 字典 AudioRenderCapacityOptions 成员

updateInterval, 类型为 double，默认为 1

用于分发 AudioRenderCapacityEvent 的更新间隔（以秒为单位）。针对每个 系统级音频回调 计算一个 负载值，并且会在指定的间隔周期内收集多个负载值。例如，如果渲染器以 48Khz 的采样率运行，且 系统级音频回调 的缓冲区大小为 192 帧，则在 1 秒的间隔内将收集 250 个负载值。

如果给定值小于 系统级音频回调 的持续时间，则抛出 NotSupportedError。

1.2.11. AudioRenderCapacityEvent

[Exposed=Window]
interface AudioRenderCapacityEvent : Event {
    constructor (DOMString type, optional AudioRenderCapacityEventInit eventInitDict = {});
        readonly attribute double timestamp;
        readonly attribute double averageLoad;
        readonly attribute double peakLoad;
        readonly attribute double underrunRatio;
};

dictionary AudioRenderCapacityEventInit : EventInit {
    double timestamp = 0;
    double averageLoad = 0;
    double peakLoad = 0;
    double underrunRatio = 0;
};

1.2.11.1. 属性

timestamp, 类型为 double，只读

数据收集周期的开始时间，以关联的 AudioContext 的 currentTime 表示。

averageLoad, 类型为 double，只读

在给定更新间隔内收集的负载值的平均值。精度限制为 1/100。

peakLoad, 类型为 double，只读

在给定更新间隔内收集的负载值中的最大值。精度同样限制为 1/100。

underrunRatio, 类型为 double，只读

在给定更新间隔内，缓冲区欠载（负载值大于 1.0）次数与 系统级音频回调 总次数之间的比率。

其中 \(u\) 是缓冲区欠载次数，\(N\) 是在给定更新间隔内 系统级音频回调 的总次数，缓冲区欠载比率为

• 如果 \(u\) = 0，则为 0.0。

• 否则，计算 \(u/N\) 并取最接近 100 分之一的向上取整值。

1.3. OfflineAudioContext 接口

OfflineAudioContext 是一种特殊的 BaseAudioContext，用于（可能）比实时更快的渲染/混音。它不渲染到音频硬件，而是尽可能快地进行渲染，并将渲染结果作为 AudioBuffer 履行返回的 promise。

[Exposed=Window]
interface OfflineAudioContext : BaseAudioContext {
    constructor(OfflineAudioContextOptions contextOptions);
    constructor(unsigned long numberOfChannels, unsigned long length, float sampleRate);
    Promise<AudioBuffer> startRendering();
    Promise<undefined> resume();
    Promise<undefined> suspend(double suspendTime);
    readonly attribute unsigned long length;
    attribute EventHandler oncomplete;
};

1.3.1. 构造函数

OfflineAudioContext(contextOptions)

如果 当前设置对象 的 相关全局对象 的 关联文档 不是 完全活动 的，则抛出 InvalidStateError 并中止这些步骤。

令 c 为一个新的 OfflineAudioContext 对象。按如下方式初始化 c

1. 将 c 的 [[control thread state]] 设置为 "suspended"。

2. 将 c 的 [[rendering thread state]] 设置为 "suspended"。

3. 基于 renderSizeHint 的值，确定此 OfflineAudioContext 的 [[render quantum size]]

   1. 如果其默认值为 "default" 或 "hardware"，则将 [[render quantum size]] 私有槽位设置为 128。

   2. 否则，如果传入的是一个整数，则用户代理可以决定通过将其设置为 [[render quantum size]] 私有槽位来采纳此值。

4. 构建一个 AudioDestinationNode，其 channelCount 设置为 contextOptions.numberOfChannels。

5. 令 messageChannel 为一个新的 MessageChannel。

6. 令 controlSidePort 为 messageChannel 的 port1 属性的值。

7. 令 renderingSidePort 为 messageChannel 的 port2 属性的值。

8. 令 serializedRenderingSidePort 为 StructuredSerializeWithTransfer(renderingSidePort, « renderingSidePort ») 的结果。

9. 将此 audioWorklet 的 port 设置为 controlSidePort。

10. 排队一个控制消息以在 AudioContext 上设置 AudioContextGlobalScope 上的 MessagePort，并传入 serializedRenderingSidePort。

OfflineAudioContext.constructor(contextOptions) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
contextOptions				构建此上下文所需的初始参数。

OfflineAudioContext(numberOfChannels, length, sampleRate)

OfflineAudioContext 可以使用与 AudioContext.createBuffer 相同的参数进行构建。如果任何参数为负数、零或超出其标称范围，则必须抛出 NotSupportedError 异常。

构建 OfflineAudioContext 的过程等同于

new OfflineAudioContext({
        numberOfChannels: numberOfChannels,
        length: length,
        sampleRate: sampleRate
})

调用以下方法。

OfflineAudioContext.constructor(numberOfChannels, length, sampleRate) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
numberOfChannels	unsigned long	✘	✘	确定缓冲区将具有多少个通道。支持的通道数请参阅 createBuffer()。
length	unsigned long	✘	✘	确定以采样帧为单位的缓冲区大小。
sampleRate	float	✘	✘	描述缓冲区中 线性 PCM 音频数据的采样率（以每秒采样帧数为单位）。有效采样率请参阅 createBuffer()。

1.3.2. 属性

length, 类型为 unsigned long，只读

缓冲区的大小（以采样帧为单位）。这与构造函数中 length 参数的值相同。

oncomplete, 类型为 EventHandler

此事件处理程序的事件类型是 complete。分发给此事件处理程序的事件将使用 OfflineAudioCompletionEvent 接口。这是在 OfflineAudioContext 上触发的最后一个事件。

1.3.3. 方法

startRendering()

基于当前的连接和预定的更改，开始渲染音频。

虽然获取渲染音频数据的主要方法是通过其 promise 返回值，但出于遗留原因，该实例也会触发一个名为 complete 的事件。

令 [[rendering started]] 为此 OfflineAudioContext 的一个内部槽位。将此槽位初始化为 false。

当调用 startRendering 时，必须在 控制线程 上执行以下步骤

1. 如果 this 的 相关全局对象 的 关联文档 不是 完全活动 的，则返回一个被 "InvalidStateError" DOMException 拒绝的 promise。
2. 如果 OfflineAudioContext 上的 [[rendering started]] 槽位为 true，则返回一个被 InvalidStateError 拒绝的 promise，并中止这些步骤。
3. 将 OfflineAudioContext 的 [[rendering started]] 槽位设置为 true。
4. 设 promise 为一个新的 Promise。
5. 创建一个新的 AudioBuffer，其通道数、长度和采样率分别等于在 contextOptions 参数中传递给此实例构造函数的 numberOfChannels、length 和 sampleRate 值。将此缓冲区分配给 OfflineAudioContext 中的一个内部槽位 [[rendered buffer]]。
6. 如果在前面的 AudioBuffer 构造函数调用期间抛出了异常，则用该异常拒绝 promise。
7. 否则，如果缓冲区构建成功，则 开始离线渲染。
8. 将 promise 添加到 [[pending promises]] 中。
9. 返回 promise。

要 开始离线渲染，必须在为此专门创建的 渲染线程 上执行以下步骤。

1. 基于当前的连接和预定的更改，开始将 length 个音频采样帧渲染到 [[rendered buffer]] 中
2. 对于每个 渲染量子，检查并在必要时 挂起 渲染。
3. 如果挂起的上下文恢复，则继续渲染缓冲区。
4. 一旦渲染完成， 排队一个媒体元素任务以执行以下步骤
   1. 用 [[rendered buffer]] 解析由 startRendering() 创建的 promise。
   2. 排队一个媒体元素任务，以在 OfflineAudioContext 上触发一个名为 complete 的事件，使用 OfflineAudioCompletionEvent，并将其 renderedBuffer 属性设置为 [[rendered buffer]]。

无参数。

返回类型: Promise<AudioBuffer>

resume()

在 OfflineAudioContext 的 currentTime 被挂起时，恢复其进程。

当调用 resume 时，执行这些步骤

1. 如果 this 的 相关全局对象 的 关联文档 不是 完全活动 的，则返回一个被 "InvalidStateError" DOMException 拒绝的 promise。

2. 设 promise 为一个新的 Promise。

3. 当以下任一条件为真时，中止这些步骤并用 InvalidStateError 拒绝 promise

   • OfflineAudioContext 上的 [[control thread state]] 为 closed。

   • OfflineAudioContext 上的 [[rendering started]] 槽位为 false。

4. 将 OfflineAudioContext 上的 [[control thread state]] 标志设置为 running。

5. 排队一个控制消息以恢复 OfflineAudioContext。

6. 返回 promise。

运行一个用于恢复 OfflineAudioContext 的 控制消息，意味着在 渲染线程 上执行这些步骤

1. 将 OfflineAudioContext 上的 [[rendering thread state]] 设置为 running。

2. 开始渲染音频图。

3. 如果失败， 排队一个媒体元素任务以拒绝 promise 并中止剩余步骤。

4. 排队一个媒体元素任务以执行以下步骤

   1. 解决（Resolve）promise。

   2. 如果 OfflineAudioContext 的 state 属性尚不是 "running"

      1. 将 OfflineAudioContext 的 state 属性设置为 "running"。

      2. 排队一个媒体元素任务，以在 OfflineAudioContext 上触发一个名为 statechange 的事件。

无参数。

返回类型: Promise<undefined>

suspend(suspendTime)

在指定时间安排音频上下文的时间进度挂起，并返回一个 promise。这在 OfflineAudioContext 上同步操作音频图时通常很有用。

注意，挂起的最大精度是 渲染量子 的大小，指定的挂起时间将被四舍五入到最近的 渲染量子 边界。因此，不允许在同一个量化帧安排多次挂起。此外，为了确保精确的挂起，应在上下文未运行时进行安排。

OfflineAudioContext.suspend() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
suspendTime	double	✘	✘	安排在指定时间挂起渲染，该时间将被量化并向上取整至 渲染量子 大小。如果量化后的帧数 为负数，或 小于或等于当前时间，或 大于或等于总渲染持续时间，或 由另一个挂起操作安排在同一时间， 则 promise 将被 InvalidStateError 拒绝。

返回类型: Promise<undefined>

1.3.4. OfflineAudioContextOptions

这指定了在构建 OfflineAudioContext 时使用的选项。

dictionary OfflineAudioContextOptions {
    unsigned long numberOfChannels = 1;
    required unsigned long length;
    required float sampleRate;
    (AudioContextRenderSizeCategory or unsigned long) renderSizeHint = "default";
};

1.3.4.1. 字典 OfflineAudioContextOptions 成员

length, 类型为 unsigned long

渲染出的 AudioBuffer 的长度（以采样帧为单位）。

numberOfChannels, 类型为 unsigned long，默认为 1

此 OfflineAudioContext 的通道数。

sampleRate, 类型为 float

此 OfflineAudioContext 的采样率。

renderSizeHint, 类型为 (AudioContextRenderSizeCategory 或 unsigned long)，默认为 "default"

此 OfflineAudioContext 的 渲染量子大小 提示。

1.3.5. OfflineAudioCompletionEvent 接口

这是一个 Event 对象，出于遗留原因，它被分发给 OfflineAudioContext。

[Exposed=Window]
interface OfflineAudioCompletionEvent : Event {
    constructor (DOMString type, OfflineAudioCompletionEventInit eventInitDict);
    readonly attribute AudioBuffer renderedBuffer;
};

1.3.5.1. 属性

renderedBuffer, 类型为 AudioBuffer，只读

包含渲染出的音频数据的 AudioBuffer。

1.3.5.2. OfflineAudioCompletionEventInit

dictionary OfflineAudioCompletionEventInit : EventInit {
    required AudioBuffer renderedBuffer;
};

1.3.5.2.1. 字典 OfflineAudioCompletionEventInit 成员

renderedBuffer, 类型为 AudioBuffer

要分配给事件的 renderedBuffer 属性的值。

1.4. AudioBuffer 接口

此接口表示驻留在内存中的音频资源。它可以包含一个或多个通道，每个通道呈现为标称范围为 \([-1,1]\) 的 32 位浮点 线性 PCM 值，但数值不限于此范围。通常，PCM 数据的长度预计会比较短（通常少于一分钟）。对于较长的声音（例如电影原声带），应使用 audio 元素和 MediaElementAudioSourceNode 进行流式传输。

AudioBuffer 可以被一个或多个 AudioContext 使用，并且可以在 OfflineAudioContext 和 AudioContext 之间共享。

AudioBuffer 有四个内部槽位

[[number of channels]]

此 AudioBuffer 的音频通道数，是一个 unsigned long。

[[length]]

此 AudioBuffer 中每个通道的长度，是一个 unsigned long。

[[sample rate]]

此 AudioBuffer 的采样率（以 Hz 为单位），是一个 float。

[[internal data]]

一个保存音频样本数据的 数据块。

[Exposed=Window]
interface AudioBuffer {
    constructor (AudioBufferOptions options);
    readonly attribute float sampleRate;
    readonly attribute unsigned long length;
    readonly attribute double duration;
    readonly attribute unsigned long numberOfChannels;
    Float32Array getChannelData (unsigned long channel);
    undefined copyFromChannel (Float32Array destination,
                               unsigned long channelNumber,
                               optional unsigned long bufferOffset = 0);
    undefined copyToChannel (Float32Array source,
                             unsigned long channelNumber,
                             optional unsigned long bufferOffset = 0);
};

1.4.1. 构造函数

AudioBuffer(options)

1. 如果 options 中的任何值超出其标称范围，则抛出 NotSupportedError 异常并中止以下步骤。

2. 令 b 为一个新的 AudioBuffer 对象。

3. 分别将构造函数中传入的 AudioBufferOptions 的 numberOfChannels、length、sampleRate 属性值分配给内部槽位 [[number of channels]]、[[length]]、[[sample rate]]。

4. 将此 AudioBuffer 的内部槽位 [[internal data]] 设置为调用 CreateByteDataBlock([[length]] * [[number of channels]]) 的结果。

   注意：这将底层存储初始化为零。

5. 返回 b。

AudioBuffer.constructor() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
options	AudioBufferOptions	✘	✘	一个确定此 AudioBuffer 属性的 AudioBufferOptions。

1.4.2. 属性

duration, 类型为 double，只读

PCM 音频数据的持续时间（以秒为单位）。

这是通过将 AudioBuffer 的 [[length]] 除以 [[sample rate]] 计算得出的。

length, 类型为 unsigned long，只读

PCM 音频数据的长度（以采样帧为单位）。这必须返回 [[length]] 的值。

numberOfChannels, 类型为 unsigned long，只读

离散音频通道的数量。这必须返回 [[number of channels]] 的值。

sampleRate, 类型为 float，只读

PCM 音频数据的采样率（以每秒采样数为单位）。这必须返回 [[sample rate]] 的值。

1.4.3. 方法

copyFromChannel(destination, channelNumber, bufferOffset)

copyFromChannel() 方法将样本从 AudioBuffer 的指定通道复制到 destination 数组中。

设 buffer 为包含 \(N_b\) 帧的 AudioBuffer，设 \(N_f\) 为 destination 数组中的元素数量，设 \(k\) 为 bufferOffset 的值。那么从 buffer 复制到 destination 的帧数为 \(\max(0, \min(N_b - k, N_f))\)。如果该值小于 \(N_f\)，则 destination 的其余元素不会被修改。

AudioBuffer.copyFromChannel() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destination	Float32Array	✘	✘	将要复制通道数据到的数组。
channelNumber	unsigned long	✘	✘	要复制数据的通道索引。如果 channelNumber 大于或等于 AudioBuffer 的通道数，则必须抛出 IndexSizeError。
bufferOffset	unsigned long	✘	✔	一个可选的偏移量，默认为 0。从该偏移量开始的 AudioBuffer 数据将被复制到 destination。

返回类型： undefined

copyToChannel(source, channelNumber, bufferOffset)

copyToChannel() 方法将 source 数组中的采样点复制到 AudioBuffer 的指定通道。

如果无法将 source 复制到缓冲区，可能会抛出 UnknownError。

设 buffer 为包含 \(N_b\) 帧的 AudioBuffer，设 \(N_f\) 为 source 数组中的元素数量，设 \(k\) 为 bufferOffset 的值。那么从 source 复制到 buffer 的帧数为 \(\max(0, \min(N_b - k, N_f))\)。如果该值小于 \(N_f\)，则 buffer 的其余元素不会被修改。

AudioBuffer.copyToChannel() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
source	Float32Array	✘	✘	将要从中复制通道数据的数组。
channelNumber	unsigned long	✘	✘	要复制数据到的通道索引。如果 channelNumber 大于或等于 AudioBuffer 的通道数，则必须抛出 IndexSizeError。
bufferOffset	unsigned long	✘	✔	一个可选的偏移量，默认为 0。来自 source 的数据将从该偏移量开始复制到 AudioBuffer。

返回类型： undefined

getChannelData(channel)

根据 获取内容 中描述的规则，允许 写入 或 获取副本 存储在 [[internal data]] 中的字节，并返回一个新的 Float32Array。

如果无法创建 [[internal data]] 或新的 Float32Array，可能会抛出 UnknownError。

AudioBuffer.getChannelData() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
channel	unsigned long	✘	✘	此参数是一个索引，表示要获取数据的特定通道。索引值 0 表示第一个通道。此索引值必须小于 [[number of channels]]，否则必须抛出 IndexSizeError 异常。

返回类型： Float32Array

注意： 方法 copyToChannel() 和 copyFromChannel() 可用于填充数组的一部分，通过传入一个更大的数组的 Float32Array 视图。当从 AudioBuffer 的通道中读取数据，并且可以分块处理数据时，应优先使用 copyFromChannel()，而不是调用 getChannelData() 并访问生成的数组，因为这样可以避免不必要的内存分配和复制。

当某些 API 实现需要 AudioBuffer 的内容时，会调用内部操作 获取 AudioBuffer 的内容。此操作向调用者返回不可变的通道数据。

获取 AudioBuffer 的内容 操作在以下情况下被调用

• 当调用 AudioBufferSourceNode.start 时，它会 获取 节点的 buffer 内容。如果操作失败，则不会播放任何内容。

• 当设置 AudioBufferSourceNode 的 buffer 并且之前已经调用了 AudioBufferSourceNode.start 时，设置器会 获取 AudioBuffer 的内容。如果操作失败，则不会播放任何内容。

• 当 ConvolverNode 的 buffer 被设置为 AudioBuffer 时，它会 获取 AudioBuffer 的内容。

• 当 AudioProcessingEvent 的分发完成时，它会 获取 其 outputBuffer 的内容。

注意： 这意味着 copyToChannel() 不能用于更改当前正被某个 AudioNode 使用的 AudioBuffer 的内容，因为该 AudioNode 已经 获取了 AudioBuffer 的内容，并且将继续使用先前获取的数据。

1.4.4. AudioBufferOptions

这指定了用于构建 AudioBuffer 的选项。length 和 sampleRate 成员是必需的。

dictionary AudioBufferOptions {
    unsigned long numberOfChannels = 1;
    required unsigned long length;
    required float sampleRate;
};

1.4.4.1. 字典 AudioBufferOptions 成员

此字典成员的允许值受到限制。请参阅 createBuffer()。

length, 类型为 unsigned long

缓冲区的采样帧长度。请参阅 length 了解限制。

numberOfChannels, 类型为 unsigned long，默认为 1

缓冲区的通道数。请参阅 numberOfChannels 了解限制。

sampleRate, 类型为 float

缓冲区的采样率（以 Hz 为单位）。请参阅 sampleRate 了解限制。

1.5. AudioNode 接口

AudioNode 是 AudioContext 的构建块。此接口代表音频源、音频目标和中间处理模块。这些模块可以连接在一起，形成 处理图 以便将音频渲染到音频硬件。每个节点可以有 输入 和/或 输出。源节点 没有输入，只有一个输出。大多数处理节点（如滤波器）有一个输入和一个输出。每种类型的 AudioNode 在处理或合成音频的具体细节上有所不同。但是，通常情况下，AudioNode 会处理其输入（如果有的话），并为其输出生成音频（如果有的话）。

每个输出都有一个或多个通道。确切的通道数取决于特定 AudioNode 的细节。

一个输出可以连接到一个或多个 AudioNode 输入，因此支持 扇出 (fan-out)。一个输入最初没有连接，但可以从一个或多个 AudioNode 输出连接，因此支持 扇入 (fan-in)。当调用 connect() 方法将 AudioNode 的输出连接到 AudioNode 的输入时，我们将此称为到该输入的 连接。

每个 AudioNode 的 输入 在任何给定时间都有特定数量的通道。这个数字可能会随着对该输入进行的 连接 而改变。如果输入没有连接，则它有一个静音的通道。

对于每个 输入，AudioNode 对所有到该输入的连接进行混合。有关规范要求和详细信息，请参阅 § 4 通道上混和下混。

无论节点是否连接了输出，也无论这些输出最终是否到达 AudioContext 的 AudioDestinationNode，AudioNode 的输入处理和内部操作都会相对于 AudioContext 时间持续进行。

[Exposed=Window]
interface AudioNode : EventTarget {
    AudioNode connect (AudioNode destinationNode,
                       optional unsigned long output = 0,
                       optional unsigned long input = 0);
    undefined connect (AudioParam destinationParam, optional unsigned long output = 0);
    undefined disconnect ();
    undefined disconnect (unsigned long output);
    undefined disconnect (AudioNode destinationNode);
    undefined disconnect (AudioNode destinationNode, unsigned long output);
    undefined disconnect (AudioNode destinationNode,
                          unsigned long output,
                          unsigned long input);
    undefined disconnect (AudioParam destinationParam);
    undefined disconnect (AudioParam destinationParam, unsigned long output);
    readonly attribute BaseAudioContext context;
    readonly attribute unsigned long numberOfInputs;
    readonly attribute unsigned long numberOfOutputs;
    attribute unsigned long channelCount;
    attribute ChannelCountMode channelCountMode;
    attribute ChannelInterpretation channelInterpretation;
};

1.5.1. AudioNode 创建

AudioNode 可以通过两种方式创建：使用该特定接口的构造函数，或使用 BaseAudioContext 或 AudioContext 上的 工厂方法。

作为 AudioNode 构造函数的第一个参数传递的 BaseAudioContext 被称为要创建的 AudioNode 的 关联 BaseAudioContext。类似地，使用工厂方法时，AudioNode 的 关联 BaseAudioContext 就是调用该工厂方法的 BaseAudioContext。

工厂方法的 关联接口 是该方法返回的对象的接口。关联选项对象 是可以传递给该接口构造函数的选项对象。

AudioNode 是 EventTarget，如 [DOM] 中所述。这意味着可以像其他 EventTarget 接受事件一样，向 AudioNode 分发事件。

enum ChannelCountMode {
    "max",
    "clamped-max",
    "explicit"
};

ChannelCountMode 结合节点的 channelCount 和 channelInterpretation 值，用于确定控制如何混合到节点输入的 computedNumberOfChannels（计算出的通道数）。computedNumberOfChannels 的确定方式如下所示。有关如何进行混合的更多信息，请参阅 § 4 通道上混和下混。

enum ChannelInterpretation {
    "speakers",
    "discrete"
};

1.5.2. AudioNode 尾音 (Tail-Time)

AudioNode 可以具有 尾音时长。这意味着即使在 AudioNode 被输入静音时，输出也可能不是静音的。

如果 AudioNode 具有内部处理状态，使得过去的输入会影响未来的输出，则它具有非零的尾音时长。AudioNode 即使在输入从非静音变为静音后，也可能在计算出的尾音时长内继续产生非静音输出。

1.5.3. AudioNode 生命周期

如果满足以下任一条件，AudioNode 在 渲染量子 (render quantum) 期间可以是 主动处理的。

• 当且仅当 AudioScheduledSourceNode 在当前渲染量子的至少一部分期间正在 播放 时，它就是 主动处理的。

• 当且仅当 MediaElementAudioSourceNode 的 mediaElement 在当前渲染量子的至少一部分期间正在播放时，它就是 主动处理的。

• 当关联的 MediaStreamTrack 对象的 readyState 属性等于 "live"，muted 属性等于 false 且 enabled 属性等于 true 时，MediaStreamAudioSourceNode 或 MediaStreamTrackAudioSourceNode 是 主动处理的。

• 仅当当前 渲染量子 的任何输出采样的绝对值大于或等于 \( 2^{-126} \) 时，循环中的 DelayNode 才是 主动处理的。

• 当其输入或输出已连接时，ScriptProcessorNode 是 主动处理的。

• 当其 AudioWorkletProcessor 的 [[callable process]] 返回 true，且其 活动源 标志为 true，或者连接到其输入之一的任何 AudioNode 是 主动处理的 时，AudioWorkletNode 是 主动处理的。

• 当连接到其输入之一的任何 AudioNode 是 主动处理的 时，所有其他 AudioNode 开始 主动处理；当从其他 主动处理的 AudioNode 接收到的输入不再影响输出时，停止 主动处理。

注意： 这考虑到了具有 尾音时长 的 AudioNode。

不 主动处理的 AudioNode 输出单通道静音。

1.5.4. 属性

channelCount, 类型为 unsigned long

channelCount 是上混和下混到节点任何输入的连接时使用的通道数。默认值为 2，但特定节点除外，其值是专门确定的。此属性对于没有输入的节点无效。如果此值设置为零或大于实现的最大通道数的值，实现必须抛出 NotSupportedError 异常。

此外，某些节点对通道数可能的值有额外的 channelCount 约束

AudioDestinationNode

行为取决于目标节点是 AudioContext 还是 OfflineAudioContext 的目标

AudioContext

通道数必须在 1 和 maxChannelCount 之间。任何在此时范围之外设置通道数的尝试都必须抛出 IndexSizeError 异常。

OfflineAudioContext

通道数无法更改。任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

AudioWorkletNode

请参阅 § 1.32.4.3.2 使用 AudioWorkletNodeOptions 配置通道。

ChannelMergerNode

通道数无法更改，且任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

ChannelSplitterNode

通道数无法更改，且任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

ConvolverNode

通道数不能大于 2，且任何尝试将其更改为大于 2 的值的行为都必须抛出 NotSupportedError 异常。

DynamicsCompressorNode

通道数不能大于 2，且任何尝试将其更改为大于 2 的值的行为都必须抛出 NotSupportedError 异常。

PannerNode

通道数不能大于 2，且任何尝试将其更改为大于 2 的值的行为都必须抛出 NotSupportedError 异常。

ScriptProcessorNode

通道数无法更改，且任何尝试更改该值的行为都必须抛出 NotSupportedError 异常。

StereoPannerNode

通道数不能大于 2，且任何尝试将其更改为大于 2 的值的行为都必须抛出 NotSupportedError 异常。

有关此属性的更多信息，请参阅 § 4 通道上混和下混。

channelCountMode, 类型为 ChannelCountMode

channelCountMode 决定了在对节点任何输入的连接进行上混和下混时如何计算通道。默认值为 "max"。此属性对于没有输入的节点无效。

此外，某些节点对通道计数模式可能的值有额外的 channelCountMode 约束

AudioDestinationNode

如果 AudioDestinationNode 是 OfflineAudioContext 的 destination 节点，则通道计数模式无法更改。任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

ChannelMergerNode

通道计数模式无法从 "explicit" 更改，且任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

ChannelSplitterNode

通道计数模式无法从 "explicit" 更改，且任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

ConvolverNode

通道计数模式无法设置为 "max"，且任何尝试将其设置为 "max" 的行为都必须抛出 NotSupportedError 异常。

DynamicsCompressorNode

通道计数模式无法设置为 "max"，且任何尝试将其设置为 "max" 的行为都必须抛出 NotSupportedError 异常。

PannerNode

通道计数模式无法设置为 "max"，且任何尝试将其设置为 "max" 的行为都必须抛出 NotSupportedError 异常。

ScriptProcessorNode

通道计数模式无法从 "explicit" 更改，且任何尝试更改该值的行为都必须抛出 NotSupportedError 异常。

StereoPannerNode

通道计数模式无法设置为 "max"，且任何尝试将其设置为 "max" 的行为都必须抛出 NotSupportedError 异常。

有关此属性的更多信息，请参阅 § 4 通道上混和下混 章节。

channelInterpretation, 类型为 ChannelInterpretation

channelInterpretation 决定了在对节点任何输入的连接进行上混和下混时如何对待各个通道。默认值为 "speakers"。此属性对于没有输入的节点无效。

此外，某些节点对通道解释可能的值有额外的 channelInterpretation 约束

ChannelSplitterNode

通道解释无法从 "discrete" 更改，且任何尝试更改该值的行为都必须抛出 InvalidStateError 异常。

有关此属性的更多信息，请参阅 § 4 通道上混和下混。

context, 类型为 BaseAudioContext，只读

拥有此 AudioNode 的 BaseAudioContext。

numberOfInputs, 类型为 unsigned long，只读

馈入 AudioNode 的输入数量。对于 源节点，此值为 0。此属性对于许多 AudioNode 类型是预先确定的，但某些 AudioNode（如 ChannelMergerNode 和 AudioWorkletNode）具有可变的输入数量。

numberOfOutputs, 类型为 unsigned long，只读

来自 AudioNode 的输出数量。此属性对于某些 AudioNode 类型是预先确定的，但可以是可变的，例如 ChannelSplitterNode 和 AudioWorkletNode。

1.5.5. 方法

connect(destinationNode, output, input)

一个特定节点的给定输出与另一个特定节点的给定输入之间只能有一个连接。具有相同端点的多个连接将被忽略。

例如

nodeA.connect(nodeB);
nodeA.connect(nodeB);

将产生与以下相同的效果

nodeA.connect(nodeB);

此方法返回 destination AudioNode 对象。

AudioNode.connect(destinationNode, output, input) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationNode				destination 参数是要连接到的 AudioNode。如果 destination 参数是使用另一个 AudioContext 创建的 AudioNode，则必须抛出 InvalidAccessError。 也就是说，AudioNode 不能在 AudioContext 之间共享。多个 AudioNode 可以连接到同一个 AudioNode，这在 通道上混和下混 章节中有描述。
output	unsigned long	✘	✔	output 参数是一个索引，描述要连接 AudioNode 的哪个输出。如果此参数越界，则必须抛出 IndexSizeError 异常。 可以通过多次调用 connect() 将一个 AudioNode 输出连接到多个输入。因此，支持 "扇出"。
input (输入)				input 参数是一个索引，描述要连接到目标 AudioNode 的哪个输入。如果此参数越界，则必须抛出 IndexSizeError 异常。 可以将一个 AudioNode 连接到另一个 AudioNode，从而创建一个 循环 (cycle)：一个 AudioNode 可以连接到另一个 AudioNode，该节点又连接回第一个 AudioNode 的输入或 AudioParam。

返回类型： AudioNode

connect(destinationParam, output)

将 AudioNode 连接到 AudioParam，使用 a-rate 信号控制参数值。

可以通过多次调用 connect() 将一个 AudioNode 输出连接到多个 AudioParam。因此，支持 "扇出"。

可以通过多次调用 connect() 将多个 AudioNode 输出连接到单个 AudioParam。因此，支持 "扇入"。

AudioParam 将从连接到它的任何 AudioNode 输出中获取渲染后的音频数据，如果不已经是单声道，则通过下混 将其转换为单声道，然后将其与其他此类输出混合，最后与 固有 (intrinsic) 参数值（在没有任何音频连接的情况下 AudioParam 通常具有的 value）进行混合，包括为该参数调度的任何时间轴更改。

下混至单声道等同于 AudioNode 的下混，其中 channelCount = 1，channelCountMode = "explicit"，并且 channelInterpretation = "speakers"。

一个特定节点的给定输出与特定 AudioParam 之间只能有一个连接。具有相同端点的多个连接将被忽略。

例如

nodeA.connect(param);
nodeA.connect(param);

将产生与以下相同的效果

nodeA.connect(param);

AudioNode.connect(destinationParam, output) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationParam	AudioParam	✘	✘	destination 参数是要连接到的 AudioParam。此方法不返回 destination AudioParam 对象。如果 destinationParam 属于一个 AudioNode，而该节点又属于一个与调用此方法的 BaseAudioContext 不同的 BaseAudioContext，则必须抛出 InvalidAccessError。
output	unsigned long	✘	✔	output 参数是一个索引，描述要连接 AudioNode 的哪个输出。如果 parameter 越界，则必须抛出 IndexSizeError 异常。

返回类型： undefined

disconnect()

断开 AudioNode 的所有传出连接。

无参数。

返回类型： undefined

disconnect(output)

断开 AudioNode 的单个输出与它连接到的任何其他 AudioNode 或 AudioParam 对象之间的连接。

AudioNode.disconnect(output) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
output	unsigned long	✘	✘	此参数是一个索引，描述要断开 AudioNode 的哪个输出。它断开从给定输出发出的所有传出连接。如果此参数越界，则必须抛出 IndexSizeError 异常。

返回类型： undefined

disconnect(destinationNode)

断开 AudioNode 指向特定目标 AudioNode 的所有输出。

AudioNode.disconnect(destinationNode) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationNode				destinationNode 参数是要断开连接的 AudioNode。它断开所有指向给定 destinationNode 的传出连接。如果没有到 destinationNode 的连接，则必须抛出 InvalidAccessError 异常。

返回类型： undefined

disconnect(destinationNode, output)

断开 AudioNode 的特定输出与某些目标 AudioNode 的任何和所有输入之间的连接。

AudioNode.disconnect(destinationNode, output) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationNode				destinationNode 参数是要断开连接的 AudioNode。如果给定输出没有到 destinationNode 的连接，则必须抛出 InvalidAccessError 异常。
output	unsigned long	✘	✘	output 参数是一个索引，描述要断开 AudioNode 的哪个输出。如果此参数越界，则必须抛出 IndexSizeError 异常。

返回类型： undefined

disconnect(destinationNode, output, input)

断开 AudioNode 的特定输出与某些目标 AudioNode 的特定输入之间的连接。

AudioNode.disconnect(destinationNode, output, input) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationNode				destinationNode 参数是要断开连接的 AudioNode。如果给定输出没有到给定输入的 destinationNode 的连接，则必须抛出 InvalidAccessError 异常。
output	unsigned long	✘	✘	output 参数是一个索引，描述要断开 AudioNode 的哪个输出。如果此参数越界，则必须抛出 IndexSizeError 异常。
input (输入)				input 参数是一个索引，描述要断开目标 AudioNode 的哪个输入。如果此参数越界，则必须抛出 IndexSizeError 异常。

返回类型： undefined

disconnect(destinationParam)

断开 AudioNode 指向特定目标 AudioParam 的所有输出。当此操作生效时，此 AudioNode 对计算参数值的贡献变为 0。固有参数值不受此操作的影响。

AudioNode.disconnect(destinationParam) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationParam	AudioParam	✘	✘	destinationParam 参数是要断开连接的 AudioParam。如果没有到 destinationParam 的连接，则必须抛出 InvalidAccessError 异常。

返回类型： undefined

disconnect(destinationParam, output)

断开 AudioNode 的特定输出与特定目标 AudioParam 之间的连接。当此操作生效时，此 AudioNode 对计算参数值的贡献变为 0。固有参数值不受此操作的影响。

AudioNode.disconnect(destinationParam, output) 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
destinationParam	AudioParam	✘	✘	destinationParam 参数是要断开连接的 AudioParam。如果没有到 destinationParam 的连接，则必须抛出 InvalidAccessError 异常。
output	unsigned long	✘	✘	output 参数是一个索引，描述要断开 AudioNode 的哪个输出。如果 parameter 越界，则必须抛出 IndexSizeError 异常。

返回类型： undefined

1.5.6. AudioNodeOptions

这指定了可用于构建所有 AudioNode 的选项。所有成员都是可选的。但是，每个节点使用的具体值取决于实际节点。

dictionary AudioNodeOptions {
    unsigned long channelCount;
    ChannelCountMode channelCountMode;
    ChannelInterpretation channelInterpretation;
};

1.5.6.1. 字典 AudioNodeOptions 成员

channelCount, 类型为 unsigned long

channelCount 属性所需的通道数。

channelCountMode, 类型为 ChannelCountMode

channelCountMode 属性所需的模式。

channelInterpretation, 类型为 ChannelInterpretation

channelInterpretation 属性所需的模式。

1.6. AudioParam 接口

AudioParam 控制 AudioNode 功能的各个方面，例如音量。参数可以使用 value 属性立即设置为特定值。或者，可以安排在非常精确的时间点（在 AudioContext 的 currentTime 属性坐标系中）进行值更改，用于包络、音量淡入淡出、LFO、滤波器扫描、颗粒窗口等。通过这种方式，可以在任何 AudioParam 上设置任意基于时间轴的自动化曲线。此外，来自 AudioNode 输出的音频信号可以连接到 AudioParam，并与 固有 参数值求和。

一些合成和处理 AudioNode 具有作为属性的 AudioParam，其值必须在每个音频采样基础上考虑。对于其他 AudioParam，采样精度并不重要，值更改可以更粗略地采样。每个单独的 AudioParam 将指定它是 a-rate 参数（意味着其值必须在每个音频采样基础上考虑），还是 k-rate 参数。

实现必须使用块处理，每个 AudioNode 处理一个 渲染量子。

对于每个 渲染量子，k-rate 参数的值必须在第一个采样帧时采样，并且该值必须用于整个块。a-rate 参数必须为块的每个采样帧进行采样。根据 AudioParam，其速率可以通过将 automationRate 属性设置为 "a-rate" 或 "k-rate" 来控制。有关更多详细信息，请参阅各个 AudioParam 的说明。

每个 AudioParam 都包含 minValue 和 maxValue 属性，它们共同构成了参数的简单标称范围。实际上，参数的值会被钳位（clamp）到范围 \([\mathrm{minValue}, \mathrm{maxValue}]\) 中。详细信息请参阅 § 1.6.3 数值计算。

对于许多 AudioParam 而言，minValue 和 maxValue 旨在被设置为最大可能的范围。在这种情况下，maxValue 应设置为 最大正单精度浮点数，即 3.4028235e38。（然而，在仅支持 IEEE-754 双精度浮点值的 JavaScript 中，必须写作 3.4028234663852886e38。）同样地，minValue 应设置为 最小负单精度浮点数，即 最大正单精度浮点数 的负值：-3.4028235e38。（类似地，在 JavaScript 中必须写作 -3.4028234663852886e38。）

AudioParam 维护一个包含零个或多个 自动化事件 的列表。每个自动化事件指定了参数值在特定时间范围内的变化，该时间是相对于 AudioContext 的 currentTime 属性所处时间坐标系下的 自动化事件时间。自动化事件列表按自动化事件时间的升序进行维护。

给定自动化事件的行为是 AudioContext 当前时间，以及该事件和列表中相邻事件的自动化事件时间的函数。以下 自动化方法 通过向事件列表添加特定于该方法类型的事件来更改事件列表：

• setValueAtTime() - SetValue

• linearRampToValueAtTime() - LinearRampToValue

• exponentialRampToValueAtTime() - ExponentialRampToValue

• setTargetAtTime() - SetTarget

• setValueCurveAtTime() - SetValueCurve

调用这些方法时适用以下规则：

• 自动化事件时间不会根据当前采样率进行量化。计算曲线和斜坡的公式适用于调度事件时给出的精确数值时间。

• 如果在一个已经存在一个或多个事件的时间点添加其中一个事件，则该事件将被放置在列表中的这些事件之后，但在时间晚于该事件的事件之前。

• 如果为时间 \(T\) 和持续时间 \(D\) 调用了 setValueCurveAtTime()，且存在时间严格大于 \(T\) 但严格小于 \(T + D\) 的任何事件，则必须抛出 NotSupportedError 异常。 换句话说，不允许在包含其他事件的时间段内调度值曲线，但允许在与其他事件完全相同的时间点调度值曲线。

• 类似地，如果任何 自动化方法 在包含于 \([T, T+D)\) 的时间内被调用（\(T\) 为曲线的时间，\(D\) 为其持续时间），则必须抛出 NotSupportedError 异常。

注意： AudioParam 属性除 value 属性外均为只读。

AudioParam 的自动化速率可以通过设置 automationRate 属性并赋予以下值之一来选择。然而，一些 AudioParam 对能否更改自动化速率有约束。

enum AutomationRate {
    "a-rate",
    "k-rate"
};

每个 AudioParam 都有一个内部槽位 [[current value]]，初始值设为 AudioParam 的 defaultValue。

[Exposed=Window]
interface AudioParam {
    attribute float value;
    attribute AutomationRate automationRate;
    readonly attribute float defaultValue;
    readonly attribute float minValue;
    readonly attribute float maxValue;
    AudioParam setValueAtTime (float value, double startTime);
    AudioParam linearRampToValueAtTime (float value, double endTime);
    AudioParam exponentialRampToValueAtTime (float value, double endTime);
    AudioParam setTargetAtTime (float target, double startTime, float timeConstant);
    AudioParam setValueCurveAtTime (sequence<float> values,
                                    double startTime,
                                    double duration);
    AudioParam cancelScheduledValues (double cancelTime);
    AudioParam cancelAndHoldAtTime (double cancelTime);
};

1.6.1. 属性

automationRate, 类型为 AutomationRate

AudioParam 的自动化速率。默认值取决于具体的 AudioParam；关于默认值，请参阅每个单独 AudioParam 的描述。

某些节点具有额外的 自动化速率约束，如下所示：

AudioBufferSourceNode

AudioParam 的 playbackRate 和 detune 必须为 "k-rate"。 如果速率更改为 "a-rate"，则必须抛出 InvalidStateError。

DynamicsCompressorNode

AudioParam 的 threshold、knee、ratio、attack 和 release 必须为 "k-rate"。 如果速率更改为 "a-rate"，则必须抛出 InvalidStateError。

PannerNode

如果 panningModel 为 "HRTF"，则 PannerNode 的任何 AudioParam 的 automationRate 设置都将被忽略。同样，AudioListener 的任何 AudioParam 的 automationRate 设置也会被忽略。在这种情况下，AudioParam 的行为表现得就像 automationRate 被设置为 "k-rate" 一样。

defaultValue, 类型为 float，只读

value 属性的初始值。

maxValue, 类型为 float，只读

参数可以取的标称最大值。与 minValue 一起，构成了该参数的 标称范围。

minValue, 类型为 float，只读

参数可以取的标称最小值。与 maxValue 一起，构成了该参数的 标称范围。

value, 类型为 float

参数的浮点数值。此属性初始化为 defaultValue。

获取此属性将返回 [[current value]] 槽位的内容。关于返回值的算法，请参阅 § 1.6.3 数值计算。

设置此属性的效果是将请求的值分配给 [[current value]] 槽位，并以当前 AudioContext 的 currentTime 和 [[current value]] 调用 setValueAtTime() 方法。setValueAtTime() 抛出的任何异常也将在设置此属性时抛出。

1.6.2. 方法

cancelAndHoldAtTime(cancelTime)

这与 cancelScheduledValues() 类似，都会取消所有时间大于或等于 cancelTime 的计划参数更改。然而，它额外将本应在 cancelTime 发生的自动化值保持，并持续到引入其他自动化事件为止。

当自动化正在运行，并且可以在调用 cancelAndHoldAtTime() 之后且达到 cancelTime 之前的任何时间点引入新自动化时，时间线的行为非常复杂。因此，cancelAndHoldAtTime() 的行为在以下算法中指定。

设 \(t_c\) 为 cancelTime 的值。那么：

1. 设 \(E_1\) 为时间 \(t_1\) 处的事件（如果存在），其中 \(t_1\) 是满足 \(t_1 \le t_c\) 的最大数。

2. 设 \(E_2\) 为时间 \(t_2\) 处的事件（如果存在），其中 \(t_2\) 是满足 \(t_c \lt t_2\) 的最小数。

3. 如果 \(E_2\) 存在

   1. 如果 \(E_2\) 是线性或指数斜坡，

      1. 实际上将 \(E_2\) 重写为同类型的斜坡，结束于时间 \(t_c\)，且结束值应为原始斜坡在时间 \(t_c\) 时的值。

      2. 转至第 5 步。

   2. 否则，转至第 4 步。

4. 如果 \(E_1\) 存在

   1. 如果 \(E_1\) 是 setTarget 事件，

      1. 在时间 \(t_c\) 处隐式插入一个 setValueAtTime 事件，其值为 setTarget 在时间 \(t_c\) 时应有的值。

      2. 转至第 5 步。

   2. 如果 \(E_1\) 是开始时间为 \(t_3\)、持续时间为 \(d\) 的 setValueCurve

      1. 如果 \(t_c \gt t_3 + d\)，转至第 5 步。

      2. 否则，

         1. 实际上将此事件替换为开始时间为 \(t_3\)、新持续时间为 \(t_c-t_3\) 的 setValueCurve 事件。然而，这不是真正的替换；此自动化必须确保产生与原始输出相同的输出，而不是使用不同持续时间计算出的输出。（那会导致以略微不同的方式对值曲线进行采样，从而产生不同的结果。）

         2. 转至第 5 步。

5. 移除所有时间大于 \(t_c\) 的事件。

如果没有添加任何事件，则 cancelAndHoldAtTime() 之后的自动化值即为原始时间线在时间 \(t_c\) 时的常量值。

AudioParam.cancelAndHoldAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
cancelTime	double	✘	✘	在此时间之后，任何先前计划的参数更改都将被取消。它与 AudioContext 的 currentTime 属性处于相同的时间坐标系中。 如果 cancelTime 为负数，则必须抛出 RangeError 异常。如果 cancelTime 小于 currentTime，则将其钳位到 currentTime。

返回类型： AudioParam

cancelScheduledValues(cancelTime)

取消所有时间大于或等于 cancelTime 的计划参数更改。取消计划的参数更改意味着从事件列表中删除该计划的事件。任何 自动化事件时间 小于 cancelTime 的活动自动化也会被取消，此类取消可能会导致不连续性，因为原始值（在此类自动化之前的值）会立即恢复。如果由 cancelAndHoldAtTime() 计划的保持值在 cancelTime 之后发生，则也会被移除。

对于 setValueCurveAtTime()，设 \(T_0\) 和 \(T_D\) 分别为该事件的相应 startTime 和 duration。那么，如果 cancelTime 在范围 \([T_0, T_0 + T_D]\) 内，则从时间线中移除该事件。

AudioParam.cancelScheduledValues() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
cancelTime	double	✘	✘	在此时间之后，任何先前计划的参数更改都将被取消。它与 AudioContext 的 currentTime 属性处于相同的时间坐标系中。 如果 cancelTime 为负数，则必须抛出 RangeError 异常。 如果 cancelTime 小于 currentTime，则将其钳位到 currentTime。

返回类型： AudioParam

exponentialRampToValueAtTime(value, endTime)

计划从上一个计划参数值到给定值的指数连续参数值变化。由于人类感知声音的方式，代表滤波器频率和播放速率的参数最好以指数方式进行更改。

时间间隔 \(T_0 \leq t < T_1\) 内的值（其中 \(T_0\) 是上一个事件的时间，\(T_1\) 是传入此方法的 endTime 参数）将按如下计算：

$$
    v(t) = V_0 \left(\frac{V_1}{V_0}\right)^\frac{t - T_0}{T_1 - T_0}
$$

其中 \(V_0\) 是时间 \(T_0\) 处的值，\(V_1\) 是传入此方法的 value 参数。如果 \(V_0\) 和 \(V_1\) 符号相反，或者 \(V_0\) 为零，则对于 \(T_0 \leq t < T_1\)，\(v(t) = V_0\)。

这也意味着指数斜坡到 0 是不可能的。使用 setTargetAtTime() 和适当选择的时间常数可以实现很好的近似。

如果在此 ExponentialRampToValue 事件之后没有更多事件，则对于 \(t \geq T_1\)，\(v(t) = V_1\)。

如果没有事件在该事件之前，指数斜坡的行为就好像调用了 setValueAtTime(value, currentTime)，其中 value 是属性的当前值，而 currentTime 是调用 exponentialRampToValueAtTime() 时上下文的 currentTime。

如果前一个事件是 SetTarget 事件，则 \(T_0\) 和 \(V_0\) 从 SetTarget 自动化的当前时间和值中选择。即，如果 SetTarget 事件尚未开始，\(T_0\) 为该事件的开始时间，\(V_0\) 为 SetTarget 事件开始前的值。在这种情况下，ExponentialRampToValue 事件有效地取代了 SetTarget 事件。如果 SetTarget 事件已经开始，\(T_0\) 为当前的上下文时间，\(V_0\) 为时间 \(T_0\) 处 SetTarget 自动化的当前值。在这两种情况下，自动化曲线都是连续的。

AudioParam.exponentialRampToValueAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
value	float	✘	✘	参数将在给定时间指数级斜坡到达的值。 如果此值等于 0，则必须抛出 RangeError 异常。
endTime	double	✘	✘	与 AudioContext 的 currentTime 属性处于相同时间坐标系下指数斜坡结束的时间。 如果 endTime 为负数或不是有限数字，则必须抛出 RangeError 异常。 如果 endTime 小于 currentTime，则将其钳位到 currentTime。

返回类型： AudioParam

linearRampToValueAtTime(value, endTime)

计划从上一个计划参数值到给定值的线性连续参数值变化。

时间间隔 \(T_0 \leq t < T_1\) 内的值（其中 \(T_0\) 是上一个事件的时间，\(T_1\) 是传入此方法的 endTime 参数）将按如下计算：

$$
    v(t) = V_0 + (V_1 - V_0) \frac{t - T_0}{T_1 - T_0}
$$

其中 \(V_0\) 是时间 \(T_0\) 处的值，\(V_1\) 是传入此方法的 value 参数。

如果在此 LinearRampToValue 事件之后没有更多事件，则对于 \(t \geq T_1\)，\(v(t) = V_1\)。

如果没有事件在该事件之前，线性斜坡的行为就好像调用了 setValueAtTime(value, currentTime)，其中 value 是属性的当前值，而 currentTime 是调用 linearRampToValueAtTime() 时上下文的 currentTime。

如果前一个事件是 SetTarget 事件，则 \(T_0\) 和 \(V_0\) 从 SetTarget 自动化的当前时间和值中选择。即，如果 SetTarget 事件尚未开始，\(T_0\) 为该事件的开始时间，\(V_0\) 为 SetTarget 事件开始前的值。在这种情况下，LinearRampToValue 事件有效地取代了 SetTarget 事件。如果 SetTarget 事件已经开始，\(T_0\) 为当前的上下文时间，\(V_0\) 为时间 \(T_0\) 处 SetTarget 自动化的当前值。在这两种情况下，自动化曲线都是连续的。

AudioParam.linearRampToValueAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
value	float	✘	✘	参数将在给定时间线性斜坡到达的值。
endTime	double	✘	✘	与 AudioContext 的 currentTime 属性处于相同时间坐标系下，自动化结束的时间。 如果 endTime 为负数或不是有限数字，则必须抛出 RangeError 异常。 如果 endTime 小于 currentTime，则将其钳位到 currentTime。

返回类型： AudioParam

setTargetAtTime(target, startTime, timeConstant)

在给定时间以给定的时间常数开始以指数方式趋向于目标值。除其他用途外，这对于实现 ADSR 包络的“衰减”和“释放”部分非常有用。请注意，参数值在给定时间不会立即变为目标值，而是逐渐变为目标值。

在时间间隔 \(T_0 \leq t\) 期间，其中 \(T_0\) 是 startTime 参数：

$$
    v(t) = V_1 + (V_0 - V_1)\, e^{-\left(\frac{t - T_0}{\tau}\right)}
$$

其中 \(V_0\) 是 \(T_0\) （startTime 参数）时的初始值（[[current value]] 属性），\(V_1\) 等于 target 参数，\(\tau\) 是 timeConstant 参数。

如果 LinearRampToValue 或 ExponentialRampToValue 事件跟随此事件，其行为分别在 linearRampToValueAtTime() 或 exponentialRampToValueAtTime() 中描述。对于所有其他事件，SetTarget 事件在下一个事件的时间结束。

AudioParam.setTargetAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
target	float	✘	✘	参数将在给定时间开始更改到的值。
startTime	double	✘	✘	指数趋近开始的时间，与 AudioContext 的 currentTime 属性处于相同时间坐标系中。 如果 start 为负数或不是有限数字，则必须抛出 RangeError 异常。 如果 startTime 小于 currentTime，则将其钳位到 currentTime。
timeConstant	float	✘	✘	一阶滤波器（指数）趋向目标值的时间常数值。此值越大，过渡越慢。 该值必须是非负数，否则必须抛出 RangeError 异常。 如果 timeConstant 为零，输出值会立即跳变至最终值。更准确地说，timeConstant 是一阶线性连续时不变系统在给定阶跃输入响应（从 0 到 1 值的过渡）时达到值 \(1 - 1/e\)（约 63.2%）所需的时间。

返回类型： AudioParam

setValueAtTime(value, startTime)

计划在给定时间更改参数值。

如果在此 SetValue 事件之后没有更多事件，则对于 \(t \geq T_0\)，\(v(t) = V\)，其中 \(T_0\) 是 startTime 参数，\(V\) 是 value 参数。换句话说，该值将保持不变。

如果此 SetValue 事件之后的下一个事件（时间为 \(T_1\)）不是 LinearRampToValue 或 ExponentialRampToValue 类型，则对于 \(T_0 \leq t < T_1\)

$$
    v(t) = V
$$

换句话说，该值在此时间间隔内将保持不变，允许创建“阶梯”函数。

如果此 SetValue 事件之后的下一个事件是 LinearRampToValue 或 ExponentialRampToValue 类型，请分别参阅 linearRampToValueAtTime() 或 exponentialRampToValueAtTime()。

AudioParam.setValueAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
value	float	✘	✘	参数将在给定时间更改到的值。
startTime	double	✘	✘	与 BaseAudioContext 的 currentTime 属性处于相同时间坐标系下，参数更改为给定值的时间。 如果 startTime 为负数或不是有限数字，则必须抛出 RangeError 异常。 如果 startTime 小于 currentTime，则将其钳位到 currentTime。

返回类型： AudioParam

setValueCurveAtTime(values, startTime, duration)

设置一系列任意参数值，从给定时间开始持续给定持续时间。值的数量将被缩放以适合所需的持续时间。

设 \(T_0\) 为 startTime，\(T_D\) 为 duration，\(V\) 为 values 数组，\(N\) 为 values 数组的长度。那么，在时间间隔 \(T_0 \le t < T_0 + T_D\) 期间，设

$$
    \begin{align*} k &= \left\lfloor \frac{N - 1}{T_D}(t-T_0) \right\rfloor \\
    \end{align*}
$$

那么 \(v(t)\) 通过在 \(V[k]\) 和 \(V[k+1]\) 之间进行线性插值计算得出，

在曲线时间间隔结束（\(t \ge T_0 + T_D\)）之后，该值将保持在最终曲线值不变，直到出现另一个自动化事件（如果有）。

在时间 \(T_0 + T_D\) 处对 setValueAtTime() 进行隐式调用，值为 \(V[N-1]\)，以便后续自动化将从 setValueCurveAtTime() 事件的末尾开始。

AudioParam.setValueCurveAtTime() 方法的参数。

参数	类型	可为空 (Nullable)	可选 (Optional)	描述
值	sequence<float>	✘	✘	代表参数值曲线的浮点值序列。这些值将从给定时间开始应用，并持续给定的持续时间。当调用此方法时，会出于自动化目的创建曲线的内部副本。因此，后续对传入数组内容的修改对 AudioParam 没有影响。 如果此属性是一个长度小于 2 的 sequence<float> 对象，则必须抛出 InvalidStateError 异常。
startTime	double	✘	✘	与 AudioContext 的 currentTime 属性处于相同时间坐标系下，将应用值曲线的开始时间。 如果 startTime 为负数或不是有限数字，则必须抛出 RangeError 异常。 如果 startTime 小于 currentTime，则将其钳位到 currentTime。
duration	double	✘	✘	（在 startTime 参数之后）值将根据 values 参数计算的时间秒数。 如果 duration 不是严格正数或不是有限数字，则必须抛出 RangeError 异常。

返回类型： AudioParam