目次 - SDL_mixer 3.0

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
  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
  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

型

  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
  2. MIX_StereoGains

マクロ

  1. SDL_MIXER_MAJOR_VERSION
  2. SDL_MIXER_MICRO_VERSION
  3. SDL_MIXER_MINOR_VERSION
  4. SDL_MIXER_VERSION
  5. SDL_MIXER_VERSION_ATLEAST

SDL Wikiへのリンク

SDL3_mixer/CategorySDLMixer