Macro_Sound: 音声/BGM操作用吉里吉里マクロ集リファレンス

概要：
	Macro_Soundは吉里吉里/KAG上で効果音/BGMを操作するためのマクロ群である。
	　・バッファを手で指定しなくていいようにする
	　・音量やpanを階層的に管理できるようする
	ために作成した。
	BGM操作タグは、KAGのものをそのまま使用してもよかったのだが、なんとなく
	作った。統一の美しさ的に。
	mp3/ogg/wav/mid/tcwなら再生可能。

使用例:
	; ↓ 効果音バッファを４つ確保しつつ初期化
	[sound_init num=4]

	; ↓ 美夏の声(minatsu001)を volume=50で再生
	[se_play name=美夏 storage=minatsu001 volume=50]

	; ↓ 美夏ともみじの声を同時に再生。バッファは適当に確保される
	[se_play name=美夏 storage=minatsu001]
	[se_play name=もみじ storage=momiji001]

	; ↓蝉効果音と鈴虫効果音を再生(名前なし)。別の音声バッファを自動的に
	; 確保するので、重ねて独立に再生可能。
	[se_play storage=semi loop=true volume=80]
	[se_play storage=suzumushi loop=true volume=70]

	; ↓グループ："ボイス"、名前："美夏"および"もみじ"を登録し、大域音量を
	; 70とする。これで、美夏はvol=70、もみじはvol=63で再生される。
	[se_reggroup group="ボイス" volume=70]
	[se_reg      group="ボイス" name="美夏" volume=100 pan=100]
	[se_reg      group="ボイス" name="もみじ" volume=90 pan=0]
	; で、もみじ、美夏を再生。groupは自動的に"ボイス"に設定される
	[se_play name="もみじ" storage="いやよ"]
	[se_play name="美夏" storage="そんな…"]

	; ↓グループ："ボイス"と"se"を効果音グループとして作成する。
	; バッファを再利用可能とし、再生中に不足した場合は途切れさせる。
	; その後、グループ音量を50に変更する
	[se_reggroup group=ボイス volume=70]
	[se_reggroup group=se 　　volume=70 reclaim=true]
	[se_play group=se storage="ガラス割れる" wait=true]
	[se_play group=se storage="ドサッ" wait=true]
	[se_groupopt volume=50]
	[se_play group="ボイス" name="美夏"storage="大丈夫！？"]


実装方針：
	効果音はグループ名とSE名をつけて管理することができる。
	前者を効果音グループ、後者を効果音ラインと呼ぶ。前者はコンフィグ画面
	などからつつくために、後者はゲーム中で一時的にボリュームを変更する
	ために使用する。
	・SE名は、たとえば "鈴虫"、"あかね" など、具体的な、単数の音ラインを
	　指定する。SE名を省略した場合、内部でUUIDにて指定される。
	・SE名/グループ名は全てユニークでなければならない。
	・効果音グループは、たとえば "効果音"、"ボイス" など、複数のSEを纏めて
	　音量・パン指定するために作成する。
	・グループ名"master"は、全体の音量管理用に無条件に作成される。
	　このグループの下位階層に、たとえば "効果音"、"ボイス" などを配置する
	　ことで、「master のボリュームを変更すると効果音もボイスもボリュームが
	　変更される」ことが実現できる。
	・効果音グループは階層的に定義可能。下位階層のグループは、上位階層の
	　音量に影響を受ける。たとえばgroup Aの下のgroup Bに属する効果音 C の
	　音量(volume)は、
		A-volume(0〜100) x B-volume(0〜100) x C-volume(0〜100)/1000000
	　となる。A(vol=80), B(vol=50), C(vol=90)なら、最終的にvol=36となる。
	　panは累積加算され,A(pan=-50), B(pan=30), C(pan=-2)なら、pan=-22。

	効果音ラインは、再生時に適宜自動的・動的にKAGのバッファを確保する。
	このため、KAG効果音バッファは適当に使い回され、効果音バッファNo.
	([playse]のbuf=)を指定する必要はない。
	同じ効果音ラインで次の効果音を再生すると、前の音は途切れる。
	SE名を省略した場合、可能な限り空きバッファを探して多重再生を試みる。

	[bgm_*]タグは少し特殊。通常は'master'にも依存せず、単に[bgmopt]などの
	KAG コマンドのラッパーとして動作する。
	しかし、'BGM'という名前で効果音ラインを作成すると、自動的にその
	効果音ラインの音量を参照する。'master'が親に居ればそれにも依存する。

	なお、このマクロで提供される効果音とBGMの操作タグは、特に指定しない
	限り終了を待たずに戻ることに注意。

構造例：
	キャラクタはキャラ・男女ごとにそれぞれ音量が指定可能、キャラとして
	音量設定する、などの構成は以下の通り。[]がグループ。これは複雑な
	例であり、普通は([キャラ女][キャラ男]が別など)もっと簡単な構成に
	なる、だろう。きっと。

	[master] ---+--[キャラ]--+--[女]-- あかね(登録済み効果音ライン)
	            |            |
	            |            +--[男]-- アキヒト(登録済み効果音ライン)
	            |            |
	            |            +-------- ガヤ(登録なし効果音ライン)
	            |
	            |
	            +--[効果音]-------+--- 鈴虫(登録なし効果音ライン)
	            |                 |
	            |                 +--- ガラス割れる(登録なし効果音ライン)
	            |
	            +----------------------BGM(BGMライン)
		※ BGMラインは、[se_reg name='BGM']が登録された時のみ
		　 'master'の下に配置。そうでなければ'master'とは独立して
		　 再生される。

	; 上を構成するスクリプト
	[sound_init num=3]
	[se_reggroup group=キャラ]
	[se_reggroup group=効果音]
	[se_reggroup group=女 parent=キャラ]
	[se_reggroup group=男 parent=キャラ]
	[se_reg name=あかね group=女]
	[se_reg name=アキヒト group=男]
	[se_reg name=BGM]

	; 音を鳴らす例
	[se_play group=効果音 storage=鈴虫 loop reclaim=false]
	[se_play group=効果音 storage=ガラス割れる] ; nameはUUIDに自動設定される
	[se_play group=キャラ storage=ガヤ loop reclaim=false]

	
タグリファレンス：------------------------------------------------------------

パラメータを指定しなかった場合、(def)またはdefaultと書いてあるものが
デフォルト値として採用される。

[sound_init]
説明:
	音声関係を初期化する。今は必要が無いのでSE周りしか初期化していない。
	エラーチェックはほぼしないので、これを呼び出す前に、config.tjs中で
	十分な量のkag.numSEBuffersが確保されていることが必要。
	再生中だった効果音は停止される。BGMは(今の実装では)停止しない。
引数:
	num=		Macro_Soundで確保するSEバッファ数。kag.numSEBuffers
			より小さくなければならない。この数だけkag.numSEBuffers
			から使用する。省略すると、kag.numSEBuffersと同じ。
	reinit=		一度初期化済みの場合、登録されている効果音を削除し、
			"master"を再作成するか
		true	する(def)
		false	しない
例:
	; 全ての効果音バッファをMacro_Soundで使用する
	[sound_init]
	; 効果音バッファのうち、0〜3をMacro_Soundで使用する
	[sound_init num=4]

[se_reggroup]
説明:
	効果音グループを登録する。
引数:
	group=		グループ名(省略不可)
	parent=		親グループ名(省略すると"master")
	volume=		効果音グループのボリューム初期値(def=100)
	gvolume=	効果音グループの大域ボリューム初期値。def=100。
	pan=		効果音グループのパン初期値(def=0)

[se_unreggroup]
説明:
	効果音グループを削除する。
	このグループに属する全ての効果音ラインも削除される。削除される効果音
	ラインが発音中であれば音を停止する。
引数:
	group=		グループ名(省略すると全てが対象)

[se_groupopt]
説明:
	効果音グループのパラメータを設定する。グループが登録されていなければ
	登録する。volume/gvolumeを変更すると、このグループに関係する発声中の
	効果音の音量が、リアルタイムで変更される。

引数:
	group=		グループ名(省略可、全効果音グループを対象とする)
 	volume=		効果音グループのボリューム。
			def=groupが登録済みならcurrent、新規登録なら100
	gvolume=	効果音グループのgボリューム。
			def=groupが登録済みならcurrent、新規登録なら100
 	pan=		パン。
			def=groupが登録済みならcurrent、新規登録なら0

[se_reg]
説明:
	効果音ラインを登録する。このタグで登録したSE名は、[se_unreg]しない限り
	以降削除されない。※[se_play]のeternalをtrueとした場合と同じ。
引数:
	name=		SE名(省略不可)、ユニークであること
	group=		グループ名(省略可、省略すると "master")
	volume=		効果音のボリューム。def=100
	gvolume=	効果音の大域音量。def=100
	pan=		パン。def=0
	eternal=	この効果音ラインを保持し続けるかどうか。def=true
			falseなら、効果音の再生が終わった後に削除される
	reclaim=	この効果音が発音中で、効果音バッファが不足した場合、
			この効果音を停止して他の音を再生させるかどうか。
		true	停止可能。発音中の音が停止されることがあるので注意
		false	停止不可能(def)

[se_unreg]
説明:
	SE名を削除する。再生中であれば停止し、保持していた音量やパンなどの
	データも破棄する。[se_reg eternal=true]の効果音ラインも削除する。
引数:
	name=		SE名(省略すると全効果音が対象になる)

[se_play]
説明:
	効果音を再生する。name=が指定された場合、名前付き効果音ラインとして
	[se_reg]で登録する。同じname=で別の効果音を再生した場合は、
	前の効果音が途切れる。
	nameを省略すると発音が終了するまでのテンポラリとなり、name=は適当な
	UUIDが割り振られる。この時、eternalを指定することはできない。
	グループにreclaim=trueが指定されている場合、可能な限り他の音が
	途切れないように効果音バッファを使いまわして再生を試みる。
	効果音バッファが足りなくなった場合は、reclaim可能なグループの再生中
	効果音が途切れ、そのバッファが使いまわされる。それでも効果音バッファが
	不足した場合は、エラーダイアログを表示する。
引数:
	name=		SE名(省略可、省略すると内部でUUIDが割り当てられる。
	group=		グループ名(省略可、省略すると、name=が登録済みなら
			それを探し、無ければ"master")
	storage=	効果音ファイル(拡張子不要、mp3/wav/oggを自動検索する)
	loop=		ループ再生するかどうか。
		true	ループ再生する
		false	ループ再生しない(def)
	canskip=	スキップ可能かどうか。wait=trueが指定された時のみ有効
		true	スキップ可能(def)
		false	スキップ不可能
	wait=		再生終了待ちをするかどうか。
			loop=trueなら無限ループ再生なので、たとえwait=trueでも
			無視する。
		true	再生終了待ちをする
		false	再生終了待ちをしない(def)
	waitprev=	同じnameで前の効果音が再生中の場合にその終了を待つか
		true	待つ
		false	待たない(def) 
 	volume=		効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
	gvolume=	効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
 	pan=		パン。
			def=nameが登録済みならcurrent、新規登録なら0
	eternal=	永久にこの効果音ラインを保存するか。キャラクタボイスの
			ように、永久に保存する(ボリューム等で、前回発音のものを
			引き継ぐ)場合はtrueを指定。
			name=を省略する場合は、削除できなくなるので
			eternal=trueを指定しないこと！
		true	この効果音ラインを保存する
		false	この効果音ラインを保存しない(def)
	reclaim=	この効果音が発音中で、効果音バッファが不足した場合、
			この効果音を停止して他の音を再生させるかどうか。
		true	停止可能。発音中の音が停止されることがあるので注意
		false	停止不可能(def)

[se_fadein]
説明:
	効果音をフェードイン再生する。以下全て[se_play]と同じ。
	引数はtimeとwaitfade以外全て[se_play]と同じ。
引数:
	name=		SE名(省略可、省略すると"何かユニークな値")
	group=		グループ名(省略可、省略すると、name=が登録済みなら
			それを探し、無ければ"master")
	storage=	効果音ファイル(拡張子不要)
	loop=		ループ再生するかどうか。
		true	ループ再生する
		false	ループ再生しない(def)
	canskip=	スキップ可能かどうか。wait=trueが指定された時のみ有効
		true	スキップ可能(def)
		false	スキップ不可能
	waitfade=	フェードイン待ちをするかどうか
		true	フェードイン待ちをする
		false	フェードイン待ちをしない(def)
	wait=		効果音終了待ちをするかどうか
		true	終了待ちをする
		false	終了待ちをしない
	waitprev=	前の効果音が再生中の場合にその終了を待つかどうか。
		true	待つ
		false	待たない(def) 
	time=		フェードイン時間をms単位で指定する。def=2000
 	volume=		効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
	gvolume=	効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
 	pan=		パン。
			def=nameが登録済みならcurrent、新規登録なら0
	eternal=	永久にこの効果音ラインを保存するか。キャラクタボイスの
			ように、永久に保存する(ボリューム等で、前回発音のものを
			引き継ぐ)場合はtrueを指定。
			name=を省略する場合は、削除できなくなるので
			eternal=trueを指定しないこと！
		true	この効果音ラインを保存する
		false	この効果音ラインを保存しない(def)


[se_fadeout]
説明:
	効果音をフェードアウトする。
	name=が省略された場合、group=で指定された全ての効果音をフェードアウト
	する。
引数:
	name=		SE名(省略可、省略するとgroup=の全効果音が対象になる
	group=		グループ名(省略可、省略するとname=が登録済みならそれを
			探し、name=が省略されていた場合は全効果音を対象とする)
	storage=	指定されていると、最初にこのストレージを発音し、
			フェードアウトする。
	time=		フェードアウト時間をms単位で指定する。def=2000
	canskip=	スキップ可能かどうか。wait=trueが指定された時のみ有効
		true	スキップ可能(def)
		false	スキップ不可能
	wait=		効果音終了待ちをするかどうか(普通はこちらは使わない)
		true	終了待ちをする
		false	終了待ちをしない
	waitfade=	フェードアウト待ちをするかどうか。
		true	フェードアウト終了待ちをする
		false	フェードアウト終了待ちをしない(def)


[se_fade]
説明:
	効果音をフェードする。
	name=が省略された場合、group=で指定された全ての効果音をフェードする。
引数:
	name=		SE名(省略可、省略するとgroup=の全効果音が対象になる
	group=		グループ名(省略可、省略するとname=が登録済みならそれを
			探し、name=が省略されていた場合は全効果音を対象とする)
	time=		フェード時間をms単位で指定する。def=2000
	canskip=	スキップ可能かどうか。wait=trueが指定された時のみ有効
		true	スキップ可能(def)
		false	スキップ不可能
	wait=		効果音終了待ちをするかどうか
		true	終了待ちをする
		false	終了待ちをしない(def)
	waitfade=	フェード待ちをするかどうか。
		true	フェード終了待ちをする
		false	フェード終了待ちをしない(def)

[se_stop]
説明:
	効果音を停止する。
	name=が省略された場合、group=で指定された全ての効果音を停止する。
引数:
	name=		SE名(省略可、省略するとgroup=の全効果音が対象になる
	group=		グループ名(省略可、省略するとname=が登録済みならそれを
			探し、name=が省略されていた場合は全効果音を対象とする)

[se_wait]
説明:
	効果音の終了を待つ。
	name=が省略された場合、group=で指定された全ての効果音を待つ。
引数:
	name=		SE名(省略可、省略するとgroup=の全効果音が対象になる
	group=		グループ名(省略可、省略するとname=が登録済みならそれを
			探し、name=が省略されていた場合は全効果音を対象とする)
	waiting=	待つ効果音の種類。
		finish	効果音の再生終了を待つ(def)
		fade	効果音のフェードイン／フェードアウト終了を待つ
	canskip=	スキップ可能かどうか
		true	スキップ可能(def)
		false	スキップ不可能


[se_opt]
説明:
	効果音のパラメータを設定する。ここで指定されるパラメータは、現在
	登録済みのSE名単体のものであり、eternalが指定されていない限り保存
	されない。[se_groupopt]で指定するもの(=効果音グループの値)とは
	別である。
	name=が省略された場合、group=で指定された全ての効果音を設定する。
引数:
	name=		SE名(省略可、省略するとgroup=の全効果音が対象になる
	group=		グループ名(省略可、省略するとname=が登録済みならそれを
			探し、name=が省略されていた場合は全効果音を対象とする)
 	volume=		効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
	gvolume=	効果音のボリューム。
			def=nameが登録済みならcurrent、新規登録なら100
 	pan=		パン。
			def=nameが登録済みならcurrent、新規登録なら0

[se_cache]
説明:
	効果音をキャッシュに読み込む。KAGの[playse]では、必ずstorageを
	指定するため、[playse]実行時に少し時間がかかる。アニメーションとの
	同期が必要な場合に引っかかってしまうので、これを防ぐためのタグ。
	実際にはバッファを確保し、一度	音量0で再生するだけ。
引数:
	name=		SE名(省略可、省略すると"noname")
	group=		グループ名(省略可、省略すると、name=が登録済みなら
			それを探し、無ければ"master")
	storage=	効果音ファイル(拡張子不要)


#############################################################################

[bgm_play storage= volume= loop=true replaysame=false]
説明:
	BGMを再生する。
引数:
	storage=	再生BGMのストレージ。mp3/ogg/wavなら再生可能。拡張子
			省略可。
	volume=		BGMのボリューム設定。無指定で変更なし。
	loop=		ループ再生するかどうか。デフォルトではtrue。
	replaysame=	同じストレージを指定した時に、先頭から再生しなおすか。
			デフォルトでは同じストレージを指定すると再再生せず、
			単純に無視する。def=false。


[bgm_stop]
説明:
	BGMを停止する。


[bgm_fadein storage= volume= time=2000 loop=true wait=false]
説明:
	BGMをフェードインする。
引数:
	storage=	再生BGMのストレージ。拡張子省略可。
	volume=		BGMのボリューム設定。無指定で変更なし。
	time=		フェードイン時間。def=2000(ms)
	loop=		ループ再生するかどうか。デフォルトではtrue。
	wait=		フェードインを待つ。def=false


[bgm_fadeout time=2000 wait=false]
説明:
	BGMをフェードアウトする。
引数:
	time=		フェードアウト時間。def=2000(ms)
	wait=		フェードアウトを待つ。def=false


[bgm_fade time=2000 volume=1000 wait=false]
説明:
	BGMをフェードする。
引数:
	volume=		BGMのボリューム設定。無指定で変更なし。
	time=		フェードイン時間。def=2000(ms)
	wait=		フェードを待つ。def=false


[bgm_pause]
説明:
	BGMを一時停止する


[bgm_resume]
説明:
	BGMを一時停止解除する


[bgm_wait]
説明:
	BGMの終了を待つ。フェードと実際の終了を待つ
引数:
	waiting=	待つBGMの種類。
		finish	BGMの再生終了を待つ(def)
		fade	BGMのフェードイン／フェードアウト終了を待つ
	canskip=	スキップ可能かどうか
		true	スキップ可能(def)
		false	スキップ不可能


[bgm_opt]
説明:
	BGMのoptionを設定する。というかbgmoptのラッパ。
	ただし、volume,gvolumeには分数表示(1/3など)が可能。


########################################################################
おまけ。メニューなどでSEを再生する場合、この仕組みを使って再生するので
あれば、[button exp=se_play(%[storage:リーン, group=se])などと指定する。
つまり、se_play()というグローバル関数があり、これに[se_play]の引数を
辞書で指定すればよい。