翻訳元:Audio Queue Services Programming Guide: About Audio Queues
本章では、Mac OS XにおけるAudio Queueの能力、アーキテクチャ、そして内部の仕組みを学びます。 Audio Queueサービスが録音や再生に使用する、Audio Queue、Audio Queue Buffer、そしてコールバック関数を紹介します。 また、Audio Queueのステータスやパラメータについても見ていきます。 本章を終える頃には、あなたはこの技術を効果的に使うために必要となる概念を、理解していることでしょう。
Audio Queueは、Mac OS Xで音声の記録、再生を行うために使用するソフトウェアオブジェクトです。
AudioQueueRef
という不透明型で表され、AudioQueue.h
ヘッダファイルで宣言されています。
Audio Queueは以下の働きをします:
Audio Queueは他のCore Audioインタフェースと一緒に利用することが出来、比較的少ないコード量でアプリケーションに完全なデジタル音声の記録、再生策を構築します。
全てのAudio Queueは、以下の構成要素から成る同じ一般的な構造を持ちます:
アーキテクチャは、Audio Queueの用途が録音なのか再生なのかによって変わります。 その違いは、Audio Queueが自身の入出力を接続方法と、コールバック関数の役割にあります。
録音用途のAudio QueueはAudioQueueNewInput
関数で生成され、図1-1で示す構造を持ちます。
録音用Audio Queueの入力側は通常、マイクといった外部の音声ハードウェアと接続されます。 標準の状態では(in the default case)、音声はユーザーがシステム環境設定で設定した、システムのデフォルト音声入力装置から入ってきます。
録音用Audio Queueの出力側は、あなたが記述するコールバック関数を利用します。 ディスクに記録する時は、バッファがAudio Queueから受信した新しい音声データを、コールバックが音声ファイルへと記録します。 しかし、録音用Audio Queueの用途はファイルへの書き込みだけに留まりません。 例えばもう1つの使い方として、リアルタイム音声解析にも利用できます。 このような場合、コールバックは音声データを直接アプリケーションに提供すればよいでしょう。
“録音用Audio Queueのコールバック関数” で、このコールバックについてより詳しく学びます。
全てのAudio Queueは、録音であろうが再生であろうが、1つないしそれ以上のAudio Queue Bufferを持ちます。 これらバッファは、Buffer Queueと呼ばれる特定の配列の中に配置されます。 図中、Audio Queue Bufferは(データで)埋められた順に番号付けがなされます。これは、バッファがコールバックに渡された順番と一致します。
“Buffer Queueとエンキュー”で、Audio Queueがそのバッファを扱う方法について学びます。
再生用途のAudio Queue(AudioQueueNewOutput
関数で生成されます)は、図1-2に示す構造を持ちます。
再生用Audio Queueでは、コールバックは入力側にあります。 そのコールバックは、ディスク(または他のソース)から音声データの取得と、Audio Queueへのデータ引き渡しの責任を負います。 また、再生コールバックは再生するデータが無くなった際、Audio Queueに停止指示を伝えます。 “再生用Audio Queueのコールバック関数” で、このコールバックについてより詳しく学びます。
再生用Audio Queueの出力は通常、スピーカといった外部音声ハードウェアに接続されます。 標準の状態では(in the default case)、音声はユーザーがシステム環境設定で設定した、システムのデフォルト音声出力装置から出力されます。
Audio Queue Bufferは、AudioQueue.h
ヘッダファイルで宣言されている、AudioQueueBufferRef
型のデータ構造です:
typedef struct AudioQueueBuffer { const UInt32 mAudioDataBytesCapacity; void *const mAudioData; UInt32 mAudioDataByteSize; void *mUserData; } AudioQueueBuffer; typedef AudioQueueBuffer *AudioQueueBufferRef;
上記リスト中で強調表記されている(訳註:本Wikiの仕様上、ここでは強調表記されていません)mAudioData
領域はバッファを指していますが、本質的には、録音や再生に使用される音声データの一時的な塊を格納する、メモリ区画です。
(構造体の)他のメンバが持つ情報は、Audio Queueがバッファを管理するのに使用されます。
Audio QueueはAudio Queue Bufferをいくつでも持つことが出来ます−つまり、アプリケーションで幾つ必要かを決めます。 通常、この個数は3個です。 これにより、バッファの1つがディスクへの書き出しで使用される一方で、2つめのバッファで新しい音声データの受け取りを可能にします。 残りの3つ目のバッファは、ディスク入出力の遅延等を吸収する目的で、必要となれば利用されます。 図1-3は、その様子を示しています。
Audio Queueは、これらバッファの全てのメモリ管理を行います。 この仕掛け(helps)は、開発者がアプリケーションに録再機能を追加する労力を低減(improve)します。 またこれは、資源利用の最適化も図ります。
AudioQueueBuffer
データ構造の完全な解説は、Audio Queue Services Referenceをご覧下さい。
The buffer queue is what gives audio queues, and indeed Audio Queue Services, their names. “Audio Queueのアーキテクチャ”では、Buffer Queue−順番に並んだバッファ列-を見て来ました。 それでは、録音、再生におけるBuffer Queueの管理のし方について学びましょう。 特に、Audio Queue BufferをBuffer Queueに追加する、エンキューについて学習します。 実装するものが録音か再生かに因らず、エンキューはコールバックがしなければならない仕事です。
録音の場合、Audio Queue Bufferの1つは、マイクなどの入力装置から得られる音声データで埋められます。 Buffer Queue中の残りのバッファは、現在使用中のバッファの後ろに並べられ、音声データで埋められる順番を待ちます。
Audio Queueは得られたバッファ順に、バッファを音声データで満たし、コールバックに渡します。 図1-3はAudio Queueを用いた録音作業の様子を示しています。
図1-3の手順1で、録音を開始します。 Audio Queueは得た音声データでバッファを埋めます。
手順2において、最初のバッファは既に埋められています。 Audio Queueはコールバックを呼び出し、コールバックに満タンのバッファ(buffer 1)を渡します。 手順3で、コールバックはそのバッファの中身を音声ファイルへ書き出します。 時を同じくして、Audio Queueは別のバッファ(buffer 2)を新しく得られたデータで埋めます。
手順4で、コールバックは書き出しが終わったバッファ(buffer 1)を、キューの最後に加え(enqueue)、そして再度データで埋められる状態にします。 手順5で、Audio Queueは再びコールバックを呼び、満タンとなった次のバッファ(buffer 2)を渡します。 手順6で、コールバックはこのバッファの中身を音声ファイルに書き出します。 この定常データ取得状態(looping steady state)は、ユーザーが録音を停止するまで続けられます。
再生の場合、Audio Bufferの1つが、スピーカなどの出力装置に送られます。 Buffer Queue中の残りのバッファは、現在使用中のバッファの後ろに並べられ、再生される番を待ちます。
Audio Queueは再生される順番に、音声データを入れるバッファをコールバックに渡します。 コールバックは新しい音声データを読み込みこんでバッファへと格納し、それからバッファをキューの最後尾へと追加します(enqueue)。 図1-4はAudio Queueを用いた再生作業の方法を示しています。
図1-4の手順1で、アプリケーションは再生用Audio Queueの準備をします。
アプリケーションは、個々のAudio Queue Bufferのために1度コールバックを呼び出し、それらを音声データで満たしBuffer Queueへと追加します。
このデータ充填作業は、アプリケーションがAudioQueueStart
関数を呼んだ際(手順2)、再生が直ぐに始まる事を保証します。
手順3で、Audio Queueは最初のバッファ(buffer 1)を出力に送ります。
最初のバッファが再生されると直ちに、再生用Audio Queueは定常データ取得状態(looping steady state)へと移行します。 Audio Queueは次のバッファ(buffer2)の再生を開始し(手順4)、コールバックを呼び(手順5)、先ほど再生されたバッファ(buffer 1)を渡します。 手順6で、コールバックはそのバッファを音声ファイルからのデータで埋め、再生に向けバッファをキューに追加します。
Audio Queue Bufferは必ず、キューに追加された順番で再生されます。
しかし、Audio Queue ServiceはAudioQueueEnqueueBufferWithParameters
関数で、この再生過程の制御を可能としています。
この関数で出来る事は以下の通りです:
再生利得に関するより詳しい情報は、“Audio Queueのパラメータ”をご覧下さい。
AudioQueueEnqueueBufferWithParameters
関数の完全な解説については、Audio Queue Services Referenceをご覧下さい。
典型的に、Audio Queue Serviceを利用したプログラミング作業の大部分が、Audio Queueコールバック関数の記述に費やされます。
録音中や再生中は、Audio QueueコールバックはAudio Queueによって繰り返し呼び出されます。 呼び出し間隔(the time between calls)は、Audio Queueのバッファ容量に依存し、通常、0.5秒〜3、4秒(several seconds)程度の範囲になります。
Audio Queueコールバックの責任の1つは、それが録音か再生かに拘らず、Buffer QueueへAudio Queue Bufferを返す事です。
コールバックは、AudioQueueEnqueueBuffer
関数を用いて、バッファをBuffer Queueの最後へ加えます。
再生の場合は、必要とあればその代わりに、“再生過程の制御”で解説したAudioQueueEnqueueBufferWithParameters
関数を使う事ができます。
本項は、あなたが記述するであろう、ディスク上のファイルへ録音するという一般的なコールバックを紹介します。
以下はAudioQueue.h
ヘッダファイルで宣言されている、録音用Audio Queueコールバックのプロトタイプです:
AudioQueueInputCallback ( void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer, const AudioTimeStamp *inStartTime; UInt32 inNumberPacketDescriptions, const AudioStreamPacketDescription *inPacketDescs );
コールバック呼び出しにおいて、録音用Audio Queueは、コールバックが前に続く次の音声データ集合を音声ファイルに書き出すために必要となる、全ての情報を提供します:
AudioFileID
型)、そしてそのファイルの音声データ形式を含む、あなたの設定した独自の構造体です。
AudioFileWritePackets
関数に渡します。CBR(固定ビットレート)形式では、パケット記述子は使いません。CBR記録の場合、Audio Queueは本引数とinPacketDescs引数をNULLにします。
AudioFileWritePackets
関数(Audiofile.h
ヘッダで宣言)に渡します。
録音コールバックのより詳しい情報については、本資料の“音声の記録”をご覧下さい。また、合わせてAudio Queue Services Referenceもご覧下さい。
本項は、あなたが記述するであろう、ディスク上のファイルから音声を再生するという一般的なコールバックを紹介します。
以下はAudioQueue.h
ヘッダファイルで宣言されている、再生用Audio Queueコールバックのプロトタイプです:
AudioQueueOutputCallback ( void *inUserData, AudioQueueRef inAQ, AudioQueueBufferRef inBuffer );
コールバック呼び出しにおいて、再生用Audio Queueは、コールバックが次の音声データ集合を音声ファイルから読み出すために必要となる、全ての情報を提供します:
AudioFileID
型)、そしてそのファイルの音声データ形式を含む、あなたの設定した独自の構造体です。再生用Audio Queueでは、コールバックはこの構造体中に要素を設けて、現在のパケット番号(packet index)を保持しなければなりません。
アプリケーションがVBRのデータを再生する場合、コールバックは読み込んだ音声データのパケット情報を必要とします。
これにはAudioFile.h
ヘッダファイルで宣言されている、AudioFileReadPackets
関数を呼びます。
それから、再生用Audio Queueがパケット情報を利用できるように、それを独自データ構造体の中に設置します。
再生用コールバックのより詳しい情報は、本資料の“音声の再生”をご覧下さい。また、併せて Audio Queue Services Reference もご覧下さい。
Audio Queue Serviceは、必要とあらば音声形式の変換にコーデック(音声データの符号化/復号を行うコンポーネント)を使用します。 録音、再生アプリケーションはインストールされているコーデックの、全ての音声形式を使う事が出来ます。 様々な音声形式を扱うために、独自のコードを記述する必要はありません。 具体的に言うと、コールバックはデータ形式について知る必要がありません。
コーデックが作用する様子を見ていきましょう。
各々のAudio Queueは、AudioStreamBasicDescription
構造体で表現される、音声データ形式を持ちます。
あなたが−構造体のmFormatID
フィールドで−形式を指定すると、Audio Queueは適切なコーデックを使用します。
更にまた、標本化周波数やチャンネル数を指定すると、同様に反映されます。
“音声の記録”や“音声の再生”で、音声データ形式の設定例を見る事ができます。
録音用Audio Queueは、図1-5に示すようにインストール済みのコーデックを使用します。
図1-5の手順1で、アプリケーションはAudio Queueに録音の開始を伝え、そしてまた、使用するデータ形式も伝えます。 手順2で、Audio Queueは新しい音声データを取得し、あまたが指定した形式に基づくコーデックを使い、データを変換します。 それからAudio Queueはコールバックを呼び、変換済み音声データを含むバッファを渡します。 手順3で、コールバックは変換済み音声データをディスクへ書き出します。 もう一度言いますが、コールバックはデータ形式について知っている必要はないのです。
再生用Audio Queueは、図1-6に示すようにインストール済みのコーデックを使用します。
図1-6の手順1は、アプリケーションがAudio Queueに再生の開始を伝え、そしてまた、再生する音声ファイルが持つでデータ形式も伝えます。 手順2で、Audio Queueがコールバックを呼び出し、音声ファイルからデータを読み込みます。 コールバックはそのデータを、読み込んだままの形式でAudio Queueに渡します。 手順3で、Audio Queueは適切なコーデックを使用し、音声を出力先へと送ります。
Audio Queueは、Mac OS Xが最初から対応しているものだろうが、サードパーティが提供したものだろうが、インストール済みの全コーデックを使う事が出来ます。
使用するコーデックを指定するには、Audio QueueのAudioStreamBasicDescription
構造体に、4文字から成るコーデックIDを設定します。
この設定例は“音声の記録”で見る事が出来ます。
Mac OS Xは、CoreAudioTypes.h
ヘッダファイルで宣言され、Core Audio Data Types Referenceで明文化されている、形式ID列挙子一覧からわかるように、広範囲に渡る音声コーデックを持ちます。
あなたは、Audio ToolboxフレームワークのAudioFormat.h
ヘッダファイルに含まれるインタフェースを用いて、システムで利用可能なコーデックの中から決定することができます。
Fiendishthngsアプリケーションを使って、システムの持つコーデックを表示することが出来ます。このサンプルコードはhttp://developer.apple.com/samplecode/Fiendishthngs/にあります。
Audio Queueの一生は、生成(creation)で始まり開放(disposal)で終わります。
アプリケーションはこのライフサイクルの管理と、Audio Queueの状態の制御をAudioQueue.h
ヘッダファイルで宣言される、6つの関数で行います:
AudioQueueStop)は、同期モードと非同期モードで使う事ができます:
Audio Queueの同期/非同期停止の詳しい情報も含め、これら関数の完全な解説はAudio Queue Services Referenceをご覧下さい。
Audio Queueはパラメータと呼ばれる、変更可能な設定を持ちます。 それぞれのパラメータは、キーとなる列挙定数と、値となる浮動小数点値を持ちます。 通常、パラメータは再生で使用され、録音では使用されません。
Mac OS X v10.5で、唯一使用可能なAudio Queueパラメータは、利得(gain)です。
このパラメータの値の設定や取得は、kAudioQueueParam_Volume
定数を使い、0.0の無音から1.0の単位利得(unity gain)までの値が利用できます。
アプリケーションがAudio Queueパラメータを設定するには、2つの方法があります:
#未訳:This lets you assign audio queue settings that are, in effect, carried by an audio queue buffer as you enqueue it. この変更はAudio Queue Bufferが再生を開始したときに反映されます。
どちらの場合も、Audio Queueのパラメータ設定は、それらを変更するまで持続(remain)します。
AudioQueueGetParameter関数で、いつでもAudio Queueの現在のパラメータ値にアクセスできます。 パラメータ値の設定/取得に関係する関数の完全な解説は、Audio Queue Services Referenceをご覧下さい。