オーディオ link

Ren'Py は以下のフォーマットのファイルを使用したバックグラウンドでの音楽、効果音再生をサポートしています。 :

Opus
Ogg Vorbis
MP3
MP2
FLAC
WAV (非圧縮16bit PCM のみ)

ウェブブラウザ上では Ren'Py はオーディオフォーマットのリストをチェックし、ブラウザがそのリストの全てのモードをサポートしていればより早く、音飛びの少ないモードを有効化します。貴方のゲームが mp3 のみを使用し、 Safari で音飛びがあるなら config.webaudio_required_types の変更を考慮してください。

Ren'Py は任意の数のオーディオチャンネルをサポートしています。デフォルトでは 2 つのノーマルチャンネルが定義されています。 :

music - 音楽再生用チャンネル。
sound - サウンドエフェクト用チャンネル。

ノーマルチャンネルはオーディオの再生、キューに対応しますが、同時にひとつのオーディオファイルのみ再生します。新しいノーマルチャンネルは renpy.music.register_channel() で登録されます。

ゲーム内の設定画面の Music Volume, Sound Volume, Voice Volume を使用してそれぞれのチャンネルの個々のボリュームを設定できます。詳細は Volume を参照してください。

通常のチャンネルに加えて、2つの特別なチャンネルがあります。

audio - audio チャンネルは複数の音声ファイルの同時再生をサポートします。
一方音声のキューや再生停止はサポートしません。
voice - voice チャンネルは Ren'Py のボイスシステムによって使用されます。Ren'Pyは、キャラクターが話すと音声ファイルを自動で再生および停止し、 voice チャンネルの音量を調整できます。

サウンドはボタンや選択肢、イメージマップがホバーされる(その上にマウスが入る)かアクティベートされると再生するようにも設定出来ます。ボタンスタイルのプロパティーを参照してください。 2 つの設定変数 config.main_menu_music と config.game_menu_music はそれぞれ指定されたオーディオファイルをメインメニューとゲームメインメニューで再生するように出来ます。

ゲーム中に Ren'Py で曲と効果音を再生する通常の方法は 3 つの music/sound ステートメントを使用することです。音声ファイルは文字列として直接、またはオーディオ名前空間で定義された名前として指定できます。

audio ディレクトリーと名前空間 link

オーディオステートメントや関数で使用されるオーディオファイルを検索するとき、 Ren'Py は game ディレクトリー内から始めます。指定のファイルがそこに見つからなければ、 game/audio ディレクトリー内も見ます。例えば、

play music "opening.ogg"

上記のコードでは game/opening.ogg を探し、なければ game/audio/opening.ogg を探します。これはさらに深いサブディレクトリーに対しても同じです。

play music "my_music/opening.ogg"

上記のコードでは game/my_music/opening.ogg を探し、なければ game/audio/my_music/opening.ogg を探します。

game/audio ディレクトリーとその サブディレクトリー にあるファイルで、サポートされている拡張子 (現在は .wav, .mp2, .mp3, .ogg, .opus) で終わるものも、Ren'Py によって自動的にオーディオ名前空間に配置されます。つまり:file:game/audio/Town_theme.ogg が以下で再生できます

play music town_theme

使用可能な名前は、拡張子を取り除き、ファイル名の残りの部分を強制的に小文字にすることによって決定されます。これは、Python 変数として表現できる名前のオーディオファイルの場合のみです (例: my song.mp3, 8track.opus または this-is-a-song.ogg は機能しません。さらに、2 つ以上のファイルが同じ名前で定義される場合は、最初のファイル (パスとファイル名、拡張子を含むアルファベット順) のみが定義されます。

互換性のない名前や別のディレクトリ内にあるなどの理由で、ファイルがオーディオ名前空間に自動的に配置されない場合でも、define ステートメントを使用して手動で配置できます。

例えばこのように書いて

define audio.sunflower = "my_music/sun-flower-slow-jam.ogg"

このように使用します。

play music sunflower

play と queue ステートメントは常に audio 名前空間でその引数を評価しますが、関数はそうではありません。なので sunflower では動作しませんが、代わりに audio.sunflower では動作します。

　play ステートメント link

play ステートメントは曲や効果音を再生する最も一般的な方法です。ファイルが通常のノーマルチャンネルで再生中なら、停止して新しいファイルで置き換えます。

チャンネル名がキーワード play に続くことが期待されます ( 通常これは「sound 」、「 music 」「 voice 」「audio」のいずれかです) 。この後にはオーディオファイルかファイルのリストが続きます。リストが指定されるとその要素が順番に再生されます。

fadein と fadeout 節は任意です。 fadeout は現在再生中の曲をフェードアウトする時間を秒数で指定し、 fadein は新しい曲をフェードインするのにかかる時間を指定します。 fadeout が指定されていないと、 config.fadeout_audio が使用されます。

loop, noloop 節も任意です。 loop 節は曲をループし、 noloop 節は一度だけ再生します。両方とも指定されない場合はチャンネルのデフォルトが使用されます。

play music "mozart.ogg"
play sound "woof.mp3"
play myChannel "punch.wav" # 'myChannel' needs to be defined with renpy.music.register_channel().

"We can also play a list of sounds, or music."
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0

if_changed 節があり、指定されたトラックが現在そのチャンネルで再生中であれば、そのままにします。

label market_side:
    play music market
    "We're entering the market."
    jump market_main

label market_main:
    play music market if_changed
    "Maybe we just entered the market, maybe we were already there."
    "If we were already there, the music didn't stop and start over, it just continued."
    jump market_main

オプションの volume 節でそのトラックの相対振幅を 0.0から1.0で指定できます(訳注: 振幅は聴感上の音量とは比例しません)。これによりトラックが再生されるボリュームを再生時ごとに調整できます。

play sound "woof.mp3" volume 0.5

この auido チャンネルでは複数の play ステートメントで同時に複数のサウンドを再生します。

play audio "sfx1.opus"
play audio "sfx2.opus"

文字列の代わりに変数も指定でき、 audio 名前空間に変数があればデフォルトの名前空間に優先して使用されます。

play music illurock

audio 名前空間に配置されたファイルはこのように使用可能な変数を自動的に定義します。

Ren'Py は、オーディオファイルの再生を同時に開始する機能をサポートしています。この機能は、デフォルトではループするオーディオチャンネル( music など)で有効になっていますが、 synchro_start オプションを renpy.music.register_channel() または renpy.music.play() に設定しても有効にできます。

同期実行が有効のとき複数の play ステートメントを同時に実行すると、各チャネルのオーディオは同期して開始されます。具体的には、次の場合にオーディオが始まります。 :

すべてのチャンネルのオーディオファイルがロードされ、オーディオサンプルが利用可能な場合。
すべてのチャンネルがフェードアウトしたとき。

両方の条件が満たされると、新しいオーディオの再生が開始されます。

stop ステートメント link

stop ステートメントはキーワード stop で始まり、ストップするチャンネル名が続きます。任意で fadeout 節も持ち、 fadeout 節がなければ、 config.fadeout_audio が使用されます。

stop sound
stop music fadeout 1.0

queue ステートメント link

queue ステートメントを使用してオーディオファイルをキューします。それらはチャンネルが現在再生中のファイルを終了してから再生されます。

queue ステートメントはキーワード queue で始まり、再生するチャンネルの名前が続きます。任意で fadein, loop, noloop 節を受け取ります。

queue sound "woof.mp3"
queue music [ "a.ogg", "b.ogg" ]

キューは volume 節も受け取ります。

play sound "woof.mp3" volume 0.25
queue sound "woof.mp3" volume 0.5
queue sound "woof.mp3" volume 0.75
queue sound "woof.mp3" volume 1.0

複数の queue ステートメントがインタラクションなしで指定されると、すべての音声ファイルはそのキューに追加されます。play や stop ステートメントで既󠄂にクリアされていなければインタラクション後の最初の queue ステートメントはキューをクリアします。

文字列の代わりに変数も指定でき、 audio 名前空間に変数があればデフォルトの名前空間に優先して使用されます。

define audio.woof = "woof.mp3"

# ...

play sound woof

これらのステートメントを使用する利点は lint を実行時にオーディオファイルの消失をチェック出来ることです。以下の関数は曲と効果音を python から制御出来るようにし、( 滅多に使用されませんが )高度な機能を利用するために存在します。

部分再生 link

Ren'Py はオーディオファイルの部分的な再生をサポートします。このためにはファイルの始めの山括弧のなかで位置を指定します。部分再生指定は適切な名前と値のペアからなり、それぞれスペースで区切られます。

値はファイルの開始からの秒数と解釈され、3つのプロパティーがあります。 :

from: 最初に再生を開始するときの位置を指定します (デフォルトでは 0.0 秒)。
to: 最初に再生を停止する位置を指定します (デフォルトでは 0.0 秒)。
loop: 二回目からの再生開始位置を指定します (デフォルトでは from で指定された開始位置またはそのファイルの開始位置です )。

例

play music "<from 5 to 15.5>waves.opus"

5 秒から開始し、 waves.opus の10.5 秒までを再生します。

play music "<loop 6.333>song.opus"

song.opus 全体を一回再生した後、 6.333 秒からループします。

開始位置の同期 link

そのファイルの再生開始位置を、 "<sync channelname>track.opus" のようなファイル名を使用して現在再生中のトラックがある他のチャンネルに同期することもできます。ここでの channelname はそのチャンネルの名前で、 "music", "sound", その他登録されたチャンネルのいずれかになります。

これによって多層レイヤーのループトラックを一緒に同期できます。例

play music_2 [ "<sync music_1>layer_2.opus", "layer_2.opus" ]

これは後続のイテレーションでそのトラック全体を再生する前に、最初のイテレーションで music_1 チャンネルの現在のトラックと同期した開始時間で layer_2.opus を再生します(デフォルトでは layer_2.opus の開始時間はそのループの後続のイテレーションでも変更が維持されます)。

Volume link

指定したトラックが再生される音量はいくつかの変数に依存します。 :

"main" ミキサーボリューム
そのチャンネルに紐付けられたミキサーのボリューム
チャンネルのボリューム
そのトラック自体の相対的な振幅
そのファイル名に関連付けられた相対振幅

これら 4 つの音量は 0 から 1 の数値であり、掛け合わせた結果がそのトラックの再生音量になります。

例えば、メインボリュームが 80%(または 0.8)で、ミキサーボリュームが 100%(または 1.0)で、チャンネルボリュームが 50%(または 0.5)で、トラックの相対ボリュームが 25%(または 0.25)では結果のボリュームは .8*1.*.5*.25*.5 = .5 になり、 5%です。

これらのボリュームはすべて振幅ですが、 preferences メニューのミキサーはデシベルで表記されます。

preferences.set_mixer() や SetMixer() アクション、 "mixer <mixer> volume" を引数にした Preference() アクションを使用してミキサーのボリュームは設定できます。 "audio" と "sound" チャンネルは "sfx" ミキサーに "music" チャンネルは "music" ミキサーに、 "voice" チャンネルは "voice" ミキサーに紐付けられています。各チャンネルは上記のようにさらに "main" ミキサーにも紐付けられています。

チャンネルのボリュームは renpy.music.set_volume() を使用して設定できます。これは複数のチャンネルが同じミキサーを使用しているときのみ有用です。 renpy.music.register_channel() 関数の "mixier" パラメーターは登録するチャンネルに紐付けられるミキサーを設定し、それがまだなければ、作成します。

トラックの相対ボリュームは　play ステートメントの volume 節に設定されます。

あるファイル名の相対的なボリュームは、山括弧で囲まれた volume 節で設定されます(例: "<volume 0.5>track.opus")。

これらのボリューム値に加え、そのチャンネルが紐付けられたミキサーのミュートフラグもあり、有効なら再生音量は 0 まで低下します。それらは SetMute() や ToggleMute() アクション、 "mixer <mixer> mute" を引数にする Preference() アクション、 preferences.set_mute() 関数を使用して設定できます。

無音再生 link

3.0 秒の無音が欲しい場合、 "<silence 3.0>" のような名前のファイル名を使用して、指定された時間無音を再生できます。これにより再生位置を遅延できます。例

play audio [ "<silence .5>", "boom.opus" ]

0.5 秒の無音の後、爆発音を再生します。

Actions link

オーディオアクションを参照してください。

関数 link

class AudioData(data, filename) link

このクラスは音声や動画データを含むバイトオブジェクトをラップしてオーディオ再生システムで使用できるようにします。オーディオ/動画データは Ren'Py がサポートするフォーマットであるべきです(例修飾のないファイルではない RIFF WAV 形式のヘッダー)。

名前にもかかわらず、これはオーディオデータだけでなく動画データを表すために使用できます。

data

オーディオファイルを含む bytes オブジェクトです。

filename

このデータと関連付けられて合成されるファイル名です。これを使用して、 data を含むフォーマットを示したり、エラーメッセージのレポートで使用したりできます。

これが山括弧で始まる場合、オーディオに (from や to など) プロパティーを提供できます。

いったん作成されると、これはオーディオファイル名が求められるどこででも使用可能です。

define audio.easteregg = AudioData(b'...', 'sample.wav')
play sound easteregg

renpy.mark_audio_seen(filename) link: 指定したファイル名をすでに現在のユーザーに再生されているとマークします。

renpy.mark_audio_unseen(filename) link: 指定したファイル名が1 度も現在のユーザーに再生されていないとマークします。

renpy.play(filename, channel=None, **kwargs) link: 効果音を再生します。 channel が None なら、デフォルトで config.play_channel になります。これは hover_sound と activate_sound スタイルで定義されたサウンドを再生します。

renpy.seen_audio(filename) link: 指定したファイル名が 1 度でも現在のユーザーに再生されていれば True を返します。

renpy.music.channel_defined(channel) link: 指定されたチャンネルがあれば True を、なければ False を返します。

renpy.music.get_all_mixers() link: 使用中のすべてのミキサーを返します。

renpy.music.get_duration(channel='music') link: channel のオーディオやビデオファイルの長さを返します。ファイルが再生されていないか長さが不明ならば 0.0 を返します。いくつかのフォーマット、特に MP3 には Ren'Py がアクセス可能な形式で長さの情報がありません。

renpy.music.get_loop(channel='music') link: channel でループされているファイル名リスト、またはループされているファイルがなければ None を返します。ループはキューされているがまだ再生されていない場合、その現在再生中の音声ではなくそのループが返されます。

renpy.music.get_pause(channel='music') link: channel のポーズフラグを返します。

renpy.music.get_playing(channel='music') link: 指定されたチャンネルが再生中の場合、再生中のファイルの名前を返します。それ以外の場合は None を返します。

renpy.music.get_pos(channel='music') link

channel のオーディオやビデオの現在位置を秒数で返します。ファイルが再生されていなければ None を返します。

チャンネルが再生前であったり、ミュートにされると None を返すため、この関数を呼び出すコードは常に None を処理するべきです。

renpy.music.is_playing(channel='music') link: 指定されたチャンネルが再生中なら True を返します。再生中でないかサウンドシステムが動作していないなら False を返します。

renpy.music.play(filenames, channel='music', loop=None, fadeout=None, synchro_start=None, fadein=0, tight=None, if_changed=False, relative_volume=1.0) link

これは指定されたチャンネルで現在再生中の曲を停止し、キューされた曲をクリアし、指定されたファイルかファイルリストを再生開始します。

filenames

これは再生されるファイルかファイルのリストです。

channel

サウンドを再生するチャンネルです。

loop

これが True ならトラックはそれがキューの最後にある間ループを続けます。

fadeout

None を指定するか、フェードにかかる秒数を指定します。そうでなければフェードアウトの時間は config.fadeout_audio から所得されます。これはそのチャンネルが音声再生時にポーズされたときは無視されます。

synchro_start

When True, all channels that have synchro_start set to true will start playing at exactly the same time. This may lead to a pause before the channels start playing. This is useful when playing two audio files that are meant to be synchronized with each other.

None の場合、チャネルから値を取得します。

fadein

これは曲をフェードインするのにかかる秒数で、最初のループでのみ有効です。

tight

True ならフェードアウトは次にキューされるサウンドにも適用されます。None なら loop が True のとき True になり、そうでなければ False です。

if_changed

これが True であり、かつ指定したオーディオファイルが現在再生中なら、停止やフェードアウトも再び最初から再生もせずに再生を継続します ( これは常にそのオーディオファイルをキューに追加します )。

relative_volume

これは現在のチャンネルボリュームに対する相対ボリュームです。指定のファイルがその相対ボリュームで再生されます。指定されなければデフォルトは 1.0で、ミキサーとチャンネル、セカンドボリュームで決まる元の音量で再生します。

channel のポーズフラグをクリアします。

renpy.music.pump() link

これはオーディオシステムを '押しだし'ます。通常 play や queue, stop ステートメントや相当する関数の効果は次のインタラクション開始時に始まります。しかしいくつかの場合では、複数のステートメントが互いを打ち消します。例えば play に続いて stop が来るとそのトラックは全く再生されません。

この関数がその play と stop 間で呼び出されると、この関数から処理が返る前にそのトラックが再生され始めるのでトラックがフェードアウトできるようになります。

play music "mytrack.opus"
$ renpy.music.pump()
stop music fadeout 4

renpy.music.queue(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None, relative_volume=1.0) link

指定されたファイルを特定のチャンネルにキューします。

filenames: これは再生されるファイルかファイルのリストです。
channel: サウンドを再生するチャンネルです。
loop: これが True ならトラックはそれがキューの最後にある間ループを続けます。
clear_queue: True なら現在の再生が終了するとキューがクリアされると共にこれらのファイルが再生されます。 False ならこれらのファイルはキューの末尾に配置されます。どちらの場合でも音楽が再生されていなければこれらのファイルは即座に再生開始します。
fadein: これは曲をフェードインするのにかかる秒数で、最初のループでのみ有効です。
tight: True ならフェードアウトは次にキューされるサウンドにも適用されます。None なら loop が True のとき True になり、そうでなければ False です。
relative_volume: これは現在のチャンネルボリュームに対する相対ボリュームです。指定のファイルがその相対ボリュームで再生されます。指定されなければデフォルトは 1.0で、ミキサーとチャンネル、セカンドボリュームで決まる元の音量で再生します。

channel のポーズフラグをクリアします。

renpy.music.register_channel(name, mixer, loop=None, stop_on_mute=True, tight=False, file_prefix='', file_suffix='', buffer_queue=True, movie=False, framedrop=True) link

name と名付けられた新しいオーディオチャンネルを登録します。そのチャンネルの名前を play または queue ステートメントに与えると、オーディオはそのチャンネルで再生されます。

name: チャンネル名です。これは Ren'py 内部での使用に予約されるため、スペースは含まず、　play ステートメントのシンタックスで使用できる妥当な識別子であるべきです。
mixer: チャンネルが使用するミキサーの名前です。デフォルトで Ren'Py には「 music 」,「 sfx 」,「 voice 」ミキサーが設定されています。他の名前の使用も可能であり、そのミキサーがなければ作成しますが、プレイヤーがチャンネルを設定できるよう設定画面の変更も必要かもしれません。
loop: True または None の場合、このチャンネルのサウンドはデフォルトでループします。False の場合、このチャネルのサウンドは既定ではループしません。
stop_on_mute: True の場合、このチャンネルの曲はチャンネルがミュートになったら停止します。
tight: True の場合、サウンドはフェードアウト中でもループします。これは、サウンドエフェクトやシームレスなミュージックチャンネルに対して True に、曲がそれ自身でフェードアウトする場合は False に設定すべきです。
file_prefix: このチャンネルで再生される曲のファイル名につけられる接頭辞。
file_suffix: このチャンネルで再生される曲のファイル名につけられる接尾辞。
buffer_queue: キューに入れたファイルの最初の数秒をメモリに展開しますか？これはオーディオに対しては True 、ムービーに対しては False にすべきです。
movie: True ならこのチャンネルはビデオ再生用に設定されます。
framedrop: これはラグ発生時にビデオをどうするかを制御します。 True なら、いくらかのフレームを落として実時間と音声トラックに追随します。False なら、Ren'Py はフレームを飛ばさず、遅れて表示します。
synchro_start: このチャンネルは同期実行に参加しますか?同期実行は、そのチャンネルが他のチャンネルと同時に再生を開始するかどうかを決定します。 None の場合、 movie が False なら、デフォルトは loop であり、それ以外の場合は False です。

renpy.music.set_audio_filter(channel, audio_filter, replace=False, duration=0.016) link

キューに入れられるサウンドのオーディオフィルターを audio_filter に設定します。

audio_filter: オーディオフィルターまたはオーディオフィルターのリストであるべきです。 None にしてオーディオフィルターを削除もできます。
replace: True なら、オーディオフィルターは現在のオーディオフィルターをすぐに置き換え、現在再生中のサウンドとキューに入れられたサウンドを変更します。False なら、オーディオフィルターは、次にサウンドが再生またはキューに入れられるときに使用されます。
duration: 現在のフィルターから新しいフィルターに変更する時間 (秒単位)です。これにより、フィルター交換時のポップ音を防止します。

renpy.music.set_mixer(channel, mixer, default=False) link

これにより、特定のチャンネルに関連付けられたミキサーの名前を設定します。デフォルトでは、「sfx」と「music」の2つのミキサーがあります。「sfx」はチャンネル0〜3にあり、「music」は3〜7にあります。 voice モジュールは、この関数を呼び出して、チャネル 2 を voice に設定します。独自のミキサーを作成できますが、ユーザーが設定できるようにする場合は、 preference を追加する必要があります。

この関数は初期化ブロックでのみ呼び出されるべきです。

renpy.music.set_pan(pan, delay, channel='music') link

このチャンネルのパンを設定します。

pan: 音源の位置を制御する -1 から 1 までの間の数字です。これが -1 だと全ての音は左側のチャンネルに送られ、 0 だと 2 つのチャンネルは等しくなります。 1 なら全ての音は右側に送られます。
delay: パンの実行に掛ける時間です。
channel: パンを実行するチャンネルです。デフォルトでは music チャンネルです。

renpy.music.set_pause(value, channel='music') link: channel のポーズフラグを value に設定します。 True なら、チャンネルはポーズし、そうでなければ通常どおり再生します。

renpy.music.set_queue_empty_callback(callback, channel='music') link

これはキューが空になったときに呼び出されるコールバックを設定します。このコールバックはキューが最初に空になったときとキューが空になっている間のインタラクション毎に少なくとも 1 回呼び出されます。

コールバックはパラメーターなしで呼び出されます。これは適切な引数で renpy.music.queue を呼び出して曲をキューに追加出来ます。コールバックはキューが空である限り曲が再生されている間も呼び出されることに注意してください。

renpy.music.set_volume(volume, delay=0, channel='music') link

このチャンネルの音量を、チャンネルを制御するミキサーの音量の割合で設定します。

volume: これは 0.0 と 1.0 の間の数字で、そのチャンネルのミキサーボリュームの割合として解釈されます。
delay: 以前の値から新しい値に音量を変更するのに delay 秒掛かります。この値はセーブに保存され、ロールバックにも参加します。
channel: 設定されるチャンネルです。

renpy.music.stop(channel='music', fadeout=None) link

これは現在再生中の曲を停止して、キューに追加された全ての曲をキューから消します。 fadeout が None なら曲は config.fadeout_audio で指定された時間でフェードアウトします。そうでなければ fadeout 秒でフェードアウトします。

これは最後にキューされたファイルを None に設定します。

channel: 再生を停止するチャンネル
fadeout: None を指定するか、フェードにかかる秒数を指定します。そうでなければフェードアウトの時間は config.fadeout_audio から所得されます。これはそのチャンネルがポーズされていれば無視されます。

サウンドの関数 link

ほとんどの renpy.music 関数は renpy.sound にエイリアスを持ちます。これらの関数はデフォルトが music チャンネルではなく sound チャンネルに設定されており、ループしないことを除いて同じものです。