目次 - 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ライブラリの使用を検討すること.

関数

MIX_AudioFramesToMS
MIX_AudioMSToFrames
MIX_CreateAudioDecoder
MIX_CreateAudioDecoder_IO
MIX_CreateGroup
MIX_CreateMixer - オーディオデータをメモリバッファに生成するミキサーを生成する
MIX_CreateMixerDevice - オーディオデバイスから音声を再生するミキサーを生成する
MIX_CreateSineWaveAudio
MIX_CreateTrack - ミキサーに新しいトラックを生成する
MIX_DecodeAudio
MIX_DestroyAudio - 指定したオーディオを破棄する
MIX_DestroyAudioDecoder
MIX_DestroyGroup
MIX_DestroyMixer - ミキサーを破棄する
MIX_DestroyTrack - 指定したトラックを破棄する
MIX_FramesToMS
MIX_Generate - オーディオデバイスで動作していない場合のミキサーの出力を生成する
MIX_GetAudioDecoder
MIX_GetAudioDecoderFormat
MIX_GetAudioDecoderProperties
MIX_GetAudioDuration
MIX_GetAudioFormat
MIX_GetAudioProperties - MIX_Audioに関連付けられたプロパティを得る
MIX_GetGroupMixer
MIX_GetGroupProperties
MIX_GetMixerFormat - ミキサーが生成するオーディオの形式を得る
MIX_GetMixerFrequencyRatio
MIX_GetMixerGain
MIX_GetMixerProperties
MIX_GetNumAudioDecoders
MIX_GetTaggedTracks
MIX_GetTrack3DPosition
MIX_GetTrackAudio
MIX_GetTrackAudioStream
MIX_GetTrackFadeFrames
MIX_GetTrackFrequencyRatio
MIX_GetTrackGain
MIX_GetTrackLoops
MIX_GetTrackMixer
MIX_GetTrackPlaybackPosition
MIX_GetTrackProperties
MIX_GetTrackRemaining
MIX_GetTrackTags
MIX_Init - SDL_mixerライブラリを初期化する
MIX_LoadAudio - ファイルから再生するオーディオデータを読み込む
MIX_LoadAudio_IO - SDL_IOStreamから再生するオーディオデータを読み込む
MIX_LoadAudioNoCopy
MIX_LoadAudioWithProperties - プロパティグループを通して再生のためのオーディオを読み込む
MIX_LoadRawAudio
MIX_LoadRawAudio_IO
MIX_LoadRawAudioNoCopy
MIX_LockMixer
MIX_MSToFrames
MIX_PauseAllTracks
MIX_PauseTag
MIX_PauseTrack
MIX_PlayAudio - MIX_Audioを管理せずに先頭から末尾まで再生する
MIX_PlayTag
MIX_PlayTrack - トラックの再生を開始(または再開)する
MIX_Quit - SDL_mixerライブラリを終了する
MIX_ResumeAllTracks
MIX_ResumeTag
MIX_ResumeTrack
MIX_SetGroupPostMixCallback
MIX_SetMixerFrequencyRatio
MIX_SetMixerGain
MIX_SetPostMixCallback
MIX_SetTagGain
MIX_SetTrack3DPosition
MIX_SetTrackAudio - MIX_Trackへの入力としてMIX_Audioを設定する
MIX_SetTrackAudioStream - MIX_Trackへの入力としてSDL_AudioStreamを設定する
MIX_SetTrackCookedCallback
MIX_SetTrackFrequencyRatio
MIX_SetTrackGain
MIX_SetTrackGroup
MIX_SetTrackIOStream - MIX_Trackへの入力としてSDL_IOStreamを設定する
MIX_SetTrackLoops
MIX_SetTrackOutputChannelMap
MIX_SetTrackPlaybackPosition
MIX_SetTrackRawCallback
MIX_SetTrackRawIOStream
MIX_SetTrackStereo
MIX_SetTrackStoppedCallback
MIX_StopAllTracks
MIX_StopTag
MIX_StopTrack
MIX_TagTrack
MIX_TrackFramesToMS
MIX_TrackMSToFrames
MIX_TrackPaused
MIX_TrackPlaying
MIX_UnlockMixer
MIX_UntagTrack
MIX_Version

型

MIX_Audio - オーディオデータを表す不透明オブジェクトの型
MIX_AudioDecoder
MIX_Group
MIX_GroupMixCallback
MIX_Mixer - ミキサーを表す不透明オブジェクトの型
MIX_PostMixCallback
MIX_Track - ミックスされる音源を表す不透明オブジェクトの型
MIX_TrackMixCallback
MIX_TrackStoppedCallback

構造体

MIX_Point3D
MIX_StereoGains

マクロ

SDL_MIXER_MAJOR_VERSION
SDL_MIXER_MICRO_VERSION
SDL_MIXER_MINOR_VERSION
SDL_MIXER_VERSION
SDL_MIXER_VERSION_ATLEAST

SDL Wikiへのリンク

SDL3_mixer/CategorySDLMixer