DOCSEARCHbyAlgolia
Submit Docs

Web Audio API v1.0 Specification

repository·main·Indexed 22 days ago

https://github.com/webaudio/web-audio-api

The official W3C Web Audio API v1.0 specification draft. This repository serves as the authoritative reference for audio processing implementation and usage within web browsers, including details on AudioContext, OfflineAudioContext, and render size configuration via renderSizeHint.

Tokens
1.3K
Snippets
3
Records
7
Agent score
28%

What's inside Web Audio API

  1. Overview of the Web Audio API 1.0 Spec

    main

    This repository hosts the latest editor's draft of the W3C Audio Working Group's Web Audio API v1.0 specification. Developers can use this repository to understand the formal requirements and standards for implementing or using the Web Audio API in web environments.

    You can preview the current live version of the specification on the hosted documentation site.

  2. Understand how renderSize interacts with latencyHint

    main

    The renderSize and latencyHint properties interact to determine the final latency of an AudioContext. The renderSize sets a floor for the minimum possible latency.

    • If renderSize is "default": The graph renders in 128-frame chunks, and latencyHint behaves normally.
    • If renderSize is "hardware": The graph renders using the hardware size. The resulting latency cannot be smaller than the hardware size.
    • If renderSize is a specific number: The graph renders using that value. The latencyHint cannot produce latencies less than this requested size.

    Example Behavior: If the hardware render size is 192 frames and you request an "interactive" latency hint, the UA will choose a latency that is a multiple of 192 frames (e.g., 192, 384, etc.).

  3. How to contribute tests for the Web Audio API

    main

    When proposing normative changes to the specification, you should also provide corresponding tests via web-platform-tests (wpt).

    Guidelines for testing:

    • Ideally, specification PRs and WPT PRs should be merged simultaneously.
    • Do not merge a test change that contradicts the spec before the spec change itself is merged.
    • If a specific feature is not practical to test, explain why in the PR and consider filing an issue in the WPT repository to track missing coverage. Use labels like type:untestable or type:missing-coverage to indicate status.

  4. Check the actual render size using BaseAudioContext.renderSize

    main

    Because the User Agent (UA) may round or clamp your requested renderSizeHint to a supported value, you should check the renderSize property on the BaseAudioContext to determine the actual number of frames being used to render the audio graph.

    const context = new AudioContext({
  renderSizeHint: 123 // Not a power of two
});

// The UA will round this to a supported value (e.g., 128)
console.log(context.renderSize);

  5. Configure the render size for an OfflineAudioContext

    main

    You can specify a preferred rendering size for an OfflineAudioContext using the renderSizeHint option in the OfflineAudioContextOptions dictionary.

    Note: For OfflineAudioContext, the value "hardware" is treated the same as "default" because there is no physical hardware output.

    renderSizeHint accepts either an AudioContextRenderSizeCategory or an unsigned long (number of frames). If an exact number is provided, it must be a power of two between 64 and 2048, inclusive.

    // Example: Requesting a specific render size for offline rendering
const offlineCtx = new OfflineAudioContext({
  numberOfChannels: 2,
  length: 48000,
  sampleRate: 48000,
  renderSizeHint: 512
});

  6. Configure the render size for an AudioContext

    main

    You can specify a preferred rendering size for an AudioContext using the renderSizeHint option in the AudioContextOptions dictionary. This allows you to optimize for hardware compatibility (e.g., on Android) or reduce function call overhead for AudioWorklet processing by requesting larger blocks.

    renderSizeHint accepts either an AudioContextRenderSizeCategory or an unsigned long (number of frames).

    • "default": Uses the standard 128-frame render quantum.
    • "hardware": Selects a size appropriate for the current output device (e.g., 192 frames on certain Android devices). For OfflineAudioContext, this is equivalent to "default".
    • unsigned long: Requests an exact number of frames. Supported values must be powers of two between 64 and 2048, inclusive. If a requested value is not supported, the User Agent (UA) will round up to the next smallest supported value.
    // Example: Requesting hardware-optimized render size
const context = new AudioContext({
  renderSizeHint: 'hardware'
});

// Example: Requesting a specific large buffer size to reduce overhead
const context = new AudioContext({
  renderSizeHint: 1024
});