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

MMLリファレンス

Ver0.8.0 by ze-na

----------------------------------------
■MML機能について
----------------------------------------
miniaudioの波形機能を用いた簡易MMLによる再生を行います。
波形機能には80年代の音源チップを参考にしたチップチューンライクな波形を再生できます。
音楽と効果音の波形再生を最大８チャンネルで行います。

MML構文はflmmlやピコカキコを参考にした簡易機能となります。
より具体的な説明と利用方法については以下を参照してください。

flmml：
https://web.archive.org/web/20171223224754/http://flmml.codeplex.com/

ピコカキコ：
https://dic.nicovideo.jp/a/%E3%83%94%E3%82%B3%E3%82%AB%E3%82%AD%E3%82%B3

演奏データ（MML構文）は半角テキストで記述します。
コメントについては全角で問題ありません。
マクロ定義は未対応でメタデータは一部のみ対応します。

多重再生は単体チャンネル再生を複数使用するか、
セミコロン（；）で連結したMML文字列にてマルチチャンネル再生を行います。

----------------------------------------
■ライブラリ機能
----------------------------------------
以下のAPIを利用することでMMLを再生することが出来ます。

ec_mml_init・・・初期化を行います。
ec_mml_shutdown・・・MML用の波形チャンネルを終了します。
ec_mml_get_ch・・・サウンド機能で制御するIDを取得します。
ec_mml_play_bgm・・・MML文字列を音楽用チャンネルで再生します。
ec_mml_play_sfx・・・MML文字列を効果音用チャンネルで再生します。
ec_mml_play_bgm_multi・・・MML文字列を分割し複数のチャンネルで再生します（多重再生）
ec_mml_stop_bgm・・・音楽の再生を停止します。
ec_mml_stop_sfx・・・効果音の再生を停止します。
ec_mml_is_playing・・・再生中フラグを取得します。
ec_mml_get_event・・・ステップ数など再生中のMMLイベントを取得します。

----------------------------------------
■音程
----------------------------------------
CDEFGAB：音名

ドレミファソラシの音程に対応しています。
以下の記号と数字の追加、オクターブ、テンポで変化します。
半音上げ：＋または＃
半音下げ：ー
音長：数字を付けます。1～384
付点音符：ピリオド（．）

例：A+8 cdeg-
音長は省略すると Lの値（音長デフォルト設定）が使用されます。
オクターブは Oの値や < > による Oの相対変化値が使用されます。
音程のテンポは音楽用は共通設定、効果音用は個別設定となります。

----------
R[n]：休符

[n]：音長を数値で付けます。1～384

休符は数字の追加、テンポで変化します。
音長は省略すると Lの値（音長デフォルト設定）が使用されます。
休符のテンポは音楽用は共通設定、効果音用は個別設定となります。

----------
O[n]：オクターブの設定

[n]：音程を変えます。0～8（4）

----------
< >：オクターブの相対設定

音程を記号にて相対変化させます。0～8
<：１上げます
>：１下げます
多くのMML構文仕様にある記号とは逆になります。
記述の向きを変えたいときはメタデータ#OCTAVE REVERSEを利用します。

----------
@D[n]：デチューン

セント（音程を測定するための単位）単位でピッチを調整します。
12平均律の半音を100セントに分割しています。1オクターブで1200セントです。
[n]：セント値を指定します。100で半音上げ、-100で半音下げです。

----------------------------------------
■音長
----------------------------------------
L[n]：デフォルト音長の設定

[n]：1～384（4）
音名（CDEFGAB）の音長を指定できます。

----------
Q[n]：ゲートタイムの設定

[n]：0～16（15）

----------
&：スラー

直前の音符を延長します。

----------------------------------------
■音量
----------------------------------------
V[n]：ベロシティ（音量）指定

[n]：音量値 0～15
大まかな音量設定を行います。
設定値は [n]×8+7として@Vの範囲にて設定されます。
そのため、V0は @V7相当となります。
このコマンド実行にて音量相対コマンドの数値変化量が変わります。

----------
@V[n]：ベロシティ（音量）指定

[n]：音量値 0～127（100）
細かな音量設定を行います。
このコマンド実行にて音量相対コマンドの数値変化量が変わります。

----------
( （括弧）：ベロシティ（音量）相対的に１段階上げ

直前に使った音量コマンドが V か@V かによって変化量
数字を添えて

----------
 ) （括弧閉じ）：ベロシティ（音量）相対的に１段階下げ

直前に使った音量コマンドが V か@V かによって変化量

 #VELOCITY REVERSE

----------------------------------------
■制御
----------------------------------------
T[n]：１分間の拍数（BPM）テンポを設定

[n]：40～（120）小数点第二位まで指定
マルチチャンネル再生の場合には、全チャンネルに適用されます。

----------
;（セミコロン）：多重再生時のチャンネル分割

マルチチャンネル時：MML文字列を分割しチャンネル分割後再生します。
flmmlやピコカキコとは異なりセミコロンごとにチャンネル分割します。
チャンネルは初期化時に指定した音楽チャンネル数を上限とします。
例：T120;の場合、テンポ設定だけで１チャンネル消費します。

単体チャンネル時：区切り（多重）とならずに連続で再生します。
多重再生する場合には事前にMML文字列の分割が必要です。

----------
/:[n]…/…:/ ：繰り返しの指定

「/:」から「:/」の間を [n]回繰り返します。
[n]：ループ回数 2～(2) 無限ループはありません。
ループネスト上限は10。
ループ内に「 / 」があれば最終ループはその場所にて、ループを抜けます。

----------
/* ...... */ ：コメント

MML文字列内にコメントを挿入できます。
全角文字を含むことが出来ます。

----------------------------------------
■音色
----------------------------------------
@0：波形パターンにサイン波を使用

@0 または @0-0：通常のサイン波
@0-1：サイン波を半波整流にて出力
@0-2：サイン波を全波整流にて出力

----------
@1：波形パターンにノコギリ波を使用

@1 または @1-0：変位最大から位相スタート
@1-1：変位0から位相スタート

----------
@2：波形パターンに三角波を使用

@2 または @2-0：変位最大から位相スタート
@2-1：変位0から位相スタート

----------
@3：波形パターンにパルス波を使用

@W[n] を設定することで、パルス幅（デューティ比）を指定できます。

----------
@4：波形パターンにホワイトノイズを使用

@N[n] を設定することで、ノイズ周波数を指定できます。

----------
@5：波形パターンにFCパルス波を使用

@W[n] を設定することで、パルス幅（デューティ比）を [n]×12.5％ に指定できます。

----------
@6：波形パターンにFC三角波を使用

@6 または @6-0：変位最大から位相スタート
@6-1：変位0から位相スタート

----------
@7：波形パターンにFCノイズを使用

LFSRにて擬似ノイズ生成されます。

----------
@8：波形パターンにFCショートノイズを使用

LFSRにて擬似ノイズ生成されます。

----------
@9：波形パターン未対応

未対応のため@13が設定されています。

----------
@10：波形パターンにGB波形メモリを使用

#WAV10 [n],[desc]にて定義した波形データを使用
@10-0、@10-1など波形番号をつけて記述

----------
@11：波形パターンにGBノイズを使用

LFSRにて擬似ノイズ生成されます。

----------
@12：波形パターンにGBショートノイズを使用

LFSRにて擬似ノイズ生成されます。

----------
@13：波形パターンに波形メモリを使用

#WAV13 [n],[desc]にて定義した波形データを使用します。
@13-0、@13-1など波形番号をつけて記述します。

----------
@14：波形パターン未対応

未対応のため@13が設定されています。

----------------------------------------
■音色設定
----------------------------------------
@W[n]：パルス幅（デューティ比）を設定

パルス波形モード（@3、@5）にて使用します。
[n]：@3＝-100～100（50）、@5＝1～7（4）

@3では、1％ や 99％に丸められます。
負の数で指定した場合は、MIXモード（ノイズ混じりの音）として認識されます。
その際は、絶対値がパルス幅となります。
MIXモードで使用するノイズモジュールは @4となります。
@5では、[n]×12.5％にて設定されます。

----------
@N[n]：ホワイトノイズの周波数を指定

[n]：ノイズ周波数を設定 0～127（0）
@4または@3のmixモードで、ノイズ周波数を定義します。

----------
@E1,[n],[n],[n],[n]：エンベロープ設定

[n]：attack ・・・無音から設定音量までの時間（[n]×1/127秒）
[n]：decay  ・・・attack終了後、sustainまでの時間（[n]×1/127秒）
[n]：sustain・・・decayが目指す音量レベル（[n]/127＝0.0～1.0）
[n]：release・・・キーオフの音量レベルから無音までの時間（[n]×1/127秒）

----------------------------------------
■波形データ定義
----------------------------------------
#WAV10 [n],[desc]GB波形メモリ音源（@10）の波形データ定義

[n]：波形番号 0～31
[desc]：波形データ。固定32サンプルの波形データを１周期分で記述します。
空白入りはOK、データは改行までなので、一行で記述してください。
（例：パルス波DT比1:1なら＃WAV10 0,FFFF FFFF FFFF FFFF 0000 0000 0000 0000）

変位データ -1.0＝16進：0
変位中心    0.0＝なし（16進：7と8の間）
変位データ +1.0＝16進：F

----------
#WAV13 [n],[desc]：波形メモリ音源（@13）の波形データ定義

[n]：波形番号 0～31
[desc]：波形データ。最大256サンプルの波形データを１周期分で記述します。
空白入りはOK、データは改行までなので、一行で記述してください。
（例：パルス波DT比1:1なら＃WAV13 0,FFFF0000（4データの場合））

変位データ -1.0＝16進：00
変位中心    0.0＝なし（16進：7Fと80の間）
変位データ +1.0＝16進：FF



