TEsound (日本語)

TEsound について

TEsound は Love2D フレームワーク用の音声管理ライブラリです。 TEsound はゲームにおいての音声および音楽の使用をより簡単にすることを意図しています。

このライブラリの使用条件は ZLIBライセンスです。このライブラリを使用したゲームが多額の利益を出した場合は、制作者への僅かばかり寄付を宜しくお願いします。

ダウンロード

現在、 Dropbox のリンクは切れています。後世のため、そして配布が再開されるまで保存してあります。それまでは、 こちら の GitHub のリンクをご利用ください。

Dropbox から入手

連絡先

準備

モジュールにある全ての関数は TEsound 名前空間に存在しており、従ってグローバル変数への干渉を心配する必要はありません。メモリおよびチャンネルは自動的に管理されます。

  1. あなたのゲームのフォルダへ TEsound.lua を配置します。
  2. main.lua の先頭へ、 require"TEsound" の行を追加します。
  3. love.update() へ、 TEsound.cleanup() の行を追加します。

よくある質問と回答

Q) どの様にして音声の再生を行いますか?
A) 再生を行うために必要な全てのものは TEsound.play(sound) であり、ここでの sound は音声ファイルへのファイルパス文字列または SoundData のいずれかです ("sounds/boom.ogg" といったように)。
Q) 三種類の様々な跳躍効果音があるとき、どうすれば、この中から一つを無作為に再生することができますか?
A) TEsound.play(list)list{"jump1.ogg", "jump2.ogg", "jump3.ogg"} の様な形式のテーブルであれば可能です。
Q) 無作為な音楽を一定不変で再生できますか?
A) もちろん! TEsound.playLooping(list) を使えばできます。楽曲が一曲終了する時に、リストから新規の一曲を自動的に再生開始します。
Q) どうやって楽曲の停止をしますか? / 音声タグとは?
A) 最良の方法は TEsound の"タグ付加"機能を使用することです。単純に配置すると、 TEsound は再生中の音声に対して一つ以上のタグを付加して、与えられたタグにある全ての音声に対して様々な関数を呼び出す事ができます。従って、これをこのようにすることができます:
TEsound.playLooping("song1.ogg", "music")
TEsound.stop("music")
希望すれば音声は複数のタグを所有でき (リストを使用する: TEsound.play(sound, {"something", "whatever", "lol"})、さらに複数の音声でタグを共有できます TEsound.pitch("sfx", .5) といったものを呼び出したとき、 "sfx" があるタグの全音声は直ちに低い音になります)。指定された音声を使用して作業を行いたい場合は、タグを固有のものにすることができます。
Q) 全音声に対して音量/音の高さを変更したい場合はどうしますか?
A) その目的のために特別な "all" タグがあります。音声に対してタグを与える必要はなく、自動的に適用されます。従って全ての音量を半分に引き下げたいのであれば TEsound.volume("all",.5) のようにします。
Q) 再生機器の効果音、音楽、声優による演技に対して様々な音量を選択したい。それは TEsound で扱うことができますか?
A) はい! TEsound.volume(tag, volume) により任意のタグに対して乗算音量を設定することができます。タグの音量変更は直ちに適用されます (既に演奏中の音声であってもです!)。従って TEsound.volume("voice", .75) を使用することができ、さらに "voice" タグがある任意の音声を 音量 .75 で再生します。これは音声そのものの音量および "all" タグが設定されているものに対して乗算を行います。 ― TEsound.play("splat.ogg", "sfx", .5) である場合、および "sfx" および "all" タグへ音量 .6 および 1 を設定したならば、音声の再生音量は .3 になります。
Q) このモジュールの名称においてどのような発音をしますか? "ティー・サウンド"ですか
A) それでよいですが、しかし私は、個人的に、 "ツェー・サウンド" と発音します ;)

関数

再生関数

TEsound.play

TEsound.play(sound, tags, volume, pitch, func)

音声を再生します。 再生中の音声チャンネルの本数または nil およびエラーメッセージのいずれかを返します。

table sound
音声ファイルへの SoundData または、ファイルパス文字列 (例: "sounds/jump.ogg") のいずれか。リスト使用時、リストから無作為な音声を再生します。
table tags ({})
音声を識別するために使用できる一つ以上のタグ (例えば、単数では: "music" です。例えば、複数では: {"sfx", "gun", "player"} です)。タグは複数の音声にて共有、またはタグは固有なものである場合があります。省略時は、タグは割り当てられません。文字列を渡すことはテーブルにある単一項目を渡すためだけの速記法です。
number volume (1)
0 から 1 の間の数値で音声の大きさを指定します。音声にて音量が指定されたタグがある場合は、この数値にて乗算します (つまり、 "sfx" タグを音量 0.5, にて使用した場合、 "sfx" の音量は 0.6 になり、音量は 0.3 で音声を再生します)。
number pitch (1)
音声の再生において速度/音声の高さを数値で指定します。音声の高さが指定されたタグである場合は、この数を乗算します。
function func (コールバックなし)
音声の再生完了時に呼び出される関数 (引数を一つ渡します。 ― 音声の音量と高さのリスト)。省略時、関数を使用しません。

TEsound.playLooping

TEsound.playLooping(sound, tags, n, volume, pitch)

音声を n 回繰り返して反復再生します。 n が未指定時は TEsound.stop により手動停止されるまでループします。再生中の音声チャンネルの本数または nil およびエラーメッセージのいずれかを返します。

table sound
TEsound.play を参照してください。リスト使用時、各ループは無作為にリストから選択されます。無作為な背景音楽に適しています。
table tags
TEsound.play を参照してください。
number n
音声のループ回数。省略時、音声は無限ループされます。
number volume
TEsound.play を参照してください。
number pitch
TEsound.play を参照してください。


音声調節関数

TEsound.volume

TEsound.volume(channel, volume)

チャンネルまたはタグおよびそのループに対して音量を設定します (もしあれば)。

number channel
どのチャンネルへ影響を与えるか決定します。音声チャンネルが静的 (static) ではないときは、一般にタグ・メソッドの使用は望ましいです (以下を参照)。
number volume (無変更)
TEsound.play を参照してください。省略時は、音の高さを変更しません (ほとんどの場合は無意味です)。

TEsound.volume

TEsound.volume(tag, volume)

チャンネルまたはタグおよびそのループに対して音量を設定します (もしあれば)。

string tag
どのチャンネルへ影響を与えるか決定します。そのタグにある再生中の全チャンネルへ影響を与えます。音声チャンネルが静的 (static) ではないときは、一般にタグ・メソッドの使用は望ましいです。
number volume (無変更)
TEsound.play を参照してください。省略時は、音の高さを変更しません (ほとんどの場合は無意味です)。

TEsound.pitch

TEsound.pitch(channel, pitch)

チャンネルまたはタグおよびそのループに対して音の高さを設定します (もしあれば)。

number channel
TEsound.volume を参照してください。
number pitch (無変更)
TEsound.play を参照してください。省略時は、音の高さを変更しません。

TEsound.pitch

TEsound.pitch(tag, pitch)

チャンネルまたはタグおよびそのループに対して音の高さを設定します (もしあれば)。

string tag
TEsound.volume を参照してください。
number pitch (無変更)
TEsound.play を参照してください。省略時は、音の高さを変更しません。

TEsound.pause

TEsound.pause(channel)

チャンネルまたはタグを一時停止します。再生再開を行うためには TEsound.resume を使用してください。

number channel
TEsound.volume を参照してください。

TEsound.pause

TEsound.pause(tag)

チャンネルまたはタグを一時停止します。再生再開を行うためには TEsound.resume を使用してください。

string tag
TEsound.volume を参照してください。

TEsound.resume

TEsound.resume(channel)

チャンネルまたはタグから再生再開を行います。

number channel
TEsound.volume を参照してください。

TEsound.resume

TEsound.resume(tag)

チャンネルまたはタグから再生再開を行います。

string tag
TEsound.volume を参照してください。

TEsound.stop

TEsound.stop(channel, finish)

音声チャンネルまたはタグのいずれかを直接または完了時に停止を行って、ループを阻止します。

number channel
TEsound.volume を参照してください。
boolean finish (false)
true の場合は、音声は直ちに停止する代わりに再生を完了することができるようになります。これは主にループを正常終了するために使用されます。

TEsound.stop

TEsound.stop(tag, finish)

音声チャンネルまたはタグのいずれかを直接または完了時に停止を行って、ループを阻止します。

string tag
TEsound.volume を参照してください。
boolean finish (false)
true の場合は、音声は直ちに停止する代わりに再生を完了することができるようになります。これは主にループを正常終了するために使用されます。


設備関数

TEsound.cleanup

TEsound.cleanup()

メモリを解放して、完了した音声をきれいにします。これは love.update() の内側にて呼び出すことを強く推奨します。呼び出さない場合は、メモリとチャンネルは解放されず音声はループしなくなります。

TEsound.volume

TEsound.volume(tag, volume)

指定されたタグの音量段階を変更します。音量の変更は直ちに効果として適用され再度変更されるまで継続します。これは音声の全分類における変更に対して推奨されるため、従って効果音、音楽 (しかし音声に対して適切なタグ付けを行うことをお忘れなく)、などの全て音量を個別に調整することができます。音声に対して音量が設定された複数のタグがある場合は、第一番目 (タグ・リストの順序) のものが使用されます。

string tag
タグの音量を設定します。また "all" と呼ばれる全音声 (もしあれば、標準的なタグへ追加します) へ乗算を行う特別なタグがあります。 ― 主音量制御にて使用します。これを発生させるために "all" タグを音声へ割り当てられる必要はありません。
number volume (選択)
TEsound.play を参照してください。省略時、タグは音声に一致する高さに影響しなくなります。

TEsound.tagPitch

TEsound.tagPitch(tag, volume)

指定されたタグの音の高さを変更します。変更は直ちに効果として適用され再度変更されるまで継続します。これは音声の全分類における変更に対して推奨されます。音声に対して音の高さが設定された複数のタグがある場合は、第一番目 (タグ・リストの順序) のものが使用されます。

string tag
TEsound.volume を参照してください。
number pitch (選択)
TEsound.play を参照してください。省略時、タグは音声に一致する高さに影響しなくなります。


内部関数

TEsound.findTag

TEsound.findTag(tag)

与えられたタグにある全音声チャンネルのリストを返します。

string tag
このタグにある全音声のチャンネルを返します。

TEsound.findVolume

TEsound.findVolume(tag)

指定されたタグ(複数可)に対して音量の段階、またタグ(複数可)の音量が設定されていない場合は 1 を返します。 タグのリストが指定された場合、最初のタグに設定されている段階を返します。

string tag
音量を確認するタグを選択します。渡されたテーブルの第一項目のみを確認します。

TEsound.findPitch

TEsound.findPitch(tag)

指定されたタグ(複数可)に対して音の高さの段階、またタグ(複数可)の音の高さが設定されていない場合は 1 を返します。

string tag
TEsound.findVolume を参照してください。

そのほかの言語