SDL_mixer 3.0 API (アルファベット順)

概要

SDL_mixerは面倒なオーディオ処理を簡単に行えるライブラリである.

これはオーディオファイルのデコード, 複数音源のミキシング, 基本的な立体音響, 様々なエフェクトを提供する.

リアルタイムで複数のオーディオデバイスにミックスすることや, ミックスしたオーディオデータを別の使用のためにメモリバッファに生成することができる. これらを同時に行うこともできる.

このライブラリを使用するには, まずMIX_Init()を呼ぶ. それからMIX_CreateMixerDevice()でミキサーを生成する. (またはMIX_CreateMixer()でメモリに書き込むレンダーを生成する)

ミキサーを生成した後は, MIX_LoadAudio(), MIX_LoadAudio_IO()またはMIX_LoadAudioWithProperties()でオーディオデータを読み込む. 一度読み込んだデータは何度でも再生できる.

オーディオデータの読み込みでは, SDL_mixerはID3やAPEタグのようないくつかのメタデータタグ形式を解析でき, この情報はMIX_GetAudioProperties()関数を経由して表に出すことができる.

オーディオデータの再生のためには, MIX_CreateTrack()でトラックを生成する. 同時に再生するオーディオデータには, それぞれトラックが必要である. トラックはミキサーボード上の一つ一つのスライダーと考えればよい. 何百ものオーディオファイルを読み込もうとしたことがあるかもしれないが, 再生の準備が整ったとき読み込んだファイルを割り当てるトラックはわずかで, これらのトラックは別のオーディオで再利用することになる. トラックはMIX_Audio(複数回再生される静的データ)またはSDL_AudioStream(アプリケーションが必要に応じて提供するストリーミングPCMオーディオ)から入力を受ける. その他の選択肢はSDL_IOStreamからの供給で読み込みと即座のデコードを行うもので, これは一度だけ使用するBGMなどで効果的かもしれない.

入力をMIX_SetTrackAudio(), MIX_SetTrackAudioStream(), またはMIX_SetTrackIOStream()でMIX_Trackに割り当てる.

トラックが入力を得た後は, MIX_PlayTrack()で再生を開始する. この関数にはミキシングの機能: ループ, フェードなどを指示する様々なオプションがある.

トラックには"music", "ingame", "ui"のような任意の文字列をタグ付けできる. これらのタグは開始, 停止, 一時停止するトラックの選択を一度に行うために使用できる.

ミキシングパイプラインの重要な部分はコールバックのため, アプリケーションは適切な場所でフックしてミキサーへ向かうオーディオデータの調査や編集を行うことができる: オーディオファイルからデコードされた無編集のPCMデータの"raw"コールバック, 同じデータに全ての変換(フェード, ポジショニングなど)が行われた後の"cooked"コールバック, トラックがミキシングを完了したときの"stopped"コールバック, 最終的なミックスされた音声が再生のためのオーディオハードウェアに送られるときの"postmix"コールバックがある. さらに, MIX_Groupオブジェクトで再生中のトラックの一部をミックスしたり, 別のトラックとミックスする前のデータにアクセスしたりできる. これらは全てオプションだが, 強力なアクセスとミキシング処理の制御を可能にする.

SDL_mixerはオーディオファイルのデコードを実際のミックス以外で使用することもできる. これはMIX_AudioDecoderで行える. アプリケーションのオーディオエンジンとして使用する場合, SDL_mixerはデコードを透過的に扱うため このインターフェースは通常の使用法では必要ないかもしれないが, これは様々なファイル形式にアクセスするために別のオーディオライブラリを使用するとき有用になりうる.

このライブラリは音声のミキシング以外にもいくつかの機能がある: マスターゲインとは別にそれぞれのトラックにゲインを持たせボリュームを調整することができる. また, トラックやミックス後の最終的な出力に「周波数比」を設定して, 速度の上げ下げやピッチの調整を行うことができ, チャンネルマッピングもトラックごとに適用可能で, 指定のオーディオチャネルをどのスピーカーから出力するかを変えることができる.

SDL_mixerのほぼ全てのタイミングはサンプルフレーム単位である. 例えば, Sint16形式のステレオPCMオーディオデータは1サンプルフレーム当たり4バイト(1サンプル当たり2バイト×2チャネル)を消費する. これによりSDL_mixerでは全ての処理をサンプル単位で行うことができ, 実時間とは無関係に動作させることが, 必要ならば実時間よりも早くデータを与えることもできる. 問題なのは, 異なるサンプリングレートのデータは同じ時間でもサンプルフレームの長さが異なることである. これを扱うために変換ルーチンのMIX_TrackMSToFrames(), MIX_TrackFramesToMS()などが提供されている. これらの関数は一度に複数のトラックをミリ秒単位を扱うため, 変換は内部で行う. 詳細な仕様はドキュメントを確認すること.

SDL_mixerは, シンプルな3D位置APIのMIX_SetTrack3DPosition()とMIX_SetTrackStereo()で基本的な位置オーディオも提供する. 前者はシンプルな距離による減衰と空間化処理を行い――ステレオ環境では音が左右に動くように聞こえる――, サラウンドの設定や個々のトラックの移動を行える. 後者のMIX_SetTrackStereo()は音声を前面左から全面右のスピーカに強制し, 必要ならばアプリケーションで左右にパンさせる. どちらのエフェクトも状況に応じて役立ちうる. SDL_mixerには完全な3Dオーディオエンジンにはならないが, 多くの目的で十分な機能がある. より強力な3Dオーディオが必要ならば, OpenALのような正式な3Dライブラリの使用を検討すること.

関数

1. MIX_AudioFramesToMS - MIX_Audioの形式のサンプルフレーム数をミリ秒に変換する
2. MIX_AudioMSToFrames - MIX_Audioの形式のミリ秒をサンプルフレーム数に変換する
3. MIX_CreateAudioDecoder - ファイルからMIX_AudioDecoderを生成する
4. MIX_CreateAudioDecoder_IO - SDL_IOStreamからMIX_AudioDecoderを生成する
5. MIX_CreateGroup - ミキシンググループを生成する
6. MIX_CreateMixer - オーディオデータをメモリバッファに生成するミキサーを生成する
7. MIX_CreateMixerDevice - オーディオデバイスから音声を再生するミキサーを生成する
8. MIX_CreateSineWaveAudio - サイン波を生成するMIX_Audioを生成する
9. MIX_CreateTrack - ミキサーに新しいトラックを生成する
10. MIX_DecodeAudio - MIX_AudioDecoderからオーディオデータを追加でデコードする
11. MIX_DestroyAudio - 指定したオーディオを破棄する
12. MIX_DestroyAudioDecoder - 指定したオーディオデコーダを破棄する
13. MIX_DestroyGroup - ミキシンググループを破棄する
14. MIX_DestroyMixer - ミキサーを破棄する
15. MIX_DestroyTrack - 指定したトラックを破棄する
16. MIX_FramesToMS - サンプルフレーム数を指定のサンプルレートでミリ秒に変換する
17. MIX_Generate - オーディオデバイスで動作していない場合のミキサーの出力を生成する
18. MIX_GetAudioDecoder - オーディオデコーダの名前を得る
19. MIX_GetAudioDecoderFormat - MIX_AudioDecoderのオーディオ形式の初期値を得る
20. MIX_GetAudioDecoderProperties - MIX_AudioDecoderに関連付けられたプロパティを得る
21. MIX_GetAudioDuration - MIX_Audioの再生の長さをサンプルフレーム数で得る
22. MIX_GetAudioFormat - MIX_Audioのオーディオ形式の初期値を得る
23. MIX_GetAudioProperties - MIX_Audioに関連付けられたプロパティを得る
24. MIX_GetGroupMixer - MIX_Groupを所有しているMIX_Mixerを得る
25. MIX_GetGroupProperties - グループに関連付けられたプロパティを得る
26. MIX_GetMixerFormat - ミキサーが生成するオーディオの形式を得る
27. MIX_GetMixerFrequencyRatio - ミキサーのマスター周波数倍率を得る
28. MIX_GetMixerGain - ミキサーのマスターゲインを得る
29. MIX_GetMixerProperties - ミキサーに関連付けられたプロパティを得る
30. MIX_GetNumAudioDecoders - 利用可能なオーディオデコーダの数を得る
31. MIX_GetTaggedTracks - 指定したタグのトラックを全て得る
32. MIX_GetTrack3DPosition - トラックの現在の3D空間内の位置を得る
33. MIX_GetTrackAudio - トラックに割り付けられたMIX_Audioを得る
34. MIX_GetTrackAudioStream - トラックに割り付けられたSDL_AudioStreamを得る
35. MIX_GetTrackFadeFrames - トラックがフェード中かを得る
36. MIX_GetTrackFrequencyRatio - トラックの周波数倍率を得る
37. MIX_GetTrackGain - トラックのゲインを得る
38. MIX_GetTrackLoops - トラックの残りループ回数を得る
39. MIX_GetTrackMixer - MIX_Trackを持つMIX_Mixerを得る
40. MIX_GetTrackPlaybackPosition - 再生中のトラックの現在の入力位置を得る
41. MIX_GetTrackProperties - グループに関連付けられたプロパティを得る
42. MIX_GetTrackRemaining - トラックのミックスされる残りサンプルフレーム数を得る
43. MIX_GetTrackTags - トラックのタグを得る
44. MIX_Init - SDL_mixerライブラリを初期化する
45. MIX_LoadAudio - ファイルから再生するオーディオデータを読み込む
46. MIX_LoadAudio_IO - SDL_IOStreamから再生するオーディオデータを読み込む
47. MIX_LoadAudioNoCopy - メモリバッファから再生するオーディオデータをコピーせずに読み込む
48. MIX_LoadAudioWithProperties - プロパティグループを通して再生のためのオーディオを読み込む
49. MIX_LoadRawAudio - メモリバッファから無圧縮PCMデータを読み込む
50. MIX_LoadRawAudio_IO - SDL_IOStreamから無圧縮PCMデータを読み込む
51. MIX_LoadRawAudioNoCopy - メモリバッファから再生する無圧縮PCMデータをコピーせずに読み込む
52. MIX_LockMixer - ミキサーの内部のミューテックスをロックする
53. MIX_MSToFrames - ミリ秒を指定のサンプルレートでサンプルフレーム数に変換する
54. MIX_PauseAllTracks - 再生中の全てのトラックを一時停止する
55. MIX_PauseTag - 特定のタグの全てのトラックを一時停止する
56. MIX_PauseTrack - 再生中の全てのトラックを一時停止する
57. MIX_PlayAudio - MIX_Audioを管理せずに先頭から末尾まで再生する
58. MIX_PlayTag - 特定のタグの全てのトラックの再生を開始(または再開)する
59. MIX_PlayTrack - トラックの再生を開始(または再開)する
60. MIX_Quit - SDL_mixerライブラリを終了する
61. MIX_ResumeAllTracks - 全てのトラックの一時停止を解除する
62. MIX_ResumeTag - 特定のタグの全てのトラックの一時停止を解除する
63. MIX_ResumeTrack - 再生中の全てのトラックを一時停止する
64. MIX_SetGroupPostMixCallback - グループのミキシングが完了したとき呼ばれるコールバックを設定する
65. MIX_SetMixerFrequencyRatio - ミキサーのマスター周波数倍率を設定する
66. MIX_SetMixerGain - ミキサーのマスターゲインを設定する
67. MIX_SetPostMixCallback - 全てのミキシングが完了したとき呼ばれるコールバックを設定する
68. MIX_SetTagGain - 特定のタグのトラックのゲインを設定する
69. MIX_SetTrack3DPosition - トラックの現在の3D空間内の位置を得る
70. MIX_SetTrackAudio - MIX_Trackへの入力としてMIX_Audioを設定する
71. MIX_SetTrackAudioStream - MIX_Trackへの入力としてSDL_AudioStreamを設定する
72. MIX_SetTrackCookedCallback - ミキサーがトラックのオーディオを変換したとき呼ばれるコールバックを設定する
73. MIX_SetTrackFrequencyRatio - トラックの周波数倍率を設定する
74. MIX_SetTrackGain - トラックのゲインを設定する
75. MIX_SetTrackGroup - ミキシンググループにトラックを割り付ける
76. MIX_SetTrackIOStream - MIX_Trackへの入力としてSDL_IOStreamを設定する
77. MIX_SetTrackLoops - 再生中のトラックの残りループ回数を設定する
78. MIX_SetTrackOutputChannelMap - トラックの出力チャネルマップを設定する
79. MIX_SetTrackPlaybackPosition - 再生中のトラックの現在の入力位置を設定する
80. MIX_SetTrackRawCallback - トラックがオーディオのデコードを開始するとき呼ばれるコールバックを設定する
81. MIX_SetTrackRawIOStream - MIX_Trackへの無圧縮PCMデータの入力としてSDL_IOStreamを設定する
82. MIX_SetTrackStereo - トラックを強制的に任意の左右パン設定でステレオ化する
83. MIX_SetTrackStoppedCallback - トラックが停止したとき呼ばれるコールバックを設定する
84. MIX_StopAllTracks - 再生中の全てのトラックを停止する. 徐々にフェードアウトさせることもできる
85. MIX_StopTag
86. MIX_StopTrack
87. MIX_TagTrack - トラックに任意のタグを関連付ける
88. MIX_TrackFramesToMS - トラックの現在の形式のサンプルフレーム数をミリ秒に変換する
89. MIX_TrackMSToFrames - トラックの現在の形式のミリ秒をサンプルフレーム数に変換する
90. MIX_TrackPaused
91. MIX_TrackPlaying
92. MIX_UnlockMixer
93. MIX_UntagTrack - トラックの任意のタグを取り除く
94. MIX_Version - 動的リンクされたSDL_mixerライブラリのバージョンを得る

型

1. MIX_Audio - オーディオデータを表す不透明オブジェクトの型
2. MIX_AudioDecoder - オーディオデコーダを表す不透明オブジェクトの型
3. MIX_Group - トラックのグループを表す不透明オブジェクトの型
4. MIX_GroupMixCallback - MIX_Groupのミキシングが完了したとき呼ばれるコールバックの型
5. MIX_Mixer - ミキサーを表す不透明オブジェクトの型
6. MIX_PostMixCallback - 全てのミキシングが完了したとき呼ばれるコールバックの型
7. MIX_Track - ミックスされる音源を表す不透明オブジェクトの型
8. MIX_TrackMixCallback - トラックの様々な段階でのミキシングで呼ばれるコールバックを設定する
9. MIX_TrackStoppedCallback - トラックが停止したとき呼ばれるコールバックの型

構造体

1. MIX_Point3D - MIX_SetTrack3DPositionの3D座標の構造体
2. MIX_StereoGains - MIX_SetTrackStereo()で使用するトラックのチャネルごとのゲインを設定する構造体

マクロ

1. SDL_MIXER_MAJOR_VERSION - SDL_mixerヘッダのメジャーバージョンのマクロ
2. SDL_MIXER_MICRO_VERSION - SDL_mixerヘッダのマイクロ(またはパッチレベル)バージョンのマクロ
3. SDL_MIXER_MINOR_VERSION - SDL_mixerヘッダのマイナーバージョンのマクロ
4. SDL_MIXER_VERSION - SDL_mixerヘッダのバージョンマクロ
5. SDL_MIXER_VERSION_ATLEAST - 少なくともX.Y.ZのバージョンのSDL_mixerでコンパイルされたとき真と評価するマクロ

SDL Wikiへのリンク