AudioHardware.h 抄訳

オーディオ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のプロパティとして利用可能である。

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のタイムスタンプによって計測された現在の実際のサンプリングレート。

kAudioDevicePropertyJackIsConnected

UInt32

0ならばエレメントとスコープに対応するジャックに何も差さっていない事を意味する。AudioBooleanControlのサブクラスAudioJackControlで実装されている。

kAudioDevicePropertyVolumeScalar

Float32

音量。0.0～1.0の値を取る。AudioControlのサブクラスAudioVolumeControlで実装されている。

kAudioDevicePropertyVolumeDecibels

Float32

音量のdB値。 AudioControlのサブクラスAudioVolumeControlで実装されている。

kAudioDevicePropertyVolumeRangeDecibels

AudioValueRange

制御可能な最小～最大のdB値。AudioControlのサブクラスAudioVolumeControlで実装されている。

kAudioDevicePropertyVolumeScalarToDecibels

Float32

音量のスカラー値を入力に取り、等価なdB値を出力する。AudioControlのサブクラスAudioVolumeControlで実装されている。

kAudioDevicePropertyVolumeDecibelsToScalar

Float32

音量のdB値を入力に取り、等価なスカラー値を出力する。AudioControlのサブクラスAudioVolumeControlで実装されている。

kAudioDevicePropertyStereoPan

Float32

0.0が完全に左、1.0が完全に右、0.5が中央の定位。 AudioControlのサブクラスAudioStereoPanControlで実装されている。

kAudioDevicePropertyStereoPanChannels

UInt32[2]

An array of two UInt32s that indicate which elements of the owning object the signal is being panned between. This property is implemented by an AudioControl object that is a subclass of AudioStereoPanControl.

kAudioDevicePropertyMute

UInt32

1はミュートが有効であることを意味し、エレメントは無音状態になる。AudioControlのサブクラスAudioMuteControlで実装されている。

kAudioDevicePropertySolo

UInt32

1はそのエレメントの音だけが聞こえ、他のエレメントは無音状態であることを示す。AudioControlのサブクラスAudioMuteControlで実装されている。

kAudioDevicePropertyDataSource

UInt32

現在選択中のデータソースのアイテムID。AudioControlのサブクラスAudioDataSourceControlで実装されている。

kAudioDevicePropertyDataSources

UInt32配列

現在利用可能なすべてのデータソースのIDを表す。AudioControlのサブクラスAudioDataSourceControlで実装されている。

kAudioDevicePropertyDataSourceNameForIDCFString

AudioValueTranslation

データソースIDを人間が読める名前に変換する。入力データは変換したいUInt32のアイテムIDで、出力データはCFStringである。返されたCFObject解放の責は呼び出し側が負う。AudioControlのサブクラスAudioDataSourceControlで実装されている。

kAudioDevicePropertyClockSource

UInt32

現在選択中のクロックソースのアイテムID。AudioControlのサブクラスAudioClockControlで実装されている。

kAudioDevicePropertyClockSources

UInt32配列

現在利用可能な全クロックソースの全てのID。AudioControlのサブクラスAudioClockControlで実装されている。

kAudioDevicePropertyClockSourceNameForIDCFString

AudioValueTranslation

クロックソースIDを人間が読める名前に変換する。入力データは変換したいUInt32のアイテムIDで、出力データはCFStringである。返されたCFObject解放の責は呼び出し側が負う。AudioControlのサブクラスAudioClockControlで実装されている。

kAudioDevicePropertyClockSourceKindForID

This property returns a UInt32 that identifies the kind of clock source the item ID refers to using an AudioValueTranslation structure. The input data is the UInt32 containing the item ID and the output data is the UInt32. Values for this property are defined in .

kAudioDevicePropertyPlayThru

UInt32

0はスルー再生が無効、1は有効を表す。AudioControlのサブクラスAudioMuteControlで実装されている。さらにまた、本プロパティを実装するコントロールは、kAudioDevicePropertyScopePlayThroughurを通してのみ利用可能である。

kAudioDevicePropertyPlayThruSolo

UInt32

where a value of 1 means that just that play through element is audible and the other elements are inaudible. The property is implemented by an AudioControl object that is a subclass of AudioSoloControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruVolumeScalar

Float32

音量制御の値を示す。範囲は0.0以上1.0以下である。本プロパティはAudioControlのサブクラスAudioVolumeControlで実装されている。さらにまた、本プロパティを実装するコントロールはkAudioDevicePropertyScopePlayThroughを通してのみ利用可能である。

kAudioDevicePropertyPlayThruVolumeDecibels

Float32

音量制御の値をデシベルで示す。 本プロパティはAudioControlのサブクラスAudioVolumeControlで実装されている。さらにまた、本プロパティを実装するコントロールはkAudioDevicePropertyScopePlayThroughを通してのみ利用可能である。

kAudioDevicePropertyPlayThruVolumeRangeDecibels

AudioValueRange

コントロールが取りうるデシベル値の最小・最大を含む。 本プロパティはAudioControlのサブクラスAudioVolumeControlで実装されている。さらにまた、本プロパティを実装するコントロールはkAudioDevicePropertyScopePlayThroughを通してのみ利用可能である。

kAudioDevicePropertyPlayThruVolumeScalarToDecibels

A Float32 that on input contains a scalar volume value for the and on exit contains the equivalent dB value. This property is implemented by an AudioControl object that is a subclass of AudioVolumeControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruVolumeDecibelsToScalar

A Float32 that on input contains a dB volume value for the and on exit contains the equivalent scalar value. This property is implemented by an AudioControl object that is a subclass of AudioVolumeControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruStereoPan

A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center. This property is implemented by an AudioControl object that is a subclass of AudioStereoPanControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruStereoPanChannels

An array of two UInt32s that indicate which elements of the owning object the signal is being panned between. This property is implemented by an AudioControl object that is a subclass of AudioStereoPanControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruDestination

A UInt32 whose value is the item ID for the currently selected play through data destination. This property is implemented by an AudioControl object that is a subclass of AudioDataDestinationControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruDestinations

An array of UInt32s that are represent all the IDs of all the play through data destinations currently available. This property is implemented by an AudioControl object that is a subclass of AudioDataDestinationControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyPlayThruDestinationNameForIDCFString

This property translates the given play through data destination item ID into a human readable name using an AudioValueTranslation structure. The input data is the UInt32 containing the item ID to translated and the output data is a CFString. The caller is responsible for releasing the returned CFObject. This property is implemented by an AudioControl object that is a subclass of AudioDataDestinationControl. Further, the control that implements this property is only available through kAudioDevicePropertyScopePlayThrough.

kAudioDevicePropertyChannelNominalLineLevel

UInt32

現在選択中のラインレベルのアイテムID。AudioControlのサブクラスAudioLineLevelControlで実装されている。

kAudioDevicePropertyChannelNominalLineLevels

An array of UInt32s that represent all the IDs of all the nominal line levels currently available. This property is implemented by an AudioControl object that is a subclass of AudioLineLevelControl.

kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString

This property translates the given nominal line level item ID into a human readable name using an AudioValueTranslation structure. The input data is the UInt32 containing the item ID to be translated and the output data is a CFString. The caller is responsible for releasing the returned CFObject. This property is implemented by an AudioCOntrol object that is a subclass of AudioLineLevelControl.

kAudioDevicePropertyDriverShouldOwniSub

A UInt32 where a value of 0 means that the AudioDevice should not claim ownership of any attached iSub and a value of 1 means that it should. Note that this property is only available for built-in devices and for USB Audio devices that use the standard class compliant driver. This property is implemented by an AudioControl object that is a subclass of AudioISubOwnerControl.

kAudioDevicePropertySubVolumeScalar

A Float32 that represents the value of the LFE volume control. The range is between 0.0 and 1.0 (inclusive). This property is implemented by an AudioControl object that is a subclass of AudioLFEVolumeControl.

kAudioDevicePropertySubVolumeDecibels

A Float32 that represents the value of the LFE volume control in dB. This property is implemented by an AudioControl object that is a subclass of AudioLFE VolumeControl.

kAudioDevicePropertySubVolumeRangeDecibels

An AudioValueRange that contains the minimum and maximum dB values the control can have. This property is implemented by an AudioControl object that is a subclass of AudioLFEVolumeControl.

kAudioDevicePropertySubVolumeScalarToDecibels

Float32

スカラー音量値を入力すると、等価なデシベル値を出力する。本プロパティはAudioControlのサブクラスAudioLFEVolumeControlで実装される。

kAudioDevicePropertySubVolumeDecibelsToScalar

Float32

デシベル音量値を入力すると、等価なスカラー値を出力する。本プロパティはAudioControlのサブクラスAudioLFEVolumeControlで実装される。

kAudioDevicePropertySubMute

UInt32

where a value of 1 means that mute is enabled making the LFE on that element inaudible. The property is implemented by an AudioControl object that is a subclass of AudioLFEMuteControl.

kAudioStreamPropertyDirection

UInt32

0はAudioStreamが出力ストリーム、1は入力ストリームを表す。

kAudioStreamPropertyTerminalType

UInt32

AudioStreamに付随する機能の一般的な種類を表す。本プロパティ値となり得る幾つかの定数は<IOKit/audio/IOAudioTypes.h>で定義されている。

kAudioStreamPropertyStartingChannel

UInt32

このストリームの1つのエレメントと一致する、親デバイス内の最初のエレメントを特定する。

kAudioStreamPropertyLatency

UInt32

AudioStreamの遅延フレーム数。親AudioDeviceが追加の遅延を持つ可能性があるため、同様に問い合わせるべきである。デバイスとストリームの両方がレイテンシを返した場合、そのストリームの合計レイテンシはデバイス遅延とストリーム遅延の合算となる。

kAudioStreamPropertyVirtualFormat

AudioStreamBasicDescription

AudioStreamの現在の仮想データ形式。 仮想フォーマットは、所有するAudioDeviceがIOトランザクション処理を行うための全てのIOProc内でのデータ形式を指す。

kAudioStreamPropertyAvailableVirtualFormats

AudioStreamRangedDescription配列

AudioStreamが利用可能な仮想データ形式リスト。 仮想フォーマットは、所有するAudioDeviceがIOトランザクションを処理を行うためのハードウェア内でのデータ形式を指す。

kAudioStreamPropertyPhysicalFormat

AudioStreamBasicDescription

AudioStreamの現在の物理データ形式。物理フォーマットは、所有するAudioDeviceがIOトランザクションを処理を行うためのハードウェア内でのデータ形式を指す。

kAudioStreamPropertyAvailablePhysicalFormats

AudioStreamRangedDescription配列

AudioStreamが利用可能な物理データ形式リスト。 物理フォーマットは、所有するAudioDeviceがIOトランザクションを処理を行うためのハードウェア内でのデータ形式を指す。

AudioStreamはAudioObjectのサブクラスで、ただ1つのスコープkAudioObjectPropertyScopeGlobalを持つ。 それらはマスターエレメントと、チャンネル毎にストリーム内で1から番号付けされるエレメントを持つ。 AudioDeviceが所有する複数のAudioStreamオブジェクト間で、AudioControlオブジェクトが共有される点に注意されたい。 その結果として、AudioDeviceによって実装される標準的なAudioControl関連のプロパティセレクタの全ては、AudioStreamによっても実装される。 このようなプロパティには同じ定数が使用される。