AudioParam: value プロパティ

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.

ウェブオーディオ APIAudioParam インターフェイスの value プロパティは、この AudioParam の現在の値を取得または設定します。初期状態では、値は AudioParam.defaultValue に設定されています。

value を設定すると、 AudioContextcurrentTime プロパティが返す時刻で AudioParam.setValueAtTime を呼び出すのと同じ効果があります。

現在の時刻におけるパラメーターの値を示す浮動小数点の値 (Number) です。この値は minValue および maxValue プロパティで指定された値の間になります。

使用上の注意

値の精度とばらつき

内部的に value を格納するために使用されるデータ型は単精度(32 ビット)の浮動小数点数ですが、 JavaScript では 64 ビットの倍精度浮動小数点数を用います。そのため、 value プロパティから読み込んだ値が、常に設定した値と一致するとは限りません。

この例を考えてください。

js
const source = new AudioBufferSourceNode(/* … */);
const rate = 5.3;
source.playbackRate.value = rate;
console.log(source.playbackRate.value === rate);

ログ出力は false になります。これは、再生レートのパラメーターである rate が 5.3 に最も近い 32 ビット浮動小数点数に変換され、5.300000190734863 となったためです。解決策の 1 つは、 value を設定する際に、指定した 64 ビットの JavaScript 値に相当する単精度の値を返す Math.fround() メソッドを使用することです。

js
const source = new AudioBufferSourceNode(/* … */);
const rate = Math.fround(5.3);
source.playbackRate.value = rate;
console.log(source.playbackRate.value === rate);

この場合、ログ出力は true になります。

時間とともに変化するプロパティの値

AudioParamvalue は固定されることもあれば、時間とともに変化することもあります。これは value ゲッターによって反映され、音声レンダリングエンジンの最新のレンダリングクォンタム(音声バッファーが処理され更新される瞬間)時点でのパラメーターの値を返します。音声バッファーが処理されるだけでなく、それぞれのレンダリングクォンタムは、現在の時刻と確立された時間ベースのパラメーターの値変更が指定された場合、必要に応じてそれぞれの AudioParamvalue を更新します。

パラメーターを最初に作成した時、その値は AudioParam.defaultValue で指定された既定値に設定されます。これは、 0.0 秒の時刻におけるパラメーターの値であり、値が変更される最初のレンダリングクォンタムまで、パラメーターの値のままです。

レンダリングクォンタムの間、ブラウザーはパラメーターの値を管理するために以下のことを行います。

  • value セッターが使用されてた場合、パラメーターの値は指定された値に変更されます。
  • 現在の時刻が前回 setValueAtTime() を呼び出して指定した時刻と等しいか超えている場合、 valuesetValueAtTime() に渡された値に変更されます。
  • 段階的または漸進的な値変更メソッドが呼び出され、現在の時刻が段階的な値変更を行うべき時間範囲内にある場合、値は適切なアルゴリズムに基づいて更新されます。これらの漸進的または段階的な値変更メソッドには linearRampToValueAtTime(), setTargetAtTime(), setValueCurveAtTime() があります。

このように、パラメーターの value は、時間経過に伴うパラメーターの状態を正確に反映するように維持されます。

この例では、 GainNode の音量を即座に 40% に変更します。

js
const audioCtx = new AudioContext();
const gainNode = audioCtx.createGain();
gainNode.gain.value = 0.4;
// 次のものと同じ
gainNode.gain.setValueAtTime(0.4, audioCtx.currentTime);

仕様書

Specification
Web Audio API
# dom-audioparam-value

ブラウザーの互換性

BCD tables only load in the browser

GainNode のゲイン値を変更する際、バージョン 64 (2018 年 1 月)以前の Google Chrome では、デジッパリングを防ぐためにスムーズな補間が行われていました。 バージョン 64 からは、ウェブオーディオ仕様に準拠するため、値が即座に変更されます。詳しくは Chrome Platform Status をご覧ください。

関連情報