オーディオ再生ストリーム
オーディオ再生ストリームを使用すると、一時停止、フラッシュ、再生バッファーへの書き込みなど、再生ストリームの制御を行うことができます。
- TOC
必要な権限
このAPIでは、特定の操作に特定の権限が必要です。
[[needs.privilege]]
id = "com.amazon.audio.privilege.settings.control"
このAPIには、システムオーディオサービスの宣言も必要です。
[wants]
[[wants.service]]
id = "com.amazon.audio.stream"
[[wants.service]]
id = "com.amazon.audio.control"
使用される型
オーディオコアタイプを参照してください
AudioStatusAudioAttributesAudioConfigAudioPlaybackEventAudioVolumeTypeStreamDuckingPolicyDuckingMode
メソッド
initCheckAsync()
説明
再生ストリームが初期化されているかどうかを確認します。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
オーディオ再生ストリームのステータスを取得し、statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.initCheckAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
getAudioConfigAsync()
説明
再生ストリームのオーディオ構成を取得します。
戻り値
AudioConfigオブジェクトに解決されるPromiseを返します。
サンプルコード
/*
再生ストリームのオーディオ構成を取得し、Promiseの解決後にconfigに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const config = playbackStream.getAudioConfigAsync()
.then((config) => {return config;}).catch((error) => console.log(error));
getAudioAttributesAsync()
説明
再生ストリームのオーディオ属性を取得します。
戻り値
AudioAttributesオブジェクトに解決されるPromiseを返します。
サンプルコード
/*
再生ストリームのオーディオ属性を取得し、Promiseの解決後にattributesに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const attributes = playbackStream.getAudioAttributesAsync()
.then((attributes) => {return attributes;}).catch((error) => console.log(error));
getSampleRateAsync()
説明
再生ストリームのサンプルレートを取得します。
戻り値
サンプルレートを表すInt32に解決されるPromiseを返します。
サンプルコード
/*
再生ストリームのサンプルレートを取得し、Promiseの解決後にsample_rateに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const sample_rate= playbackStream.getSampleRateAsync()
.then((rate) => {return rate;}).catch((error) => console.log(error));
getChannelCountAsync()
説明
再生ストリームのチャネル数を取得します。
戻り値
チャネル数を表すInt32に解決されるPromiseを返します。
サンプルコード
/*
再生ストリームのチャネル数を取得し、Promiseの解決後にchannel_countに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const channel_count = playbackStream.getChannelCountAsync()
.then((count) => {return count;}).catch((error) => console.log(error));
getSampleSizeAsync(**)
説明
再生ストリームのサンプルサイズを取得します。
戻り値
サンプルサイズを表すInt32に解決されるPromiseを返します。
サンプルコード
/*
再生ストリームのサンプルサイズを取得し、Promiseの解決後にsample_sizeに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const sample_size = playbackStream.getSampleSizeAsync()
.then((sample_size) => {return sample_size;}).catch((error) => console.log(error));
getNumBytesInPipelineAsync()
説明
クライアントとオーディオサーバー間のオーディオパイプラインによって消費されるのを待機している、パイプライン内のバイト数を取得します。
戻り値
パイプライン内のバイト数を表すInt32に解決されるPromiseを返します。
サンプルコード
/*
パイプライン内のバイト数を取得し、Promiseの解決後にpipeline_bytesに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const pipeline_bytes = playbackStream.getNumBytesInPipelineAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));
getNumBytesOfNativeBufferAsync()
説明
クライアントとオーディオサーバー間の共有バッファーのサイズを表すバイト数を取得します。
戻り値
ネイティブバッファー内のバイト数を表すInt32に解決されるPromiseを返します。
サンプルコード
/*
ネイティブバッファー内のバイト数を取得し、Promiseの解決後にbuffer_bytesに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const buffer_bytes = playbackStream.getNumBytesOfNativeBufferAsync()
.then((bytes) => {return bytes;}).catch((error) => console.log(error));
getFramesPerBufferAsync()
説明
バッファあたりのフレーム数を取得します。
戻り値
バッファーあたりのフレーム数を表すInt32に解決されるPromiseを返します。
サンプルコード
/*
ネイティブバッファー内のフレーム数を取得し、Promiseの解決後にbuffer_framesに
格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const buffer_frames = playbackStream.getFramesPerBufferAsync()
.then((frames) => {return frames;}).catch((error) => console.log(error));
getAudioFocusSessionIdAsync()
説明
フォーカスセッションIDを取得します。
戻り値
フォーカスセッションIDを表すInt32に解決されるPromiseを返します。
サンプルコード
/*
フォーカスセッションを取得し、Promiseの解決後にsession_idに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const session_id = playbackStream.getAudioFocusSessionIdAsync()
.then((id) => {return id;}).catch((error) => console.log(error));
getLatencyInMsAsync()
説明
レイテンシをミリ秒単位で取得します。
戻り値
レイテンシをミリ秒単位で表すInt32に解決されるPromiseを返します。
サンプルコード
/*
レイテンシをミリ秒単位で取得し、Promiseの解決後にlatencyに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const latency = playbackStream.getLatencyInMsAsync()
.then((latency) => {return latency;}).catch((error) => console.log(error));
pauseAsync()
説明
再生ストリームを一時停止します。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
オーディオ再生ストリームを一時停止し、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.pauseAsync().then((status) => {return status;}).catch((error) => console.log(error));
startAsync()
説明
再生ストリームを開始します。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
オーディオ再生ストリームを開始し、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.startAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
stopAsync()
説明
再生ストリームを停止します。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
オーディオ再生ストリームを停止し、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.stopAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
flushAsync()
説明
再生ストリームをフラッシュします。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
オーディオ再生ストリームをフラッシュし、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.flushAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
registerEventObserverAsync(callback)
説明
オーディオ変更イベントが検出されるたびに実行されるコールバック関数を登録します。登録できるコールバック関数は、一度に1つだけです。
戻り値
AudioStatus型に解決されるPromiseを返します。
パラメーター
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| callback | function | ○ | イベントを受け取り、そのイベントに基づいて処理を実行するコールバック関数。 |
サンプルコード
/*
関数を作成し、再生イベントオブザーバーに登録して、再生の変更が発生するたびに
この関数が実行されるようにします。Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const playbackStreamEventHandler = (event: any) => {
console.debug('playbackStreamEventHandlerイベントを受信しました ->', event);
switch (event.playbackStreamEvent) {
case AudioPlaybackEvent.DIED:
console.debug('ストリームが中断されました。ストリームID:', playbackStream.current);
break;
case AudioPlaybackEvent.RECOVERED:
console.debug('ストリームが復元されました。ストリームID:', playbackStream.current);
break;
case AudioPlaybackEvent.STOPPED:
console.debug('ストリームが停止しました。ストリームID:', playbackStream.current);
break;
case AudioPlaybackEvent.MUTE_STATE_UPDATE:
console.debug('ストリームのミュート状態が変更されました。ストリームID:', playbackStream.current);
console.debug('ミュート状態:', event.muteState);
break;
case AudioPlaybackEvent.FRAME_UNDERRUN:
console.debug('ストリームアンダーランが発生しました。ストリームID:', playbackStream.current);
console.debug('アンダーランの数:', event.underrunCount);
break;
default:
break;
}
};
const status = playbackStream.registerEventObserverAsync(playbackStreamEventHandler)
.then((status) => {return status;}).catch((error) => console.log(error));
unregisterEventObserverAsync(**)
説明
現在登録されているコールバック関数を登録解除します。
戻り値
AudioStatus型に解決されるPromiseを返します。
サンプルコード
/*
コールバック関数の登録を解除し、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.unregisterEventObserverAsync()
.then((status) => {return status;}).catch((error) => console.log(error));
writeAsync(buffer)
説明
bufferパラメーターに格納されているバイトを使用して再生バッファーに書き込みます。
戻り値
AudioStatus型に解決されるPromiseを返します。
パラメーター
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| buffer | ArrayBuffer | ○ | 再生バッファーに書き込むバイトを含むバッファー。 |
サンプルコード
/*
再生バッファーに書き込みを行い、Promiseの解決後に返されたAudioStatus型を
statusに格納します。
bufferはバッファーに書き込むバイトを含むUint8Arrayであると想定します。
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const status = playbackStream.writeAsync(buffer).then((status) => {return status;}).catch((error) => console.log(error));
getUnderrunSizeAsync()
説明
アンダーランサイズを照会するための取得用API。
クライアントがバッファーアンダーランしきい値を設定しており、再生バッファーがアンダーラン状態の場合、このAPIはバッファーサイズとしきい値の差を返します。
それ以外の場合、このAPIは0を返します。
戻り値
バッファーサイズとアンダーランしきい値のフレーム数の差を含むPromise(Int32)を返します。フレーム数は切り上げられます。
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const getUnderrunSizeAsyncTest = async () => {
try {
let underRunSize = await playbackStream.current?.getUnderrunSizeAsync();
console.debug("getUnderrunSizeAsync():", underRunSize);
} catch (error) {
console.debug('エラー:getUnderrunSizeAsync():', error);
}
}
getUnderrunSizeAsyncTest();
getUnderrunCountAsync()
説明
ストリームが存続している間に発生したアンダーランの数を照会するための取得用API。
戻り値
ストリームが存続している間に発生したアンダーランの数を含むPromise(Int32)を返します。
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const getUnderrunCountAsyncTest = async () => {
try {
let underRunCount = await playbackStream.current?.getUnderrunCountAsync();
console.debug("getUnderrunCountAsync():", underRunCount);
} catch (error) {
console.debug('エラー:getUnderrunCountAsync():', error);
}
}
getUnderrunCountAsyncTest();
getPresentedFrameCountAsync()
説明
オーディオパイプラインに既に提示され、受け入れられたオーディオフレームの数を照会するためのAPI。
戻り値
成功時にオーディオパイプラインに提示されたオーディオフレーム数を含むPromise(Int32)を返します。
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const getPresentedFrameCountAsyncTest = async () => {
try {
let presentedFrameCount = await playbackStream.current?.getPresentedFrameCountAsync();
console.debug("getPresentedFrameCountAsync():", presentedFrameCount);
} catch (error) {
console.debug('エラー:getPresentedFrameCountAsync():', error);
}
}
getPresentedFrameCountAsyncTest();
getDuckingPolicyAsync()
説明
オーディオパイプラインに既に提示され、受け入れられたオーディオフレームの数を照会するためのAPI。
戻り値
現在のAudioPlaybackStreamオブジェクトのduckingPolicyを含むPromise(Int32)を返します
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const getDuckingPolicyAsyncTest = async () => {
try {
const duckingPolicy = await playbackStream.current?.getDuckingPolicyAsync();
console.debug("getDuckingPolicyAsync:", duckingPolicy);
} catch (err) {
console.debug("getDuckingPolicyAsync() ERR:", err);
}
}
getDuckingPolicyAsyncTest();
duckVolumeAsync(mode, value, rampDuration)
説明
特定のストリームインスタンスの音量を基準にして、指定されたdBまたはパーセンテージでストリームの音量をダッキング/ダッキング解除するAPI。
戻り値
AudioStatus型に解決されるPromiseを返します(Int32)。
パラメーター
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| mode | DuckingMode | ○ | 音量をダッキングするモードを指定します。 |
| value | ArrayBuffer | ○ | DuckingMode::DBの場合、値は現在のストリームの音量から減衰させるdB数を示します(範囲: 0~144)。DuckingMode::PERCENTAGEの場合、値は現在のストリームの音量から減衰させる特定のパーセンテージを示します(範囲: 0~100)。値=0は、ストリームが元の音量までダッキング解除されないことを意味します。 |
| rampDuration | ArrayBuffer | ○ | 現在の音量からターゲットの音量までのランプ時間(ミリ秒単位)。 |
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const createAudioSourceInstance = async () => {
const builder = new AudioPlaybackStreamBuilder();
/*その他の構成
...
...
...*/
builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT); // ポリシーを明示的に設定します
const stream = await builder.buildAsync();
playbackStream.current = stream;
}
const duckVolumeAsyncTest = async () => {
try {
/*500ミリ秒で最大50%ダッキング*/
let duckStatus = await playbackStream.current?.duckVolumeAsync(DuckingMode.PERCENTAGE, 50, 500);
} catch (err) {
console.debug("duckVolumeAsync() ERR:", err);
}
/*現在の再生ストリームに関連付けられたオーディオを再生するメソッドがあると想定します*/
playClipDucked();
}
createAudioSourceInstance();
duckVolumeAsyncTest();
setVolumeAsync(gain)
説明
個々のストリームの音量を絶対ゲイン(パーセンテージ)で設定します。設定されたゲインがストリームの音量に乗算されます。
戻り値
現在のAudioPlaybackStreamオブジェクトのduckingPolicyを含むPromise(Int32)を返します
パラメーター
| パラメーター名 | 型 | 必須 | 説明 |
|---|---|---|---|
| gain | Int32 | ○ | 現在のストリームタイプの音量に適用されるゲイン。 |
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const createAudioSourceInstance = async () => {
const builder = new AudioPlaybackStreamBuilder();
/*その他の構成
...
...
...*/
builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT);
const stream = await builder.buildAsync();
playbackStream.current = stream;
}
const setVolumeAsyncTest = async () => {
try {
let setVolumeStatus = await playbackStream.current?.setVolumeAsync(70);
} catch (err) {
console.debug("setVolumeAsync() ERR:", err);
}
/*現在の再生ストリームに関連付けられたオーディオを再生するメソッドがあると想定します*/
playClip();
}
createAudioSourceInstance();
setVolumeAsyncTest();
getVolumeAsync()
説明
個々のストリームの音量を絶対ゲイン(パーセンテージ)で設定します。設定されたゲインがストリームの音量に乗算されます。
戻り値
現在のAudioPlaybackStreamオブジェクトのduckingPolicyを含むPromise(Int32)を返します
パラメーター
| パラメーター名 | 型 | 必須 | 説明 | | ————– | —- | ——– | ———– |
サンプルコード
/*
playbackStreamはAudioPlaybackStreamオブジェクトであると想定します。
*/
const createAudioSourceInstance = async () => {
const builder = new AudioPlaybackStreamBuilder();
/*その他の構成
...
...
...*/
builder.setDuckingPolicy(StreamDuckingPolicy.EXPLICIT);
const stream = await builder.buildAsync();
playbackStream.current = stream;
}
const setVolumeAsyncTest = async () => {
try {
let setVolumeStatus = await playbackStream.current?.setVolumeAsync(70);
} catch (err) {
console.debug("setVolumeAsync() ERR:", err);
}
}
const getVolumeAsyncTest = async () => {
try {
let currentStreamVolume = await playbackStream.current?.getVolumeAsync();
console.log("getVolumeAsync() 現在のストリームの音量:", currentStreamVolume);
} catch (err) {
console.debug("getVolumeAsync() ERR:", err);
}
}
createAudioSourceInstance();
setVolumeAsyncTest();
getVolumeAsyncTest();
Last updated: 2025年10月2日

