
echod-ma サウンド再生ライブラリ

APIリファレンス

Ver0.8.1 by ze-na

----------------------------------------
■基本用語
----------------------------------------
エンジン：
サウンドライブラリ本体です。

----------
デバイス：
音源の出力先です。
出力フォーマットによりデータサイズや音質に影響します。

----------
デコーダ：
音源をデバイスで再生可能な形式に変換する機能です。マスターデコーダとも呼ばれます。
音源ファイルやファイルバッファ単位で管理され、内部ID（仮想デコーダID）によって識別されます。
WAV形式はフォーマット変換のみですが、MP3/OGG/FLACはデータ変換を伴うため、CPU負荷が高くなります。
音源ファイル指定の場合にはストリーミング再生にも対応しています。
ec_load系関数により生成されます。

----------
マスターデコーダ：
シングルまたはマルチ再生機能において、音源バッファを保持する基幹デコーダです。 
初回のインスタンス生成時に作成され、以降の複製デコーダはこのマスターデコーダを参照します。 インスタンスの自動解放や手動解放において、マスターデコーダの初期インスタンスは解放対象外となります。

----------
仮想デコーダ：
ライブラリ内部でデコーダとして管理されるものを「仮想デコーダ」と呼び、仮想デコーダIDによって識別されます。
主な種類は以下の通りです：
・通常の音源ファイル、ファイルバッファにて生成するマスターデコーダ
・マルチ再生機能により、音源バッファを保持するマスターデコーダ
・マルチ再生機能により、自動生成されるバッファ非保持の複製デコーダ
・波形ジェネレータによって自動生成される生成デコーダ
・ノイズジェネレータによって自動生成される生成デコーダ

----------
再生インスタンス：
音源を再生する単位です。仮想デコーダと対になっており
内部No（インスタンスNo）で管理されます。マルチ機能のデコーダIDに複数のインスタンスがある場合の個別制御が必要な際に使います。
ec_play、ec_mkinsにて生成することが出来ます。

----------
マルチ再生（多重再生）：
マルチ再生は、1つの音源を複数のインスタンスで同時に再生できる機能です。
爆発音や連続射撃音など、同じ音を短時間に繰り返す場面で活躍します。
通常の再生では、1インスタンスにつき1再生となりますが、マルチ再生を有効にすることで、再生要求ごとに複製されたデコーダ＋インスタンスが自動生成され、自然な多重再生が可能になります。
本ライブラリでは、理論上最大1024インスタンスまでの同時再生に対応しています。
ただし、音源の長さや再生頻度、同時発音数によっては、CPU負荷や再生タイミングの調整が必要になる場合があります。
安定した動作のために、インスタンスの再利用や再生数の制限など、用途に応じた設計が推奨されます。
マルチ再生はメモリサウンド専用の機能であり、ストリーミング再生には対応していません。
インスタンスごとの音量制御やダッキング処理とも組み合わせることで、臨場感のある音響演出が可能です。

----------
複製サウンド：
他社ライブラリで「Duplex機能」として提供される、1音源を複数IDで管理する仕組みに相当します。
本ライブラリでは以下の方法で複製サウンドを実現できます（※メモリサウンドのみ。ストリーミング再生には非対応）：
・音源ファイルを開発者がメモリ管理し複数IDにロードする（ec_loadm）
・マルチ機能によるバッファの自動複製／再利用／自動解放（ec_play、ec_mkins）
・マルチ機能によるバッファの手動複製（ec_play、ec_mkins）

----------
出力フォーマット：
音源ファイルには様々なサンプリング形式がありますが、デバイスで再生する際には、出力フォーマットの統一が行われます。ec_cfg_deviceにて設定することが出来ます。
本ライブラリでは以下の3つの項目を設定できます：

1. サンプルレート（Sample Rate）：
音源の時間軸上の解像度であり、1秒間に何回音を記録するかを示します（Hz単位）。
値が低いと音が粗くなりますがデータ量は少なく、値が高いほど音質は向上しますがデータ量が増加します。
一般的には CD規格の 44100Hzや、映像・ゲーム用途の 48000Hzが推奨されます。
長時間の音声や負荷軽減が必要な場合は、低めの設定も検討されます。

2. チャンネル数（Channels）：
音の空間的な分割数を示します。1チャンネルはモノラル、2チャンネルはステレオ（左右）です。チャンネル数が増えるとデータ量も比例して増加します。
本ライブラリでは最大2チャンネルまで対応しており、サラウンド音源はステレオまでに削減されます。
モノラル音源を2チャンネルに変換した場合は、左右に同じデータが複製されます。

3. サンプルフォーマット（Sample Format）：
音の振幅を表す1サンプルあたりの解像度（ビット数）です。ビット数が多いほど音の表現力や重ね合わせ時の再現性が高くなります。
逆に、ビット数が少ないとデータ量は減りますが、音の階調が粗くなり、丸め誤差が生じやすくなります。
一般的には 8〜32ビットが使用され、音源形式によってデータ量は最大4倍まで変化します。

----------
音量：
音量は 0〜100％ を整数値（100倍）で管理します。例：10000 = 100％
本ライブラリでは、音量は以下の4つの要素で構成されます：

マスター音量：デバイス出力全体に適用される音量です。
グループ音量：グループ設定されたインスタンスにのみ適用される音量です。
インスタンス音量：各再生インスタンスごとの個別音量です。
オフセット音量：音源ファイルの音量ばらつきを補正するための調整値です。

最終的な出力音量は、以下の乗算式で決定されます：
マスター音量 × グループ音量 ×（インスタンス音量 ＋ オフセット音量）
※いずれかの値が 0 の場合、出力は無音になります。

----------
音量補正（オフセット音量）：
音源ファイルごとの音量に補正をかけるための整数値です。
素材の音量が未調整の場合や、再生時の基準音量を揃えたい場合に使用します。
単位は音量と同じく、0〜100％を100倍した値で管理されますが、補正値としては -150％〜+150％（-15000〜+15000） の範囲で設定可能です。
負の値を指定すると音量を減衰させ、正の値で増音できます。
この補正値はインスタンス音量に加算され、最終的な出力音量は以下のように決定されます：
マスター音量 × グループ音量 ×（インスタンス音量 ＋ オフセット音量）
※いずれかの値が 0 の場合、出力は無音になります。
マスター音量とグループ音量は音源ファイルに属さないため、オフセット補正の対象外です。

----------
パン（パンニング、定位）：
ステレオバランスを整数値で設定します。左右値：-1.0～1.0の値を整数化し10000倍したものになります。
-10000 = 左、0 = 中央、10000 = 右
実際の出力は「グループパン + インスタンスパン」で合成されます。（加算合成）

----------
ピッチ：
再生速度を整数値で設定します。基準値1.0を10000倍した値で管理され、通常速度は10000です。
値を上げると速く（音程が高く）、下げると遅く（音程が低く）なります。
音楽のテンポ調整やボイスチェンジなどに利用できます。
ピッチ処理は CPU 負荷が高いため、未使用時はオフ設定で最適化が可能です。
※ストリーミング再生との併用は、デコード処理とピッチ処理が重なるため非推奨です（詳細は「ストリーミング再生」を参照）。

----------
ダッキング（音量抑制処理）：
ダッキングは、特定のサウンドを聞き取りやすくするために、他のサウンドの音量を一時的に低下させる処理です。 主に効果音やボイスを再生する際に、BGMなどの背景音を一時的に抑える用途で使用されます。
低下値は現在の音量に対する割合（0〜100%）で指定され、100%で完全に無音、0%で音量変化なしとなります。
一時的にBGM音量を下げるなど、効果音やボイスを聞きやすくしたりするのに利用されます。

----------
サウンドグループ：
サウンドグループは、複数の再生インスタンスをまとめて制御するための機能です。
グループは内部的に番号（No 0から採番）で管理され、インスタンスは任意のグループに所属させることができます。
基本的にはグループで音量調整する機能、グループ停止によって出力を一時的に遮断し、グループ開始によって再開する機能となります。

----------
波形出力：
波形タイプ・周波数・振幅などの設定により、波形を生成して発音します。
音源ファイルを使用せず、トーン音やビープ音、簡易的な効果音などを再生する際に利用できます。
音源チップを参考にしたChiptuneライクな波形やMML構文による連続再生ができます。

----------
ストリーミング再生：
音源ファイルを分割して逐次読み込みながら再生する方式です。
mp3/ogg/flacなどの圧縮形式では、読み込みごとにデコード処理が発生します。
メモリに全体を展開せずに再生できるため、長時間の音楽や大容量ファイルに適しています。
ec_loadによるファイル指定で有効となり、ec_loadmによるメモリ指定では非対応です。
ピッチ処理などのリアルタイム変換を併用すると、デコード処理と再生処理が重なりCPU負荷が高くなるため、併用は非推奨です（音途切れ（アンダーラン）が発生する可能性があります）。
ストリーミング再生を有効にするには、ec_def_load のストリーミング設定を使用してください。

----------------------------------------
■初期化・終了
----------------------------------------
ec_init
オーディオエンジンとデバイスを初期化を行います。

stat：0未満=エラー

----------
ec_cfg_device p1,p2,p3
デバイスの出力フォーマット設定を行います。
初期値（48000Hz、2ch、f32）を推奨。ec_initで自動設定されるため、通常は呼び出し不要です。

p1：サンプルレート（周波数、8000から384000）

一般的： 48000(映像制作、ゲーム開発)/44100(CD規格)
中品質： 32000/24000/22050（中程度の品質）
低品質： 16000/11025/8000（低品質、データ圧縮など）
最大限： 88200/96000/176400/192000（高品質、聴力以上）
最大限： 352800/384000（最高品質、聴力以上）

p2：チャンネル数（1でモノラル、2でステレオ）
p3：サンプルフォーマット（1=u8/2=s16/3=s24/4=s32/5=f32）

1  EC_FORMAT_U8   8ビット符号なし整数
2  EC_FORMAT_S16  16ビット符号付き整数
3  EC_FORMAT_S24  24ビット符号付き整数
4  EC_FORMAT_S32  32ビット符号付き整数
5  EC_FORMAT_F32  32ビット浮動小数点

stat：0未満=エラー

----------
ec_cfg_init p1,p2,p3
サウンド再生ライブラリの初期設定を行います。
ec_loadの実行数が上限を超えた場合や、マルチ再生によるインスタンス生成時に自動的に上限が拡張されます。

p1：デコーダの上限値（ID=4～512）
p2：インスタンスの上限値（No=8～1024）
p3：文字列の文字コードにUTF-8を使う（0=SHIFT-JIS、1=UTF-8）

----------
ec_shutdown
サウンド再生機能の終了処理を行ないます。

----------------------------------------
■設定・ロード既定値
----------------------------------------
ec_def_vol p1
ec_load系関数で使用される音量のデフォルト値を設定します。

p1：音量（0〜10000、10000 = 100％）

----------
ec_def_pan p1
ec_load系で反映されるパン(ステレオバランス)のデフォルト値を設定します。

p1：パン（左右の定位：-10000から10000、0=中央値）

----------
ec_def_pitch p1
ec_load系で反映される再生時のピッチ値を10000倍の整数値にて設定します。
ピッチ機能が無効の場合、再生時に変化しません。

p1：ピッチ（2500～20000、10000＝標準、0=無効、1=有効）

----------
ec_def_frame p1,p2,p3
ec_load系で反映される再生時の始点終点フレーム値を設定します。

p1：開始ディレイフレーム値(-1=フレーム無指定)
p2：始点フレーム値(-1=フレーム無指定)
p3：終点フレーム値(-1=終端まで再生)

----------
ec_def_fadein p1
ec_load系で反映される開始時のフェードイン時間値を設定します。

p1：時間値(msec、-1=取り消し)

----------
ec_def_group p1
ec_load系にて設定されるサウンドグループNoの既定値を設定します。

p1：サウンドグループNo（-1=未使用、0～設定最大値）

----------
ec_def_load p1,p2,p3,p4,p5
ec_load系にて設定される既定パラメータを設定します。

p1：グループNo（-1=未使用、1以上で有効）
p2：自動解放しない（0=解放する、1=解放しない、マルチ再生のみ）
p3：ピッチ設定（0=無効、1=有効）
p4：3D空間化（0=無効、1=絶対位置、2=相対位置）
p5：ストリーミング再生（0=無効、1=有効、シングルのみ）

----------------------------------------
■音源ロード処理
----------------------------------------
ec_load "ファイル名",p1,p2,p3
サウンドの読み込みとデコーダの生成を行います（ファイル指定）。
この段階ではデコーダのみが生成され、インスタンスの制御はできません。
必要に応じて ec_play や ec_mkins によってインスタンスを生成してください。
ファイルを分割して読み込みながらのストリーミング再生が可能です。
グループ設定、マルチ再生の自動解放、ピッチ、3D空間化、ストリーミング再生などの挙動を変更したい場合は、ec_def_load などの既定値設定関数を使用してください。

"ファイル名"：読み込みを行なう音源ファイル名
p1：マルチ再生上限値(0=無効、1=有効（既定上限=8）、2～32=有効/上限値)
p2：ループ再生(0=通常、1=リピート)
p3：音量補正％(0から10000、簡易レベル均一化)

stat：デコーダID（0以上）、エラー（0未満）

----------
ec_loadm p1,p2,p3,p4,p5
サウンドの読み込みとデコーダの生成を行います（バッファ指定）。
ec_load が音源ファイルを直接読み込むのに対し、ec_loadm はファイルバッファを直接読み込みます。
1つの音源バッファから複数のデコーダを生成する場合にも利用できます。
メモリサウンドではストリーミング再生は行えません。

p1：音源ファイルのバッファポインタ
p2：音源ファイルのバッファサイズ
p1：マルチ再生上限値(0=無効、1=有効（既定上限=8）、2～32=有効/上限値)
p4：ループ再生(0=通常、1=リピート)
p5：音量補正％(0から10000、簡易レベル均一化)

stat：デコーダID（0以上）、エラー（0未満）

----------
ec_mkins p1
インスタンスの生成のみを行います。
マスターデコーダは初回のみ生成され、ec_playとは異なり再生は行いません。
マルチ再生が有効な場合、呼び出すたびにインスタンスが自動追加されます（多重再生）。
自動解放が有効な場合は、解放や再利用により追加数が抑制されます。

p1：デコーダID｜インスタンスNo
stat：インスタンスNo、0未満 = エラー

----------
ec_udins p1
指定インスタンスを解放します。マルチ再生にて生成したインスタンスを手動で解放するときに利用されます。
ただしマスターデコーダに属する初期インスタンスは解放されません。

p1：デコーダID｜インスタンスNo
stat：0未満 = エラー

----------
ec_unload p1
サウンドのデコーダIDの情報を破棄します。

p1：デコーダID
stat：0未満 = エラー

----------
ec_unload_all
サウンド再生を全停止し、全デコーダ設定をリセットします。

stat：0未満 = エラー

----------------------------------------
■再生・停止
----------------------------------------
ec_play p1
インスタンス生成およびサウンドの再生を同時に行います。マスターデコーダは初回のみインスタンス生成されます。
マルチ再生が有効の場合、呼び出すたびにインスタンスが自動追加され（多重再生）、自動解放が有効な場合は再利用や解放により追加数が抑制されます。
ec_mkinsとec_startにてec_playの生成と再生を個別に行うことが出来ます。
グループ機能を利用している場合、再生中のままグループ停止した場合には状態は再生中のまま更新されません。

p1：デコーダID｜インスタンスNo
stat：インスタンスNo、0未満 = エラー

----------
ec_start p1
既存インスタンスのサウンド再生を行います。
ec_playと異なり、新たなインスタンスの生成は行いません。
マルチ再生が有効な場合でも、インスタンスを追加せずに再生したい場合はec_startを使用してください。
グループ機能を利用している場合、再生中のままグループ停止した場合には状態は再生中のまま更新されません。

p1：デコーダID｜インスタンスNo
stat：インスタンスNo、0未満 = エラー

----------
ec_loop p1,p2
サウンドのループ再生の再設定を行います。

p1：デコーダID｜インスタンスNo
p2：ループ再生(1=ループ再生、0=通常再生)
stat：0未満 = エラー

----------
ec_loop_frame p1,p2,p3
ループ再生フレーム範囲を設定します。停止中に使用します。

p1：デコーダID｜インスタンスNo
p2：開始フレーム値
p3：終了フレーム値
stat：0未満 = エラー

----------
ec_seek_frame p1,p2
サウンドの開始フレーム値を設定します。

p1：デコーダID｜インスタンスNo
p2：開始フレーム値
stat：0未満 = エラー

----------
ec_pitch p1,p2
ピッチを設定します（ピッチ機能が有効な場合のみ反映）。
値を下げると再生速度が遅くなり音程が低く、上げると速くなり音程が高くなります。

p1：デコーダID｜インスタンスNo
p2：ピッチ値（10000＝標準、2500から-20000）
stat：0未満 = エラー

----------
ec_stop p1,p2
再生を停止します。

p1：デコーダID｜インスタンスNo
p2：一時停止（1=一時停止する、0=初めに戻す）
stat：0未満 = エラー

----------
ec_stop_all p1
すべてのインスタンスに対して停止処理を行います。

p1：一時停止（1=一時停止する、0=初めに戻す）
stat：0未満 = エラー

----------------------------------------
■音量・パン・フェード
----------------------------------------
ec_vol_master p1
サウンドのマスター音量を設定します。

p1：音量（％値＝0から10000）
stat：0未満 = エラー

----------
ec_mute p1
マスター音量値を変えずに消音（ミュート）を行います。

p1：ミュート（1=消音、0=再開）
stat：0未満 = エラー

----------
ec_vol p1,p2
サウンドの音量を設定します。

p1：デコーダID｜インスタンスNo
p2：音量（％値＝0から10000）
stat：0未満 = エラー

----------
ec_pan p1,p2
サウンドのパン(ステレオバランス)を設定します。
-10000で左側100％となり、10000で右側100％になります。

p1：デコーダID｜インスタンスNo
p2：パンニング（-10000から10000）
stat：0未満 = エラー

----------
ec_duck p1,p2,p3
一時的に音量を下げるダッキング処理を行います。
効果音やボイスを強調する目的で、BGMなどの音量を減衰させる際に使用します。

p1：デコーダID｜インスタンスNo
p2：音量低下％（1～100％、0=音量を戻す、-1=即時リセット）
p3：経過時間（msec）
stat：0未満 = エラー

----------
ec_fadein p1,p2
サウンドの音量増加（フェードイン）を行います。
設定時間で消音から現在の設定値まで音量を変化させます。

p1：デコーダID｜インスタンスNo
p2：経過時間（msec）
stat：0未満 = エラー

----------
ec_fadeout p1,p2
再生中サウンドの音量減少（フェードアウト）を行い、再生を停止します。
設定時間で現在の設定値から消音まで音量を変化させます。

p1：デコーダID｜インスタンスNo
p2：経過時間（msec）
stat：0未満 = エラー

----------------------------------------
■簡易2D/3D音量パン変換
----------------------------------------
ec_vol3d_dir p1,p2,p3,p4,p5,p6,p7
簡易3D空間化による音量の自動設定を行います。
リスナー方向と音源との距離によって音量が変化します。音源が後方にある場合にも音量は減衰します。
座標は1人称視点を基準とし、Z軸＝上下方向、Y軸＝前後方向、X軸＝左右方向となる座標配置を行って下さい。
座標は整数値で指定しますが、内部では1/1000単位の実数として処理されます。

音量増幅減衰距離はリスナーと音源の距離による音量調整範囲となっており、
その距離を以下で100％、超えると無音に近くなります。
音量減衰の最小音量は無音にしたくない場合に最低値を設定できます。

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：リスナーの方向ポインタ(dir_px/dir_py/dir_pz)
p4：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p5：音量増幅の最小距離
p6：音量減衰の最大距離
p7：音量減衰の最小音量
stat：0未満 = エラー

----------
ec_pan3d_dir p1,p2,p3,p4,p5
簡易3D空間化によるパンの自動設定を行います。
リスナー方向と音源の位置によってステレオバランスが変化します。
座標はec_vol3d_dirと同じ内容です。

パン効果距離はリスナーと音源の距離によるパン調整範囲となっており、
その距離を超えると右や左の最大となります。

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：リスナーの方向ポインタ(dir_px/dir_py/dir_pz)
p4：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p5：パン効果距離
stat：0未満 = エラー

----------
ec_audio3d p1,p2,p3,p4,p5,p6,p7,p8
簡易3D空間化による音量とパンの自動設定を行います。
ec_vol3d_dirとec_pan3d_dirを同時に適用する統合処理です。

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：リスナーの方向ポインタ(dir_px/dir_py/dir_pz)
p4：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p5：音量増幅の最小距離
p6：音量減衰の最大距離
p7：音量減衰の最小音量
p8：パン効果距離
stat：0未満 = エラー

----------
ec_vol2d_ui p1,p2,p3,p4,p5,p6
簡易2D空間化による音量の自動設定を行います。
座標は画面基準とし、画面奥がZ軸＝0となる座標配置を行って下さい。
640x480画面の場合、左上が(0,0,0)、右下が(639,479,0)となります。
座標は整数値で指定しますが、内部では1/1000単位の実数として処理されます。

音量増幅減衰の距離はリスナーと音源の距離による音量調整範囲となっており、
その距離を以下で100％、超えると無音に近くなります。
音量減衰の最小音量は無音にしたくない場合に最低値を設定できます。

p6：音量減衰の最小音量

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p4：音量増幅の最小距離
p5：音量減衰の最大距離
p6：音量減衰の最小音量
stat：0未満 = エラー

----------
ec_pan2d_ui p1,p2,p3,p4
簡易2D空間化によるパン(ステレオバランス)の自動設定を行います。
座標はec_vol2d_uiと同じ内容です。

パン効果距離はリスナーと音源の距離によるパン調整範囲となっており、
その距離を超えると右や左の最大となります。

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p4：パン効果距離
stat：0未満 = エラー

----------
ec_audio2d p1,p2,p3,p4,p5,p6,p7
簡易2D空間化による音量とパンの自動設定を行います。
ec_vol2d_uiとec_pan2d_uiを同時に適用する統合処理です。

p1：デコーダID｜インスタンスNo
p2：リスナーの座標ポインタ(lsn_px/lsn_py/lsn_pz)
p3：音源の座標ポインタ（snd_px/snd_py/snd_pz）
p4：音量増幅の最小距離
p5：音量減衰の最大距離
p6：音量減衰の最小音量
p7：パン効果距離
stat：0未満 = エラー

----------------------------------------
■状態取得
----------------------------------------
ec_get_length p1,p2
サウンドの再生フレーム数を取得します。
時間変換は音源ファイルが異常な場合にはエラーを返します。
時間値はミリ秒単位で返されます。

p1：デコーダID｜インスタンスNo
p2：時間変換（1=時間値、0=フレーム値）
stat：フレーム数、0未満 = エラー

----------
ec_get_frame p1,p2
サウンドの停止フレーム位置を取得します。
時間変換は音源ファイルが異常な場合にはエラーを返します。
時間値はミリ秒単位で返されます。

p1：デコーダID｜インスタンスNo
p2：時間変換（1=時間値、0=フレーム値）
stat：フレーム値、0未満 = エラー

----------
ec_get_engframe p1
エンジン内部のフレームカウンタを取得します
フレーム値を利用することで再生タイミングの管理に利用できます。
時間変換は音源ファイルが異常な場合にはエラーを返します。
時間値はミリ秒単位で返されます。

p1：時間変換（1=時間値、0=フレーム値）
stat：フレーム値、0未満 = エラー

----------
ec_get_state p1
サウンドの再生・停止・ループ状態をビット値で取得します。
ec_is_play、ec_is_end、ec_is_loopの一括処理となります。

p1：デコーダID｜インスタンスNo
stat：ステータス値（bit0=再生中、bit1=終端、bit2=ループ再生）

----------
ec_is_play p1
サウンドの再生中を取得します。未検出で停止中も判定できます。
グループ機能を利用している場合、再生中のままグループ停止した場合には状態は再生中のまま更新されません。

p1：デコーダID｜インスタンスNo
stat：1=再生中、0=停止中、未検出

----------
ec_is_end p1
サウンドの再生位置終端を取得します。
停止中のサウンドが一時停止か再生終了なのかを判断できます。

p1：デコーダID｜インスタンスNo
stat：1=サウンド終端、0=終端ではない、未検出

----------
ec_is_loop p1
サウンドのループ再生状態を取得します。

p1：デコーダID｜インスタンスNo
stat：1=ループ再生設定、0=ループ未設定、未検出

----------------------------------------
■サウンドグループ
----------------------------------------
ec_gp_init p1
サウンドグループの初期化を行います。

p1：サウンドグループ最大値(1～32)
stat：0未満 = エラー

----------
ec_gp_start p1
サウンドグループNoのインスタンスを制御可能にします。
強制的に制御停止していたインスタンスは再開されます。インスタンスの再生中ステータスも更新を再開します。

p1：サウンドグループNo
stat：0未満 = エラー

----------
ec_gp_stop p1
サウンドグループNoのインスタンスを制御停止します。
再生中であればその状態を維持したままとなります。再生中ステータスも状態を維持されます。
この状態ではec_playやec_startによる再生は全て禁止（停止）されます。

p1：サウンドグループNo
stat：0未満 = エラー

----------
ec_gp_vol p1,p2
サウンドグループNoの音量を設定します。

p1：サウンドグループNo
volume：音量％（0-10000）
stat：0未満 = エラー

----------
ec_gp_pan p1,p2
サウンドグループNoのパンを設定します。

p1：サウンドグループNo
p2：パン（-10000から10000、0=中央）
stat：0未満 = エラー

----------
ec_gp_mute p1,p2
サウンドグループNoの消音（ミュート）を行います。

p1：サウンドグループNo
p2：ミュート（1=消音、0=解除）
stat：0未満 = エラー

----------
ec_gp_duck p1,p2,p3
サウンドグループNoの音量低下（ダッキング）を行います。

p1：サウンドグループNo
p2：音量低下％（1～100％、0=音量を戻す、-1=即時リセット）
p3：経過時間（msec）
stat：0未満 = エラー

----------
ec_gp_fadein p1,p2
サウンドグループNoの段階的音量増加（フェードイン）を行います。
設定時間で消音から現在のボリュームまで音量を変化させます。

p1：サウンドグループNo
p2：経過時間（msec）
stat：0未満 = エラー

----------
ec_gp_fadeout p1,p2
サウンドグループNoの段階的音量減少（フェードアウト）を行います。
設定時間で現在のボリュームから消音まで音量を変化させます。

p1：サウンドグループNo
p2：経過時間（msec）
stat：0未満 = エラー

----------------------------------------
■波形出力
----------------------------------------
ec_gen_wform p1,p2,p3
波形出力の仮想デコーダ＋インスタンスを生成します。
ピッチ設定を有効にすることで音の高さを変えることが出来ます。
波形のタイプは基本波形のみとなっており、波形タイプの拡張は ec_wave_formにて行います。

p1：波形の初期タイプ（0～3）

EC_WAVE_SIN 0 サイン波
EC_WAVE_SAW 1 ノコギリ波
EC_WAVE_TRI 2 三角波
EC_WAVE_PUL 3 パルス波（DT比可変)

p2：波形の振幅（-10000～10000、負にて波形の反転）
p3：波形の周波数（1000倍のHz値、1～(サンプルレート/2)まで）
stat：デコーダID（0以上）、エラー（0未満）

----------
ec_wave_out p1,p2
波形を出力します。時間値を設定することも出来ます。
ノートオンを発行するのでエンベロープ利用の場合には音量制御が開始されます。

p1：デコーダID｜インスタンスNo
p2：時間値（msec、0以下=継続）
stat：0未満 = エラー

----------
ec_wave_off p1,p2
波形を停止します。時間値を設定することも出来ます。
ノートオフを発行するのでエンベロープ利用などの場合など音量オフまでの時間が必要であれば設定します。

p1：デコーダID｜インスタンスNo
p2：時間値（msec）
stat：0未満 = エラー

----------
ec_wave_set p1,p2,p3,p4,p5
波形タイプの拡張プリセット設定や周波数や振り幅の再設定を行えます。
ec_gen_wformの設定変更として使用します（仮想デコーダやインスタンスを生成しません）
波形タイプのプリセットは基本波形＋Chiptune波形にて構成されます。

FC＝ファミリーコンピューター音源風
GB＝ゲームボーイ音源風

p1：デコーダID｜インスタンスNo
p2：波形のプリセット（0～14）

EC_WFORM_SINE      0 サイン波
EC_WFORM_SAWTOOTH  1 ノコギリ波
EC_WFORM_TRIANGLE  2 三角波
EC_WFORM_PULSE     3 パルス波（DT比可変)
EC_WFORM_WH_NOISE  4 ホワイトノイズ
EC_WFORM_FC_PULSE  5 FCパルス波（@3と同じ）
EC_WFORM_FC_TRI    6 FC三角波（@2と同じ）
EC_WFORM_FC_NZ_L   7 FCノイズ
EC_WFORM_FC_NZ_S   8 FCショートノイズ
EC_WFORM_UK_WMEM1  9 未対応１（@13と同じ）
EC_WFORM_GB_WMEM  10 GB波形メモリ
EC_WFORM_GB_NZ_L  11 GBノイズ
EC_WFORM_GB_NZ_S  12 GBショートノイズ
EC_WFORM_WAVE_MEM 13 拡張波形メモリ
EC_WFORM_UK_WMEM2 14 未対応２（@13と同じ）

p3：波形のサブプリセット

サイン波   0・・・0=通常、1=半波整流にて出力、2=全波整流にて出力
ノコギリ波 1・・・0=変位最大から位相開始、1=変位0から位相開始
三角波     2・・・0=変位最大から位相開始、1=変位0から位相開始
FC三角波   6・・・0=変位最大から位相開始、1=変位0から位相開始
GB波形メモリ   10・・・GB波形メモリのバンク番号
拡張波形メモリ 13・・・拡張波形メモリのバンク番号

p4：波形の振幅（-10000～10000、0=無音、負にて波形の反転、範囲外は未設定）
p5：波形の周波数（1000倍のHz値、1～(サンプルレート/2)まで、-1＝未設定）
stat：0未満 = エラー

----------
ec_wave_form p1,p2,p3,p4
特定波形出力のフォーマットを設定します。
分解能による音量や音色、デューティ比を変えることが出来ます。
分解能を小さく変更すると滑らかな波形をギザギザ（階段状）に変化させることが出来ます。
デューティ比はパルス波のみ適用されます。

p1：デコーダID｜インスタンスNo
p2：周波数分解能（2から32ビット）
p3：振り幅（音量）分解能（2から32ビット）
p4：デューティ比（0％から100％の100倍の値、50％=5000）
stat：0未満 = エラー

----------
ec_wave_evlp_adsr p1,p2,p3,p4,p5
エンベロープ機能を使用します。ADSRパラメータを設定します。
利用することでキーオンからキーオフまでの音量が変化します。

p1：デコーダID｜インスタンスNo
p2：attack ・・・無音から設定音量までの時間（ミリ秒）
p3：decay  ・・・attack終了後、sustainまでの時間（ミリ秒）
p4：sustain・・・decayが目指す音量レベル（100％を１とした値の100倍）
p5：release・・・キーオフの音量レベルから無音までの時間（ミリ秒）
stat：0未満 = エラー

----------
ec_wave_evlp_fcgb p1,p2,p3,p4,p5
FC/GBエンベロープ機能を使用します。レジスタパラメータを設定します。
利用することでキーオンからの音量が変化します。

FC＝ファミリーコンピューター音源風
GB＝ゲームボーイ音源風

p1：デコーダID｜インスタンスNo
p2：Volume   ・・・初期音量（0から15）
p3：Direction・・・音量変更方向（1=大きくなる、0=小さくなる）
p4：Speed    ・・・エンベロープ速度（0から15）
p5：Loop     ・・・ループフラグ（1=ループする）
stat：0未満 = エラー

----------
ec_wave_evlp_ay3 p1,p2,p3
AY3エンベロープパターン機能を使用します。レジスタパラメータを設定します。
利用することでキーオンからの音量が変化します。

AY3＝AY-3-8910(PSG)音源チップ風

p1：デコーダID｜インスタンスNo
p2：エンベロープパターンNo

EC_AYEP_FALL_SAW   0 :＼|＼|＼|＼|(減衰ノコギリ)
EC_AYEP_FALL_STOP  1 :＼＿＿＿＿＿(減衰保持)
EC_AYEP_FALL_TRI   2 :＼／＼／＼／(減衰三角)
EC_AYEP_FALL_JTOP  3 :＼|￣￣￣￣ (減衰最大保持)
EC_AYEP_RISE_SAW   4 :／|／|／|／|(増加ノコギリ)
EC_AYEP_RISE_STOP  5 :／￣￣￣￣￣(増加保持)
EC_AYEP_RISE_TRI   6 :／＼／＼／＼(増加三角)
EC_AYEP_RISE_JZERO 7 :／|＿＿＿＿ (増加ゼロ保持)

p3：エンベロープ周期（0から65535、T=(256*EP)/fc）
stat：0未満 = エラー

----------
ec_wave_evlp_off p1
エンベロープパターン機能を無効化します。

p1：デコーダID｜インスタンスNo
stat：0未満 = エラー

----------
ec_wave_wtbl_init p1,p2,p3,p4,p5,p6
GB波形メモリと拡張波形メモリの波形テーブルを設定します。
GB波形メモリは1バンクのサンプルの固定長テーブルを、
拡張波形メモリは1バンクのサンプルの可変長テーブルとサイズ格納テーブルを準備します。

GB＝ゲームボーイ音源風（1バンク32サンプル4bit）
拡張＝SCC、FDS、Namco WSG、N163音源チップ風（8bit）

p1：デコーダID｜インスタンスNo
p2：波形メモリタイプ

EC_WTBL_GB 0 GB波形メモリ
EC_WTBL_EX 1 拡張波形メモリ

p3：波形メモリテーブルの文字列ポインタ

GB＝1バイトに4bit（0から15）のサンプルを設定する
拡張＝1バイトに8bit（0から255）のサンプルを設定する
波形データは-1.0から1.0に変換されます（0.0=中心はなし）

p4：波形メモリバンクサイズの数値配列ポインタ（拡張のみ）
p5：最大サンプルサイズ（16/32/64/128/256/512/1024まで）
p6：最大バンクサイズ
stat：0未満 = エラー

----------
ec_wave_wtbl_bank p1,p2,p3
GB波形メモリまたは拡張波形メモリを使用します。

p1：デコーダID｜インスタンスNo
p2：波形メモリタイプ
p3：バンク番号
stat：0未満 = エラー

----------------------------------------
■MML再生（MML構文はリファレンス参照）
----------------------------------------
ec_mml_init p1,p2,p3,p4
MML再生機能を初期化します。
波形出力の仮想デコーダ＋インスタンスをチャンネル数生成します。

p1：最大チャンネル数（1から8）
p2：音楽再生チャンネル数
p3：音楽再生グループNo（-1=使用しない）
p4：効果音グループNo（-1=使用しない）
stat：0未満 = エラー

p1とp2の差分が効果音チャンネル数となります。
p1=p2の場合、効果音チャンネルは利用できません。
p2が0の場合には、音楽再生チャンネルは利用できません。

----------
ec_mml_shutdown
MML再生機能を終了します。

stat：0未満 = エラー

----------
ec_mml_get_ch p1
MML再生機能の各チャンネルのデコーダIDを取得します。
通常のサウンド機能にて制御を行う際に使用します。

p1：MML再生チャンネル番号（0から最大チャンネル数）
stat：0未満 = エラー

----------
ec_mml_play_bgm p1,p2,p3
MML構文を利用した音楽再生を行います。

p1：MML文字列（MML構文はリファレンスを参照）
p2：チャンネル番号（ec_mml_initの設定範囲）
p3：1=再生ループを行う、0=行わない
stat：0未満 = エラー

----------
ec_mml_play_sfx p1,p2
MML構文を利用した効果音再生を行います。
再生チャンネルは自動で選択されます。
優先度が低いと再生の空きがない場合に選択されやすくなります。

p1：MML文字列（MML構文はリファレンスを参照）
p2：優先度（0=低優先度、10=高優先度）
stat：0未満 = エラー

----------
ec_mml_play_bgm_multi p1,p2
MML構文を利用した音楽再生を多重再生にて行います。
チャンネルは0から順に利用されます。
再生トラックは音楽再生チャンネル数上限までとなります。

p1：MML文字列（MML構文はリファレンスを参照）
p2：1=再生ループを行う、0=行わない
stat：0未満 = エラー

----------
ec_mml_stop_bgm p1
再生中の音楽を停止します。

p1：停止するチャンネル番号（-1=すべて）
stat：0未満 = エラー

----------
ec_mml_stop_sfx p1
再生中の効果音をすべて停止します。

stat：0未満 = エラー

----------
ec_mml_is_playing p1
選択したチャンネルの再生中フラグを取得します。

p1：参照するチャンネル番号（-1=音楽再生チャンネルすべて）
stat：0未満 = エラー

p1に最大チャンネル数を指定すると効果音すべてが対象となります。
効果音チャンネルは自動選択なので１チャンネル利用限定です。

----------
ec_mml_get_event p1,p2,p3,p4
MML再生ステップ数など再生中のMMLイベントを取得します。
効果音チャンネルは自動選択なので１チャンネル利用限定または
MML構文イベント数などによる判断が必要です。

p1：チャンネル番号
p2：現在再生中のMML音色
p3：MML構文イベント数
p4：未対応マクロ、メタデータ削除数
stat：0未満 = エラー

----------------------------------------
■エラー処理
----------------------------------------
ec_chk_recover
サウンドデバイスの異常時に修復を試みます。
スリープ復帰後に無音状態になる場合などに使用します。
ステータスを返しますが、条件判定は自動で行われます。

stat：0未満 = エラー

----------
ec_chkerr p1
最新のエラー値を取得します。

連続処理で毎回エラーを確認せずに判定したい時などに使用します。

p1：1=保持したエラーのリセット

stat：エラー値

 0    EC_SUCCESS        正常
-1    EC_ERROR          エラー
-2    EC_INVALID_ARGS   不正なパラメータ
-3    EC_INVALID_OPERATION 不正な操作
-5    EC_OUT_OF_RANGE   値が範囲外
-7    EC_DOES_NOT_EXIST 存在しない
-11   EC_TOO_BIG        大きすぎる
-18   EC_NO_SPACE       空きがない
-19   EC_BUSY           ビジー状態
-23   EC_ALREADY_IN_USE 既に使用中
-45   EC_CONNECTION_RESET 接続がリセット
-300  EC_DEVICE_NOT_INITIALIZED 未初期化または初期化失敗



