オーディオHALは、それを通してアプリケーションがオーディオハードウェアへのアクセスを可能にする、抽象的概念を提供する。
これを達成するために、HALはシステムの様々な構成部位へのアクセスを行う、小さなAudioObject
セットを備える。
全てのAudioObject
はプロパティの集合を持ち、状態の取得や操作を行うことが出来る。プロパティは三次元座標(ordered triple)的にアクセスされる。
1つめの軸はプロパティを分類する(describe)セレクタである。
他の2つの軸はAudioObject
の特定の部分を識別するスコープとエレメントで、その中からセレクタを探す。
AudioObjectPropertyAddress
構造体はプロパティのアドレスをカプセル化する。
プロパティの値は型付けされていないデータブロックで、その内容はセレクターの仕様に依存する。
いくつかのセレクタは問い合わせ時に修飾データ(qualifier)を要求する。
修飾データはプロパティ操作のために使う追加情報を提供する。
プロパティ値の変化は常に非同期であることを考慮せよ。
アプリケーションはAudioObjectHasProperty()
, AudioObjectIsPropertySettable()
とAudioObjectGetPropertyDataSize()
ルーチンを使い、プロパティに関する有益なメタ情報を取得する。
また、アプリはAudioObjectGetPropertyData()
とAudioObjectSetPropertyData()
でプロパティの値を操作する。
アプリはAudioObjectAddPropertyListener
()とAudioObjectRemovePropertyListener()
で、プロパティの値が変化した際に呼ばれる関数の登録と削除を行う。
AudioObject
のクラスは、どの機能がオブジェクトに作用するのか、またオブジェクトが実装する事を期待されるプロパティセットの観点から、そのオブジェクトの基本機能を決定づける。
オブジェクトのために利用可能なクラスセットは、ここで定義されているものに限られる。
これら以外のクラスは存在しない。
クラスセットは、あるクラスがその親クラスのプロパティやルーチンを継承するといった、階層構造にまとめられている。
全てのAudioObjectクラス群の基底クラスがAudioObject
クラスである。
そのようなものとして、AudioObject
クラスは、分類付けや人間が読める名前といった基本プロパティを提供し、各々のAudioObjectオブジェクトはそれらを持つ。
他の重要なクラスとして、AudioSystemObject
, AudioDevice
そしてAudioStream
がある。
HAL中のAudioObjectは包含階層で並べられている。
階層の根本は1つで、それはAudioSystemObject
クラスの唯一のインスタンスである。
AudioSystemObject
のプロパティは、様々なデフォルトデバイスや通知実行ループといった、プロセス全体にまたがる設定を表す。
またAudioSystemObject
は利用可能な全てのAudioDevice
を持つ。
AudioDevice
クラスのインスタンスは個々のオーディオ装置をカプセル化したものである。
AudioDevice
はI/Oの基本ユニットとしての役割を果たす。
AudioDevice
は、1つのI/Oサイクル、それに基づくタイミング源、そしてそれに同期する全てのバッファを提供する。
I/Oサイクルは同一呼び出し内で、全ての同期されたバッファを現在時間を指定するタイムスタンプと伴にクライアントに提供し、そしてその際、入力データが獲得され、また出力データも渡されるだろう。
AudioDevice
はAudioStream
クラスのインスタンスを含む。
AudioStream
はユーザー・カーネル領域にまたがって転送されるデータの1つのバッファを表す。
それだけに、AudioStream
はフォーマット情報の門番である。
各々がそれ自身のフォーマットと利用可能なフォーマットの一覧を持っている。
AudioStream
は、エンコードされたフォーマットや非オーディオフォーマットを含む、あらゆる形式のデータを提供することが出来る。
フォーマットがリニアPCMの場合、そのデータは常にネイティブエンディアンの32ビット浮動小数点数として表される。
ハードウェアの実際の物理フォーマットとの全ての変換は、デバイスドライバーによって行われる。
AudioDevice
とAudioStream
の両者は、AudioControl
クラスあるいはその多くのサブクラスのインスタンスを含むことが出来る。
AudioControl
は、ゲイン、ミュート、データソース選択などといった、そのオブジェクトの特定の側面を表し、操作するプロパティを提供する。
多くの共通コントロールは、AudioDevice
かAudioStream
のプロパティとして利用可能である。
AudioObjectAddPropertyListener |
説明 | プロパティ変化の通知を受け取るAudioObjectPropertyListenerProcを登録する。 |
引数 | AudioObjectID inObjectID | |
const AudioObjectPropertyAddress *inAddress | リスナーに通知されるプロパティ。 |
AudioObjectPropertyListenerProc inListener | リスナー |
void *inClientData | リスナーが呼ばれた際に渡されるユーザーデータのポインタ。 |
返値 | OSStatus | 成功または失敗を返す。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectGetPropertyData |
説明 | AudioObjectにプロパティを問い合わせ、指定したバッファにそのデータを置く。 |
引数 | AudioObjectID inObjectID | |
const AudioObjectPropertyAddress *inAddress | 問い合わせるプロパティを示すAudioObjectPropertyAddress |
UInt32 inQualifierDataSize | inQualifierDataが指しているバッファの大きさ。全てのプロパティが修飾データを要求するわけではなく、必要のないものは0にする。 |
const void*inQualifierData | 問い合わせるプロパティ値の決定に使われる修飾データのバッファ。全てのプロパティが修飾データを要求するわけではなく、必要のないものはNULLにする。 |
UInt32*ioDataSize | outDataが指しているバッファのサイズを渡す。関数呼び出し後、バッファの使用量が返る。 |
void*outData | AudioObjectがプロパティのデータを置くバッファ。 |
返値 | OSStatus | 成功または失敗を返す。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectGetPropertyDataSize |
説明 | AudioObjectにプロパティのデータサイズを問い合わせる。 |
引数 | AudioObjectID inObjectID | 問い合わせるAudioObject。 |
const AudioObjectPropertyAddress*inAddress | 問い合わせるプロパティを示すAudioObjectPropertyAddress |
UInt32 inQualifierDataSize | inQualifierDataが指しているバッファの大きさ。全てのプロパティが修飾データを要求するわけではなく、必要のないものは0にする。 |
const void*inQualifierData | 問い合わせるプロパティ値の決定に使われる修飾データのバッファ。全てのプロパティが修飾データを要求するわけではなく、必要のないものはNULLにする。 |
UInt32*outDataSize | プロパティデータが必要とするバイト数。 |
返値 | OSStatus | 成功または失敗を返す。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectHasProperty |
説明 | AudioObjectにプロパティを持っているかどうかを問い合わせる。 |
引数 | AudioObjectID inObjectID | 問い合わせるAudioObject。 |
const AudioObjectPropertyAddress*inAddress | 問い合わせるプロパティを示すAudioObjectPropertyAddress |
返値 | Boolean | AudioObjectがプロパティを持っているかどうか。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectIsPropertySettable |
説明 | AudioObjectにプロパティがAudioObjectSetPropertyDataで設定できるかどうか問い合わせる。 |
引数 | AudioObjectID inObjectID | 問い合わせるAudioObject |
const AudioObjectPropertyAddress*inAddress | 問い合わせるプロパティを示すAudioObjectPropertyAddress |
Boolean*outIsSettable | プロパティが設定可能かどうか |
返値 | OSStatus | 成功または失敗を返す。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectRemovePropertyListener |
説明 | プロパティ変化時の通知の受信リストからAudioObjectPropertyListenerProcの登録を解除する。 | |
引数 | AudioObjectID inObjectID | リスナーの登録を解除するAudioObject |
const AudioObjectPropertyAddress*inAddress | 削除するリスナーのプロパティを示すAudioObjectPropertyAddress |
AudioObjectPropertyListenerProc inListener | 削除するリスナー |
void*inClientData | リスナー呼び出し時に渡されるユーザーデータへのポインタ |
返値 | OSStatus | 成功または失敗を返す。 |
互換性 | Mac OS X v10.4以降 |
AudioObjectSetPropertyData |
説明 | 与えられたデータでAudioObjectのプロパティを変更する。 | |
引数 | AudioObjectID inObjectID | 変更するAudioObject |
const AudioObjectPropertyAddress*inAddress | 変更するプロパティを示すAudioObjectPropertyAddress |
UInt32 inQualifierDataSize | inQualifierDataが指しているバッファの大きさ。全てのプロパティが修飾データを要求するわけではなく、必要のないものは0にする。 |
const void*inQualifierData | 問い合わせるプロパティ値の決定に使われる修飾データのバッファ。全てのプロパティが修飾データを要求するわけではなく、必要のないものはNULLにする。 |
UInt32 inDataSize | inDataが指すバッファのサイズ |
const void*inData | 変更するプロパティデータを含むバッファ |
返値 | OSStatus | 成功または失敗を返す。 |
詳解 | プロパティの多くが非同期的に変更されると共に、HALがリスナーを呼び出すまで、値が反映されたと見なすべきではない。 | |
互換性 | Mac OS X v10.4以降 |
AudioObjectShow |
説明 | AudioObjectのテキスト形式の説明を標準出力に表示する。 |
引数 | AudioObjectID inObjectID | 表示するAudioObject |
返値 | void | |
互換性 | Mac OS X v10.4以降 |
- kAudioDevicePropertyPlugIn
OSStatus
AudioDevice用のIOAudioドライバープラグイン読込みで発生する何らかのエラーコード、もしくはプラグイン読込みが成功すればkAudioHardwareNoErrorを得る。このプロパティはプラグイン読込みに対応するIOAudioベースAudioDeviceドライバーにのみ存在する。
- kAudioDevicePropertyConfigurationApplication
CFString
AudioDevice設定GUIを提供するアプリケーションのバンドルID。デフォルト値はオーディオMIDI設定.appのバンドルIDである。返されたCFObjectの解放は呼び出し側が責を負う。
- kAudioDevicePropertyDeviceUID
CFString
AudioDeviceの永続的な識別子。AudioDeviceのUIDはシステムの起動をまたいでも持続する。UID文字列の中身はブラックボックスであり、個々のAudioDeviceハードウェアインスタンスに特有、ないしCPUに特有の内容を含む可能性がある。故に、それらはCPU間の受け渡しやハードウェアの類似モデルの識別には適さない。
- kAudioDevicePropertyModelUID
CFString
AudioDeviceの型番の永続的な識別子。この識別子は、たとえ2つのAudioDeviceが同一製造元の全く同一のモデルだったとしても一意である。加えて、識別子はそのAudioDeviceが現れるマシンを問わず同一であるべきである。
- kAudioDevicePropertyTransportType
UInt32
AudioDeviceとCPUの接続方法。Constants for some of the values for this property can be found in .
- kAudioDevicePropertyRelatedDevices
AudioDeviceIDの配列
関連するAudioDevice装置を表す。IOAudioベースの装置では、同一のIOAudioDeviceオブジェクトを共有するAudioDevic同士は関連付けられる。
- kAudioDevicePropertyClockDomain
UInt32
AudioDeviceが属するクロックドメイン。同じ値を持つAudioDeviceはハードウェア的に同期を取ることが出来る。しかし、値が0の場合、そのデバイスのクロックドメインは不定であることを表し、他の全てのデバイスから分離されていると考えるべし。たとえ、それらが同様にクロックドメインとして0を持っていたとしても。
- kAudioDevicePropertyDeviceIsAlive
UInt32
1はデバイスの準備が出来ており利用可能、0はデバイスは利用可能だが間もなく使えなくなることを表す。
- kAudioDevicePropertyDeviceHasChanged
UInt32 (ただし値に意味はない)
このプロパティは、 クライアントによるAudioDevice
の監視と、さもなければ他の通知方法では伝播されないデバイスの設定変更を知るために存在する。この通知に応えて、クライアントはそのデバイスについて知る必要のある事項、とりわけレイアウトとコントロール値を再評価すべきである。
- kAudioDevicePropertyDeviceIsRunning
UInt32
0はAudioDeviceがIO処理を行っていない状態、1は処理を行っている状態を表す。留意すべきは、IOProcにNULLを渡しAudioDeviceStart()を呼ぶといった、実効性のないIOProcでもデバイスは走るという事である。また、このプロパティの通知は常にAudioDeviceのIOスレッドから送信される点にも留意されたい。
- kAudioDevicePropertyDeviceIsRunningSomewhere
UInt32
1はAudioDeviceがシステムの少なくとも1つのプロセスで実行中、0は全く実行していない状態を表す。
- kAudioDevicePropertyDeviceCanBeDefaultDevice
UInt32
1はAudioDeviceがkAudioHardwarePropertyDefaultInputDeviceかkAudioHardwarePropertyDefaultOutputDeviceの選択肢となれる事を示す。どちらのプロパティかはスコープに依存する。
- kAudioDevicePropertyDeviceCanBeDefaultSystemDevice
UInt32
1はAudioDeviceがkAudioHardwarePropertyDefaultSystemOutputDeviceの選択肢となれる事を示す。
- kAudioDeviceProcessorOverload
UInt32 (ただし値に意味はない)
このプロパティは、AudioDeviceがIOサイクルのデッドラインを超えてしまった時に、それをクライアントに通知するために存在している。留意すべきは、本プロパティの通知は常にAudioDeviceのIOスレッドから送信される事である。
- kAudioDevicePropertyHogMode
pid_t
現在AudioDeviceに排他アクセスを行っているプロセスIDを表す。-1の時は全てのプロセスで利用可能な事を示す。AudioDeviceがnon-mixableモードの場合、そのHALはIOProcを開始する最初のプロセスに代わって自動で占有モード(hog mode)に切り替わる。
- kAudioDevicePropertyLatency
UInt32
AudioDeviceの遅延フレーム数を表す。入力と出力の遅延時間は異なる可能性に注意すべきである。加えて、AudioDeviceのAudioStreamは更なる遅延を持つ可能性があるため、同様に問い合わせるべし。入出力デバイスとその各ストリームにレイテンシがあった場合、ストリームの総レイテンシはデバイスレイテンシとストリームレイテンシの合算である。
- kAudioDevicePropertyBufferFrameSize
UInt32
IOバッファのフレーム数を表す。
- kAudioDevicePropertyBufferFrameSizeRange
AudioValueRange
kAudioDevicePropertyBufferFrameSizeに関する最少~最大の包括的な値を表す。
- kAudioDevicePropertyUsesVariableBufferFrameSizes
UInt32
装置によって実装されている場合、IOProcに渡されるバッファサイズが微少に変化する事を示す。本プロパティ値は渡される最大バッファサイズを表し、そしてkAudioDevicePropertyBufferFrameSize
はIOProcに渡される最小バッファを表す。本プロパティの使い方は狭く、バッファサイズがkAudioDevicePropertyBufferFrameSize
よりも少し増加する事を装置に許可するだけである。必要とした際に装置が自由にバッファを送信する権利を、装置に付与することを意図したものではない。より正確には、ハードウェアの自然なリズムに不可欠なRather, it is intended to allow for hardware whose natural rhythms lead to this necessity.
A UInt32 that, if implemented by a device, indicates that the sizes of the buffers passed to an IOProc will vary by a small amount. The value of this property will indicate the largest buffer that will be passed and kAudioDevicePropertyBufferFrameSize will indicate the smallest buffer that will get passed to the IOProc. The usage of this property is narrowed to only allow for devices whose buffer sizes vary by small amounts greater than kAudioDevicePropertyBufferFrameSize. It is not intended to be a license for devices to be able to send buffers however they please. Rather, it is intended to allow for hardware whose natural rhythms lead to this necessity.
- kAudioDevicePropertyStreams
AudioStreamID配列
AudioDeviceのAudioStreamを表す。このプロパティの通知を受け取った場合、そのデバイスの取得済みAudioStreamIDは全て無効となり、再取得が必要な点に留意されたし。
- kAudioDevicePropertySafetyOffset
UInt32
ハードウェアの現在の状態から安全にIO処理を行うために必要なフレーム数を示す。出力の場合は先行フレーム数、入力の場合は後続フレーム数となる。
- kAudioDevicePropertyIOCycleUsage
Float32
A Float32 whose range is from 0 to 1. This value indicates how much of the client portion of the IO cycle the process will use. The client portion of the IO cycle is the portion of the cycle in which the device calls the IOProcs so this property does not the apply to the duration of the entire cycle.
- kAudioDevicePropertyStreamConfiguration
AudioBufferList (バッファポインタはNULLに設定される)
装置のストリーム一覧と各ストリームのチャンネル数を示すストリーム構造を返す。これはIOProcに渡されるであろう構造と一致する。
- kAudioDevicePropertyIOProcStreamUsage
AudioHardwareIOProcStreamUsage
structure which details the stream usage of a given IO proc. If a stream is marked as not being used, the given IOProc will see a corresponding NULL buffer pointer in the AudioBufferList passed to it's IO proc. Note that the number of streams detailed in the AudioHardwareIOProcStreamUsage must include all the streams of that direction on the device. Also, when getting the value of the property, one must fill out the mIOProc field of the AudioHardwareIOProcStreamUsage with the address of the of the IOProc whose stream usage is to be retrieved.
- kAudioDevicePropertyPreferredChannelsForStereo
UInt32配列
デバイスのステレオIOと使用するチャンネル番号の関係を示す。第1要素が左チャンネルで、第2要素が右チャンネルである。このプロパティは入力と出力で異なる値を取ることができ、使用するチャンネル番号に制限はない。
- kAudioDevicePropertyPreferredChannelLayout
AudioChannelLayout
AudioDeviceのチャンネルをそれぞれどのように使うべきかを表す。
- kAudioDevicePropertyNominalSampleRate
Float64
AudioDeviceの現在の公称サンプリングレート。
- kAudioDevicePropertyAvailableNominalSampleRates
AudioValueRangeの配列
AudioDeviceの公称サンプリングレートの有効な範囲。
- kAudioDevicePropertyActualSampleRate
Float64
AudioDeviceのタイムスタンプによって計測された現在の実際のサンプリングレート。
AudioStream
はAudioObject
のサブクラスで、ただ1つのスコープkAudioObjectPropertyScopeGlobal
を持つ。
それらはマスターエレメントと、チャンネル毎にストリーム内で1から番号付けされるエレメントを持つ。
AudioDevice
が所有する複数のAudioStream
オブジェクト間で、AudioControl
オブジェクトが共有される点に注意されたい。
その結果として、AudioDevice
によって実装される標準的なAudioControl
関連のプロパティセレクタの全ては、AudioStream
によっても実装される。
このようなプロパティには同じ定数が使用される。