spAudio APIリファレンス

出力プラグイン

出力プラグインのための関数です．様々なファイル形式での保存やオーディオデバイスなどへの出力が可能となります．入力プラグインのために使用できる関数も多く含まれています．

spOpenFilePlugin, spOpenFilePluginAuto, spOpenFilePluginArg, spOpenFilePluginArgAuto

目的: プラグインを用いてファイルを開きます．

書式

#include <sp/spOutputPlugin.h>

spPlugin *spOpenFilePlugin(char *plugin_name, char *filename, char *mode,
                           spPluginDeviceType device_type,
                           spWaveInfo *wave_info, spSongInfo *song_info,
                           spPluginOpenCallback call_func, void *call_data,
                           spPluginError *error);
spPlugin *spOpenFilePluginAuto(char *plugin_name, char *filename, char *mode,
                               spPluginDeviceType device_type,
                               spWaveInfo *wave_info, spSongInfo *song_info,
                               spPluginOpenCallback call_func, void *call_data,
                               spPluginError *error);
spPlugin *spOpenFilePluginArg(char *plugin_name, char *filename, char *mode,
                              spPluginDeviceType device_type,
                              spWaveInfo *wave_info, spSongInfo *song_info,
                              int argc, char **argv, spPluginError *error);
spPlugin *spOpenFilePluginArgAuto(char *plugin_name, char *filename, char *mode,
                                  spPluginDeviceType device_type,
                                  spWaveInfo *wave_info, spSongInfo *song_info,
                                  int argc, char **argv, spPluginError *error);

引数

plugin_name: プラグイン名を指定します．例えば，"input_raw"のように指定します． NULLを指定すると，読み込みの場合はファイルの情報から，書き込みの場合はファイル名から自動判定します．
file_name: ファイル名を指定します．
mode: ファイルを開く際のモードを指定します．読み込みモードでファイルを開く場合は"r"を，書き込みモードでファイルを開く場合は"w"を指定します．現在はこの2つのモードのみをサポートしています．
device_type: ファイルを開く場合は，SP_PLUGIN_DEVICE_FILEを指定します．オーディオデバイスを開く場合は，SP_PLUGIN_DEVICE_AUDIOを指定します．
wave_info: spWaveInfo型変数へのポインタを指定します．読み込みモードの場合は，spWaveInfo型変数のメンバーにファイルの情報が返ってきます．例えば，wave_info.samp_rate でサンプリング周波数が， wave_info.samp_bit で量子化ビット数が得られます．書き込みモードの場合は，書き込むファイルにメンバーの値が設定されます．

戻り値: spPlugin型へのポインタが返ります．これを後の処理において，関数の引数として使用することになります．

説明: 関数名の最後にAutoが付いているものは，最初はplugin_nameの引数を無視してファイルを開こうとし，対応するプラグインが見つからなかった場合のみにplugin_nameを用いてファイルを開く，という処理をします．例えば，自動でファイル形式を判定できなかった場合に，Rawファイルとして読み込みたい場合などに利用します．
関数名にArgが入っているものは，プラグインに対するコマンドラインオプションを渡せるようにするものです．いくつかのプラグインはコマンドラインオプションに対応しているため，こちらの関数を使用すると，関係のあるコマンドラインオプションを渡せるようになります．プラグインに関係のないコマンドラインオプションや無関係の文字列は無視されます．

関連項目: spCloseFilePlugin

spCloseFilePlugin

目的: プラグインを用いて開いたファイルを閉じます．

書式

#include <sp/spOutputPlugin.h>

spBool spCloseFilePlugin(spPlugin *plugin);

引数

plugin: spOpenFilePluginで得られたspPlugin型へのポインタを指定します．

戻り値: 正常に終了した場合はSP_TRUEが返り，そうでない場合はSP_FALSEが返ります．

説明: ファイルを閉じるだけでなく，プラグインの解放処理（spPlugin型へのポインタに確保されたメモリの解放など）も行われます．そのため，この関数を呼び出した後は，引数で用いたspPlugin型へのポインタへアクセスしてはいけません．

関連項目: spOpenFilePlugin

spWritePlugin, spWritePluginInByte, spWritePluginDouble

目的: プラグインを用いてファイルにデータを書き込みます．

書式

#include <sp/spOutputPlugin.h>

long _spWritePlugin(spPlugin *plugin, char *data, long length);
#define spWritePlugin(plugin, data, length) _spWritePlugin(plugin, (char *)(data), length)

long spWritePluginInByte(spPlugin *plugin, char *data, long data_size);
long spWritePluginDouble(spPlugin *plugin, double *data, long length);

引数

plugin: spOpenFilePluginで得られたspPlugin型へのポインタを指定します．
data: 書き込むデータです．spWritePluginの場合は書き込むデータの量子化ビット数に応じて型が変わります． 8・16ビットであればshort型，24・32ビットであればlong型，64ビットであればdouble型になります．
length: 書き込むdataのポイント数です（継続時間長をポイント単位にしたものではありません）．例えば，ステレオデータの場合であれば，dataの継続時間長をポイント単位にしたものの2倍の値です．
data_size: 書き込むdataのバイト数です．

戻り値: 書き込んだポイント数・バイト数が返ります．正常に書きこめた場合は引数のlengthもしくはdata_sizeと同じ値になります．

説明: spWritePluginとspWritePluginInByteの違いはデータの長さの与え方が異なるだけです． spWritePluginDoubleの場合は，基本的に-1～1の範囲の値にする必要があります．

関連項目: spOpenFilePlugin, spReadPlugin

xspFindRelatedPluginFile

目的: 関係のあるプラグインの名前を取得します．

書式

#include <sp/spOutputPlugin.h>

char *xspFindRelatedPluginFile(char *plugin_name);

引数

plugin_name: プラグイン名を指定します．例えば，"input_wav"のように指定します．

戻り値: 関連するプラグインの名前が返ります．例えば，"input_wav"を引数として与えた場合は，"output_wav"が返ります．存在しなかった場合にはNULLが返ります．使用しなくなった場合は，xspFreeを用いて解放して下さい．

説明: 入力プラグインと対応する出力プラグインを探す場合などに使用します．

関連項目: spOpenFilePlugin

xspFindSuitablePluginFile, xspFindSuitablePluginFileWithPriority

目的: ファイル名とファイルを開く際のモードから，そのファイルをサポートしている適切なプラグイン名を取得します．

書式

#include <sp/spOutputPlugin.h>

char *xspFindSuitablePluginFile(spPluginDeviceType device_type, char *filename, char *mode);
char *xspFindSuitablePluginFileWithPriority(spPluginDeviceType device_type, char *filename, char *mode, int *current_priority);

引数

device_type: 通常は，SP_PLUGIN_DEVICE_FILEを指定します．
filename: ファイル名を指定します．
mode: ファイルを開く際のモードを指定します．読み込みモードでファイルを開く場合は"r"を，書き込みモードでファイルを開く場合は"w"を指定します．
current_priority: 現在の優先度の値を保持する変数のアドレスを渡します．この優先度からプラグインの検索を始めます．この優先度よりも高い優先度を持つプラグインは無視されます．終了時に，優先度の値は，次の呼び出しのために更新されます．

戻り値: プラグインの名前が返ります．存在しなかった場合にはNULLが返ります．使用しなくなった場合は，xspFreeを用いて解放して下さい．

関連項目: spOpenFilePlugin

Last modified: "2013-06-23 19:21:40 hideki"