Web 音频 API 1.1

介绍

到目前为止，Web 上的音频功能一直相当基础，而且直到 最近还必须通过 Flash 和 QuickTime 等插件来提供。HTML5 中引入 audio 元素 非常重要，它允许进行基本的流式音频播放。但是，它 的功能还不足以处理更复杂的音频应用程序。对于 复杂的基于 Web 的游戏或交互式应用程序，需要另一种 解决方案。本规范的目标是包含 现代游戏音频引擎中的功能，以及现代 桌面音频制作应用程序中的一些 混音、处理和滤波任务。

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

特性

该 API 支持以下主要特性：

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

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

• 采样精确的计划声音播放， 为鼓机和音序器等 要求极高节奏精度的音乐应用程序提供低延迟。 这还包括 动态创建效果的可能性。

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

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

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

• 使用来自 MediaStream 的实时音频输入， 该 getUserMedia() 获取。

• 与 WebRTC 集成

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

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

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

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

  • 声像定位模型：equalpower、HRTF、直通

  • 距离衰减

  • 声音锥体

  • 阻挡 / 遮蔽

  • 基于声源 / 监听者

• 用于各种 线性效果的卷积引擎，尤其适用于高质量房间效果。 以下是一些可能的效果示例：

  • 小型 / 大型房间

  • 大教堂

  • 音乐厅

  • 洞穴

  • 隧道

  • 走廊

  • 森林

  • 圆形剧场

  • 透过门口听到的远处房间声音

  • 极端滤波器

  • 奇异的反向效果

  • 极端梳状滤波器效果

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

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

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

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

• 振荡器

模块化路由

模块化路由允许不同 AudioNode 对象之间进行任意连接。每个节点都可以具有 输入和/或 输出。 源节点没有 输入，只有一个输出。 目标节点 有一个输入且没有输出。滤波器等其他节点 可以放置在源节点与目标节点之间。当两个对象连接在一起时， 开发者无需担心底层流格式 的细节； 系统会自动执行正确的处理。 例如，如果单声道音频流连接到 立体声输入，它应该直接适当地 混合到左右声道。

在最简单的情况下，可以将单个源直接路由到输出。 所有路由都发生在一个 AudioContext 中，其中包含单个 AudioDestinationNode：

为了说明这种简单路由，下面是播放单个声音的简单示例：

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();    // 创建效果节点。    lowpassFilter = context.createBiquadFilter();    waveShaper = context.createWaveShaper();    panner = context.createPanner();    compressor = context.createDynamicsCompressor();    reverb = context.createConvolver();    // 创建主湿声和干声。    mainDry = context.createGain();    mainWet = context.createGain();    // 将最终压缩器连接到最终目标。    compressor.connect(context.destination);    // 将主干声和湿声连接到压缩器。    mainDry.connect(compressor);    mainWet.connect(compressor);    // 将混响连接到主湿声。    reverb.connect(mainWet);    // 创建几个源。    source1 = context.createBufferSource();    source2 = context.createBufferSource();    source3 = context.createOscillator();    source1.buffer = manTalkingBuffer;    source2.buffer = footstepsBuffer;    source3.frequency.value = 440;    // 连接 source1    dry1 = context.createGain();    wet1 = context.createGain();    source1.connect(lowpassFilter);    lowpassFilter.connect(dry1);    lowpassFilter.connect(wet1);    dry1.connect(mainDry);    wet1.connect(reverb);    // 连接 source2    dry2 = context.createGain();    wet2 = context.createGain();    source2.connect(waveShaper);    waveShaper.connect(dry2);    waveShaper.connect(wet2);    dry2.connect(mainDry);    wet2.connect(reverb);    // 连接 source3    dry3 = context.createGain();    wet3 = context.createGain();    source3.connect(panner);    panner.connect(dry3);    panner.connect(wet3);    dry3.connect(mainDry);    wet3.connect(reverb);    // 立即启动这些源。    source1.start(0);    source2.start(0);    source3.start(0);}

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

function setupRoutingGraph() {    const context = new AudioContext();    // 创建提供调制信号的低频振荡器    const lfo = context.createOscillator();    lfo.frequency.value = 1.0;    // 创建要被调制的高频振荡器    const hfo = context.createOscillator();    hfo.frequency.value = 440.0;    // 创建一个增益节点，其增益决定调制信号的振幅    const modulationGain = context.createGain();    modulationGain.gain.value = 50;    // 配置图并启动振荡器    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 接口，它是一个 AudioNode， 用于从 AudioBuffer 生成音频。

• 一个 AudioDestinationNode 接口，它是一个 AudioNode 子类，表示所有渲染音频的最终 目标。

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

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

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

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

• 一个 AudioWorkletNode 接口，它是一个 AudioNode， 表示在 AudioWorkletProcessor 中处理的节点。

• 一个 AudioWorkletProcessor 接口， 表示音频工作线程中的单个节点实例。

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

  • 低通

  • 高通

  • 带通

  • 低架

  • 高架

  • 峰值

  • 陷波

  • 全通

• 一个 ChannelMergerNode 接口，它是一个 AudioNode， 用于将多个 音频流中的声道合并为单个音频流。

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

• 一个 ConstantSourceNode 接口，它是一个 AudioNode， 用于生成名义上的恒定输出值， 并带有一个 AudioParam 以允许自动控制该值。

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

• 一个 DelayNode 接口，它是一个 AudioNode， 用于应用可动态调整的 可变延迟。

• 一个 DynamicsCompressorNode 接口，它是一个 AudioNode， 用于动态范围压缩。

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

• 一个 IIRFilterNode 接口，它是一个 AudioNode， 用于通用 IIR 滤波器。

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

• 一个 MediaStreamAudioSourceNode 接口，它是一个 AudioNode， 其音频源来自 MediaStream， 例如实时音频输入或远程对等端。

• 一个 MediaStreamTrackAudioSourceNode 接口， 它是一个 AudioNode， 其音频源来自 MediaStreamTrack。

• 一个 MediaStreamAudioDestinationNode 接口， 它是一个 AudioNode， 它是发送到远程对等端的 MediaStream 的音频目标。

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

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

• 一个 OscillatorNode 接口，它是一个 AudioNode， 用于生成周期波形。

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

• 一个 WaveShaperNode 接口，它是一个 AudioNode， 用于应用非线性波形整形 效果，以产生失真和其他更细微的暖化效果。

• 一个 AudioPlaybackStats 接口，它提供有关 AudioContext 所播放音频的统计信息。

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" ，[[state before interruption]] 也取自 AudioContextState 的值， 并且最初设置为 null，还有一个私有槽 [[render quantum size]]，它是一个无符号整数。

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

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 状态发生变化时 派发到 BaseAudioContext 的事件设置事件处理程序（即对应的 promise 将会被兑现时）。此事件处理程序的事件类型为 statechange。一个使用 Event 接口的事件将被派发到事件 处理程序，该处理程序可以直接查询 AudioContext 的状态。新创建的 AudioContext 始终以 suspended 状态开始，并且每当状态变化为不同状态时 都会触发状态变化事件。此 事件会在 complete 事件触发之前 触发。

sampleRate，类型为 float，只读

BaseAudioContext 处理音频时的采样率（以每秒采样帧数为单位）。 假定上下文中的所有 AudioNode 都以此速率运行。由于这一假设， 实时处理中不支持采样率转换器或 "varispeed" 处理器。 奈奎斯特频率是此采样率值的一半。

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() 方法的参数。

参数	类型	可为空	可选	说明
numberOfChannels	unsigned long	✘	✘	确定缓冲区将具有多少个声道。实现必须支持至少 32 个声道。
length	unsigned long	✘	✘	以采样帧为单位确定缓冲区的大小。该值必须至少为 1。
sampleRate	float	✘	✘	描述缓冲区中线性 PCM 音频数据的采样率，以每秒采样帧数 表示。有关必须支持的范围，请参阅§ 2.4 支持的采样率。

返回类型： AudioBuffer

createBufferSource()

用于 AudioBufferSourceNode 的工厂方法。

无参数。

返回类型： AudioBufferSourceNode

createChannelMerger(numberOfInputs)

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

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

参数	类型	可为空	可选	说明
numberOfInputs	unsigned long	✘	✔	确定输入数量。必须支持最多 32 的值。如果未指定， 则使用 6。

返回类型： ChannelMergerNode

createChannelSplitter(numberOfOutputs)

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

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

参数	类型	可为空	可选	说明
numberOfOutputs	unsigned long	✘	✔	输出数量。必须支持最多 32 的值。如果未指定，则 使用 6。

返回类型： ChannelSplitterNode

createConstantSource()

用于 ConstantSourceNode 的工厂方法。

无参数。

返回类型： ConstantSourceNode

createConvolver()

用于 ConvolverNode 的工厂方法。

无参数。

返回类型： ConvolverNode

createDelay(maxDelayTime)

用于 DelayNode 的工厂方法。 初始默认 延迟时间为 0 秒。

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

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

返回类型： DelayNode

createDynamicsCompressor()

用于 DynamicsCompressorNode 的工厂方法。

无参数。

返回类型： DynamicsCompressorNode

createGain()

用于 GainNode 的工厂方法。

无参数。

返回类型： GainNode

createIIRFilter(feedforward, feedback)

BaseAudioContext.createIIRFilter() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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) 方法的参数。

参数	类型	可为空	可选	说明
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 中包含的音频文件数据。 例如，可以在将 responseType 设置为 "arraybuffer" 后， 从 XMLHttpRequest 的 response 属性加载 ArrayBuffer。 音频文件数据可以采用 audio 元素支持的任何格式。传递给 decodeAudioData() 的缓冲区，其 内容类型按照 [mimesniff] 中所述通过嗅探确定。

尽管与此函数交互的主要方式 是通过其 promise 返回值，但为了 兼容旧版仍提供回调参数。

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

注：如果压缩音频数据字节流已损坏，但 解码在其他方面仍可继续，则鼓励实现警告 作者，例如通过开发者工具。

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

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

2. 令 promise 为一个新的 Promise。

3. 如果 audioData 尚未分离，执行以下步骤：

   1. 将 promise 追加到 [[pending promises]]。

   2. 分离 audioData ArrayBuffer。 如果此操作抛出异常，则跳转到步骤 4.1。

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

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

   1. 令 error 为一个 DataCloneError。

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

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

5. 返回 promise。

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

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

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

2. 尝试确定 audioData 的 MIME 类型， 使用 MIME 嗅探 § 6.2 匹配音频或视频类型模式。如果音频 或 视频类型模式匹配算法返回 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() 方法的参数。

参数	类型	可为空	可选	说明
audioData	ArrayBuffer	✘	✘	包含压缩音频数据的 ArrayBuffer。
successCallback	DecodeSuccessCallback?	✔	✔	解码完成时将调用的回调函数。此回调的唯一 参数是表示已解码 PCM 音频数据的 AudioBuffer。
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 允许实现释放其所有 资源，此后它不能再次使用或恢复。

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

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;
    attribute EventHandler onsinkchange;
    attribute EventHandler onerror;
    [SameObject] readonly attribute AudioPlaybackStats playbackStats;
    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， 分别表示当前音频输出设备的标识符 或信息。初始值为 ""，表示默认音频输出 设备。

[[sink ID at construction]]

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

[[pending resume promises]]

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

[[playback stats]]

用于存储 AudioPlaybackStats 实例的槽。

1.2.1. 构造函数

AudioContext(contextOptions)

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

创建 AudioContext 时，执行以下步骤：

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

2. 将 context 上的 [[control thread state]] 设置为 suspended。

3. 将 context 上的 [[rendering thread state]] 设置为 suspended。

4. 将 context 上的 [[state before interruption]] 设置为 null。

5. 令 messageChannel 为一个新的 MessageChannel。

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

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

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

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

10. 将控制消息排队， 以使用 serializedRenderingSidePort 在 AudioContextGlobalScope 上设置 MessagePort。

11. 如果给出了 contextOptions，执行以下 子步骤：

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

       1. 如果 sinkId 和 [[sink ID]] 都是 DOMString 类型， 并且二者相等，则中止这些 子步骤。

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

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

       4. 如果 sinkId 是 AudioSinkOptions 类型，则将 [[sink ID at construction]] 设置为一个新的 AudioSinkInfo 实例，该实例使用 sinkId 的 type 值创建。

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

    3. 如果 contextOptions.sampleRate 已指定，则将 context 的 sampleRate 设置为该值。否则，执行以下子步骤：

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

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

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

       注： 如果需要重采样， context 的延迟可能会 受到影响，并且影响可能很大。

    4. 根据 contextOptions.renderSizeHint 的值，设置 context 的 [[render quantum size]]：

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

       2. 否则，如果其值为 "hardware"，则将 [[render quantum size]] 私有槽设置为 0。

       3. 否则，如果传入了整数，并且该值超出 § 2.5 支持的渲染量子 大小中指定的范围，则必须 抛出 NotSupportedError； 否则将 [[render quantum size]] 私有槽设置为传入的值。

12. 如果 context 允许启动，则发送一条 控制 消息以开始处理。

13. 将 [[playback stats]] 设置为一个新的 AudioPlaybackStats 实例。

14. 返回 context。

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

1. 令 validationResult 为对 [[sink ID at construction]] 进行接收器标识符验证 的返回值。

2. 如果 validationResult 为 false，执行以下步骤：

   1. 将 [[sink ID]] 设置为空字符串。

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

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

   • 对于空字符串，使用默认音频输出设备。

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

     1. 如果资源获取失败，则将媒体元素 任务排队，以在 AudioContext 上触发一个名为 error 的事件，并 中止后续步骤。

4. 将 [[sink ID]] 设置为 [[sink ID at construction]] 的值。

5. 将 AudioContext 上的 this [[rendering thread state]] 设置为 running。

6. 将媒体元素任务排队以执行 以下步骤：

   1. 如果 AudioContext 的 [[render quantum size]] 为 0， 则将其设置为资源获取期间选择的实际硬件渲染量子大小。

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

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

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

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

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

2. 将 port 设置为 deserializedPort。

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

参数	类型	可为空	可选	说明
contextOptions	AudioContextOptions	✘	✔	用于控制应如何构造 AudioContext 的用户指定选项。

1.2.2. 属性

baseLatency, 类型为 double，只读

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

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

outputLatency, 类型为 double，只读

音频输出延迟的估计值，以秒为单位，即 用户代理请求主机系统播放缓冲区的时刻与 缓冲区中的第一个采样实际由音频输出设备 处理的时刻之间的间隔。对于 扬声器或耳机等产生声学 信号的设备，后一个时刻指采样的 声音产生的时刻。

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

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

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

onsinkchange, 类型为 EventHandler

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

注： 在 AudioContext 构造过程中的初始 设备选择不会派发此事件。 可以使用 statechange 事件 来检查初始输出设备是否已就绪。

onerror, 类型为 EventHandler

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

• 初始化和激活选定音频设备时发生故障。

• 与 AudioContext 关联的音频输出设备在 上下文处于 running 状态时断开连接。

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

playbackStats, 类型为 AudioPlaybackStats，只读

此 AudioContext 的 AudioPlaybackStats 实例。 返回 [[playback stats]] 内部槽的值。

1.2.3. 方法

close()

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

调用 close 时，执行以下步骤：

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

2. 令 promise 为一个新的 Promise。

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

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

5. 将控制消息排队， 以关闭 AudioContext。

6. 返回 promise。

运行一条控制 消息以关闭 AudioContext 意味着在 渲染 线程上运行以下步骤：

1. 尝试释放 系统资源。

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

   这将停止渲染。

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

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

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

   1. 兑现 promise。

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

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

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

当 AudioContext 被关闭时，任何连接到 AudioContext 的 MediaStream 和 HTMLMediaElement 的输出都将被忽略。也就是说，它们将不再向 扬声器或其他输出设备产生任何输出。若需要更灵活的 行为，请考虑使用 HTMLMediaElement.captureStream()。

注： 当 AudioContext 已关闭时，实现可以 选择比暂停时更积极地释放更多资源。

无参数。

返回类型： Promise<undefined>

createMediaElementSource(mediaElement)

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

AudioContext.createMediaElementSource() 方法的参数。

参数	类型	可为空	可选	说明
mediaElement	HTMLMediaElement	✘	✘	将被重新路由的媒体元素。

返回类型： MediaElementAudioSourceNode

createMediaStreamDestination()

创建一个 MediaStreamAudioDestinationNode

无参数。

返回类型： MediaStreamAudioDestinationNode

createMediaStreamSource(mediaStream)

创建一个 MediaStreamAudioSourceNode。

AudioContext.createMediaStreamSource() 方法的参数。

参数	类型	可为空	可选	说明
mediaStream	MediaStream	✘	✘	将充当源的媒体流。

返回类型： MediaStreamAudioSourceNode

createMediaStreamTrackSource(mediaStreamTrack)

创建一个 MediaStreamTrackAudioSourceNode。

AudioContext.createMediaStreamTrackSource() 方法的参数。

参数	类型	可为空	可选	说明
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， 所获得估计值的准确性就越高。

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

无参数。

返回类型： AudioTimestamp

resume()

当 AudioContext 已被暂停时，恢复其 currentTime 的推进。

调用 resume 时， 执行以下步骤：

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

2. 令 promise 为一个新的 Promise。

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

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

5. 如果上下文的 state 属性为 "suspended" 并且上下文的 [[control thread state]] 为 "interrupted"， 则：

   1. 将媒体元素任务排队以 执行以下步骤：

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

      2. 将 [[state before interruption]] 槽设置为 "running"。

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

   2. 使用 InvalidStateError 拒绝 promise， 中止这些 步骤，并返回 promise。

6. 如果上下文不允许启动，则将 promise 追加到 [[pending promises]] 和 [[pending resume promises]] 中，并中止 这些步骤，返回 promise。

7. 将 AudioContext 上的 [[control thread state]] 设置为 running。

8. 将控制消息排队， 以使用 promise 恢复 AudioContext。

9. 返回 promise。

运行一条控制 消息以恢复 AudioContext 意味着在 渲染 线程上运行以下步骤：

1. 令 promise 为传入此算法的 promise。

2. 尝试获取系统资源。

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

4. 开始渲染音频图。

5. 如果失败， 将媒体元素任务排队以执行以下步骤：

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

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

6. 将媒体元素任务排队以执行以下步骤：

   1. 如果 AudioContext 的 [[render quantum size]] 为 0， 则将其设置为资源获取期间选择的实际硬件渲染量子大小。

   2. 按顺序兑现 [[pending resume promises]] 中的所有 promise。

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

   4. 兑现 promise。

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

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

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

无参数。

返回类型： Promise<undefined>

suspend()

暂停 AudioContext 的 currentTime 的推进， 允许任何已经处理完成的 当前上下文处理块播放到目标，然后允许系统 释放其对音频硬件的占用。这通常在 应用程序知道一段时间内不需要 AudioContext 并希望暂时 释放系统资源 与 AudioContext 关联时很有用。 当帧缓冲区 为空（已移交给硬件）时，promise 会兑现；如果上下文已经 suspended，则立即兑现 （且不会产生其他影响）。如果上下文 已关闭，则 promise 会被拒绝。

调用 suspend 时，执行以下步骤：

1. 如果 this 的相关全局对象的关联 Document不是完全活动的，则返回一个以 "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. 将控制消息排队， 以使用 promise 暂停 AudioContext。

8. 返回 promise。

运行一条控制 消息以暂停 AudioContext 意味着在 渲染 线程上运行以下步骤：

1. 令 promise 为传入此算法的 promise。

2. 尝试释放 系统资源。

3. 如果 AudioContext 上的 [[rendering thread state]] 为 "interrupted"， 则将媒体元素 任务排队，以将 [[state before interruption]] 槽设置为 "suspended"。

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

5. 将媒体元素任务排队以执行 以下步骤：

   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 进行接收器标识符验证 的返回值。

4. 如果 validationResult 为 false，则返回一个 以新 DOMException 拒绝的 promise，该异常的名称为 "NotAllowedError"。 中止这些步骤。

5. 令 p 为一个新的 promise。

6. 发送一条带有 p 和 sinkId 的控制消息以开始 处理。

7. 返回 p。

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

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

2. 令 sinkId 为传入此算法的接收器标识符。

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. 处理完当前渲染量子后暂停渲染器。

8. 尝试释放 系统资源。

9. 如果 wasRunning 为 true：

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

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

      1. 如果 AudioContext 的 state 属性尚未为 "suspended"：

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

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

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

    • 对于空字符串，使用默认音频输出设备。

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

    如果失败，则使用 "InvalidAccessError" 拒绝 p， 并中止 后续步骤。

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

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

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

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

    4. 兑现 p。

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

12. 如果 wasRunning 为 true：

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

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

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

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

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

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 or double)，默认值为 "interactive"

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

latencyHint 的首选值是 AudioContextLatencyCategory 中的一个值。 不过，也可以指定一个 double，表示延迟秒数，以便更精细地控制延迟与功耗 之间的平衡。如何适当地解释 该数值由浏览器自行决定。实际使用的延迟由 AudioContext 的 baseLatency 属性给出。

sampleRate, 类型为 float

将要创建的 AudioContext 的 sampleRate 设置为此值。有关所需支持的范围，请参阅 § 2.4 支持的采样率。

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

sinkId, 类型为 (DOMString or AudioSinkOptions)

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

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

当传入整数时，这允许用户请求特定的渲染量子大小；如果未传入任何值或传入 "default"，则使用默认的 128 帧；如果指定了 "hardware"， 则要求用户代理选择合适的 渲染量子 大小。

有关所需支持的范围，请参阅§ 2.5 支持的渲染量子大小。

这只是一个提示，可能不会被遵循。

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.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(optional unsigned long? chunkSize = null);
    Promise<undefined> resume();
    Promise<undefined> suspend(double suspendTime);
    Promise<undefined> close();
    readonly attribute unsigned long? length;
    attribute EventHandler oncomplete;
};

OfflineAudioContext 具有以下内部槽：

[[rendering started]]

表示渲染是否已开始的布尔标志。其 初始值为 false。

[[rendered buffers]]

正在渲染的 AudioBuffer 的有序列表。初始 值为空列表。

[[committed frames]]

跟踪 OfflineAudioContext 已提交进行渲染的帧数。初始值为 0。

[[rendered frames]]

跟踪已经渲染的帧数。初始值 为 0。

1.3.1. 构造函数

OfflineAudioContext(contextOptions)

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

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

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

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

3. 根据 contextOptions.sampleRate 的值，设置 c 的 sampleRate。

4. 根据 contextOptions.renderSizeHint 的值，确定 c 的 [[render quantum size]]：

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

   2. 否则，如果传入了一个整数，并且该值超出 § 2.5 支持的渲染量子大小 中指定的范围，则必须 抛出 NotSupportedError； 否则将 [[render quantum size]] 私有槽设置为传入的值。

5. 构造一个 AudioDestinationNode， 并将其 channelCount 设置为 contextOptions.numberOfChannels。

6. 令 messageChannel 为一个新的 MessageChannel。

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

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

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

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

11. 将控制消息排队， 以使用 serializedRenderingSidePort 在 AudioContextGlobalScope 上设置 MessagePort。

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

参数	类型	可为空	可选	说明
contextOptions				构造此上下文所需的初始参数。

OfflineAudioContext(numberOfChannels, length, sampleRate)

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

OfflineAudioContext 的构造效果等同于调用

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

。

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

参数	类型	可为空	可选	说明
numberOfChannels	unsigned long	✘	✘	确定缓冲区将具有多少个声道。有关支持的声道数量，请参阅 createBuffer()。
length	unsigned long	✘	✘	以采样帧为单位确定音频渲染的总大小。
sampleRate	float	✘	✘	描述缓冲区中线性 PCM 音频数据的采样率，以每秒采样帧数 表示。有关所需支持的范围，请参阅§ 2.4 支持的采样率。

1.3.2. 属性

length, 类型为 unsigned long，只读，可为空

以采样帧为单位表示音频渲染的总大小。该值与构造函数的 length 参数值相同。

对于未定义长度的渲染，此属性应该设置为 null。

oncomplete, 类型为 EventHandler

此事件处理程序的事件类型为 complete。派发到 该事件处理程序的事件将使用 OfflineAudioCompletionEvent 接口。它是在 OfflineAudioContext 上触发的最后一个事件。

1.3.3. 方法

startRendering(chunkSize)

根据当前连接和已计划的更改，开始 渲染音频。

尽管获取渲染后音频数据的主要方式 是通过其 promise 返回值，但出于兼容旧版的原因，该实例还会触发一个 名为 complete 的事件。

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

1. 如果 this 的相关全局对象的关联 Document不是完全活动的，则返回一个以 "InvalidStateError" DOMException 拒绝的 promise。
2. 令 promise 为一个新的 promise。
3. 如果 OfflineAudioContext 上的 [[control thread state]] 为 closed， 则使用 InvalidStateError 拒绝 promise，并中止这些 步骤。
4. 如果 OfflineAudioContext 的 length 不为 null，并且 [[committed frames]] 大于或等于 OfflineAudioContext 的 length， 则使用 InvalidStateError 拒绝 promise，并中止这些 步骤。
5. 令 bufferLength 为一个初始化为 chunkSize 值的数字。
   1. 如果 OfflineAudioContext 的 length 为 null：
      1. 如果 chunkSize 为 null，则将 bufferLength 设置为 渲染量子大小。
   2. 否则，如果 OfflineAudioContext 的 length 不为 null：
      1. 如果 chunkSize 不为 null，且 [[committed frames]] + chunkSize 小于 OfflineAudioContext 的 length， 则将 bufferLength 设置为 chunkSize。
      2. 否则，将 bufferLength 设置为 length - [[committed frames]]。
6. 如果 bufferLength 不是 渲染 量子大小的整数倍，则将其向上取整为下一个 渲染量子大小的整数倍。
7. 创建一个新的 AudioBuffer buffer，其声道数和采样率分别等于 在 contextOptions 参数中传递给此实例构造函数的 numberOfChannels 和 sampleRate 值； 长度等于 bufferLength。
8. 如果前面的 AudioBuffer 构造函数调用期间抛出了异常，则使用 此异常拒绝 promise，并返回 promise。
9. 将 [[rendering started]] 设置为 true。
10. 将 [[committed frames]] 设置为 [[committed frames]] 与 buffer 的 length 之和。
11. 将 buffer 追加到 [[rendered buffers]] 中，并为 buffer 开始离线渲染。
12. 将 promise 追加到 [[pending promises]]。
13. 返回 promise。

要为 AudioBuffer buffer 开始离线渲染，以下步骤必须发生在为此创建的渲染 线程上。

1. 根据当前连接和已计划的更改，开始将 buffer 的 length 个音频采样帧渲染到 buffer 中。
2. 对于每个渲染 量子，进行检查，并在必要时 suspend 渲染。
3. 如果已暂停的上下文恢复，则继续渲染 缓冲区。
4. 渲染完成后， 将媒体元素任务排队以执行以下步骤：
   1. 使用 buffer 兑现由 startRendering() 创建的 promise。
   2. 从 [[pending promises]] 中移除 promise。
   3. 从 [[rendered buffers]] 中移除 buffer。
   4. 将 [[rendered frames]] 设置为 [[rendered frames]] 与 buffer 的 length 之和。
   5. 如果 length 不为 null：
      1. 如果 [[rendered frames]] 大于或 等于 length， 则将 控制消息排队以关闭 OfflineAudioContext。
      2. 将媒体元素任务排队， 以使用 OfflineAudioCompletionEvent 在 OfflineAudioContext 上触发一个名为 complete 的事件，其中 renderedBuffer 属性设置为 buffer。

OfflineAudioContext.startRendering(chunkSize) 方法的参数。

参数	类型	可为空	可选	说明
chunkSize	unsigned long?	✔	✔	此调用期间要渲染的采样帧数。

返回类型： Promise<AudioBuffer>

resume()

当 OfflineAudioContext 已暂停时，恢复其 currentTime 的推进。

调用 resume 时， 执行以下步骤：

1. 如果 this 的相关全局对象的关联 Document不是完全活动的，则返回 一个以 "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. 兑现 promise。

   2. 如果 OfflineAudioContext 的 state 属性尚未为 "running"：

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

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

无参数。

返回类型： Promise<undefined>

suspend(suspendTime)

计划在指定时间暂停音频 上下文中的时间推进，并返回一个 promise。这通常适用于 在 OfflineAudioContext 上同步操作音频图时。

请注意，暂停的最大精度为 渲染量子 的大小，指定的暂停时间 将向上舍入到最近的渲染量子 边界。因此，不允许在同一个量化帧上计划 多次暂停。此外，为确保 精确暂停，应在上下文未运行时进行计划。

OfflineAudioContext.suspend() 方法的参数。

参数	类型	可为空	可选	说明
suspendTime	double	✘	✘	计划在指定时间暂停渲染，该时间会被量化并 向上舍入到渲染量子大小。如果量化后的帧号 为负数，或 小于或等于当前时间，或 大于或等于总渲染时长，或 同一时间已由另一个 suspend 进行计划， 则使用 InvalidStateError 拒绝 promise。

返回类型： Promise<undefined>

close()

关闭 OfflineAudioContext。 这不会自动释放 所有由 AudioContext 创建的 对象，但会暂停 AudioContext 的 currentTime 的推进，并停止 处理音频数据。

调用 close 时，执行以下步骤：

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

2. 令 promise 为一个新的 Promise。

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

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

5. 将控制消息排队， 以关闭 OfflineAudioContext。

6. 返回 promise。

运行一条控制 消息以关闭 OfflineAudioContext 意味着在渲染线程上运行以下步骤：

1. 将 [[rendering thread state]] 设置为 suspended。

   这将停止渲染。

2. 如果此控制消息是为了响应 文档被卸载而运行的，则中止此算法。

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

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

   1. 兑现 promise。

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

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

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

1.3.4. OfflineAudioContextOptions

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

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

1.3.4.1. 字典 OfflineAudioContextOptions 成员

length, 类型为 unsigned long，可为空，默认值为 null

渲染后的 AudioBuffer 的长度，以采样帧为单位。

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

此 OfflineAudioContext 的声道数量。

sampleRate, 类型为 float

此 OfflineAudioContext 的采样率。有关所需支持的范围，请参阅 § 2.4 支持的采样率。

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

用于此 OfflineAudioContext 的渲染量子大小的提示。 有关所需支持的范围，请参阅§ 2.5 支持的渲染量子大小。

1.3.5. OfflineAudioCompletionEvent 接口

这是一个出于兼容旧版原因而派发到 OfflineAudioContext 的 Event 对象。

[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 接口

此接口表示驻留在内存中的音频资源。它可以包含一个或 多个声道，其中每个声道表现为 32 位浮点 线性 PCM 值，标称 范围为 \([-1,1]\)，但这些 值并不限于该范围。通常预计 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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

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

返回类型： Float32Array

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

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

获取 AudioBuffer 内容操作会在以下情况下调用：

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

• 当 buffer 为 AudioBufferSourceNode 设置后，并且此前已经调用过 AudioBufferSourceNode.start， setter 会获取 内容 AudioBuffer。 如果该操作失败， 则不会播放任何内容。

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

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

注： 这意味着 copyToChannel() 不能用于更改 当前正由 已获取 AudioBuffer 内容的 AudioNode 所使用的 AudioBuffer 的内容，因为该 AudioNode 将继续使用此前 获取的数据。

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 为单位。有关所需支持的范围，请参阅§ 2.4 支持的采样率。

1.5. AudioNode 接口

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

每个输出都有一个或多个声道。确切的声道数量 取决于具体 AudioNode 的细节。

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

每个 AudioNode 的 输入在任何给定时刻都有特定数量的 声道。该数量可以根据连接到该输入的 连接发生变化。如果 输入没有连接，则它有一个静音声道。

对于每个输入，AudioNode 会对连接到该输入的所有连接执行 混音。 有关规范性要求和详细信息，请参阅§ 4 声道升混和降混。

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

[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 尾部时间

一个 AudioNode 可以具有尾部时间。这 意味着即使向 AudioNode 输入静音，其输出也可能不是静音。

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

1.5.3. AudioNode 生命周期

如果满足以下任一条件，AudioNode 在一个渲染量子期间可以 主动 处理。

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

• MediaElementAudioSourceNode 当且仅当其 mediaElement 在当前渲染量子的至少一部分时间中播放时，才会主动 处理。

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

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

• 当其输入或输出已连接时，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 配置声道 使用 AudioWorkletNodeOptions 配置声道。

ChannelMergerNode

声道数量不能更改，任何更改该值的尝试 都必须抛出 InvalidStateError 异常。

ChannelSplitterNode

声道数量不能更改，任何更改该值的尝试 都必须抛出 InvalidStateError 异常。

ConvolverNode

声道数量不能大于二，任何将其更改为 大于二的值的尝试 都必须抛出 NotSupportedError 异常。

DynamicsCompressorNode

声道数量不能大于二，任何将其更改为 大于二的值的尝试 都必须抛出 NotSupportedError 异常。

PannerNode

声道数量不能大于二，任何将其更改为 大于二的值的尝试 都必须抛出 NotSupportedError 异常。

ScriptProcessorNode

声道数量不能更改，任何更改该值的尝试 都必须抛出 NotSupportedError 异常。

StereoPannerNode

声道数量不能大于二，任何将其更改为 大于二的值的尝试 都必须抛出 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) 方法的参数。

参数	类型	可为空	可选	说明
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， 从而形成一个循环：一个 AudioNode 可以连接到另一个 AudioNode， 后者又连接回第一个 AudioNode 的输入或 AudioParam。

返回类型： AudioNode

connect(destinationParam, output)

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

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

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

AudioParam 会获取连接到它的任意 AudioNode 输出的已渲染音频 数据，如果它尚不是单声道，则通过 降混将其转换为单声道，然后将其与 其他此类输出混合，最后再与 内在参数值（即在没有任何 音频连接时 AudioParam 通常具有的 value）混合，其中包括为该参数 计划的任何时间线变化。

降混为单声道等价于一个 AudioNode 使用 channelCount = 1、 channelCountMode = "explicit"， 且 channelInterpretation = "speakers" 时的降混。

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

例如：

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

与以下代码具有相同的效果

nodeA.connect(param);

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

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

返回类型： undefined

disconnect()

断开 AudioNode 的所有传出连接。

无参数。

返回类型： undefined

disconnect(output)

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

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

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

返回类型： undefined

disconnect(destinationNode)

断开 AudioNode 中通往特定目标 AudioNode 的所有输出。

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

参数	类型	可为空	可选	说明
destinationNode				destinationNode 参数是要断开的 AudioNode。 它会断开通往给定 destinationNode 的所有传出连接。如果不存在通往 destinationNode 的连接，则必须抛出 InvalidAccessError 异常。

返回类型： undefined

disconnect(destinationNode, output)

将 AudioNode 的特定输出与某个目标 AudioNode 的任意及所有输入断开。

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

参数	类型	可为空	可选	说明
destinationNode				destinationNode 参数是要断开的 AudioNode。 如果给定输出不存在通往 destinationNode 的连接，则必须抛出 InvalidAccessError 异常。
output	unsigned long	✘	✘	output 参数是一个索引，用于描述从 AudioNode 的哪个输出断开。如果此参数越界， 则必须抛出 IndexSizeError 异常。

返回类型： undefined

disconnect(destinationNode, output, input)

将 AudioNode 的特定输出与某个目标 AudioNode 的特定输入断开。

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

参数	类型	可为空	可选	说明
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) 方法的参数。

参数	类型	可为空	可选	说明
destinationParam	AudioParam	✘	✘	destinationParam 参数是要断开的 AudioParam。 如果不存在通往 destinationParam 的连接，则必须抛出 InvalidAccessError 异常。

返回类型： undefined

disconnect(destinationParam, output)

将 AudioNode 的特定输出与特定目标 AudioParam 断开。 当此操作生效时，此 AudioNode 对计算参数值的贡献 变为 0。此操作不会影响内在 参数值。

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

参数	类型	可为空	可选	说明
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 属性，它们共同构成该参数的 简单标称 范围。实际上， 参数值会被钳制到范围 \([\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 异常。

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

可以通过将 automationRate 属性设置为以下值之一来选择 AudioParam 的自动化速率。不过，某些 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() 的行为相当复杂。因此， 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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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 \le t \lt 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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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() 方法的参数。

参数	类型	可为空	可选	说明
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[k]\) 和 \(V[k+1]\) 之间进行线性插值来计算 \(v(t)\)。

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

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

AudioParam.setValueCurveAtTime() 方法的参数。

参数	类型	可为空	可选	说明
values	sequence<float>	✘	✘	表示参数值曲线的一系列 float 值。这些值将从 给定时间开始，并持续给定的持续时间。调用此方法时， 会为自动化目的创建该曲线的内部副本。因此，之后 修改传入数组的内容不会影响 AudioParam。 如果此属性是长度小于 2 的 sequence<float> 对象，则必须抛出 InvalidStateError。
startTime	double	✘	✘	应用值曲线的开始时间，它使用与 AudioContext 的 currentTime 属性相同的时间坐标系。如果 startTime 为负数或不是有限 数，则必须抛出 RangeError 异常。如果 startTime 小于 currentTime， 则将其钳制为 currentTime。
duration	double	✘	✘	按照 values 参数计算值的时间量，以秒为单位 （在 startTime 参数之后）。如果 duration 不是严格正数或不是 有限数，则必须抛出 RangeError 异常。

返回类型： AudioParam