Ren’Py支持在後台播放音樂和音效,支持的音訊檔案格式如下:
Opus和Ogg Vorbis格式可能不被某些基於WebKit的瀏覽器(比如Safari),但對氣態平台來說是最好的選擇。
Ren’Py支持任意數量的音訊通道。有三種一般音訊通道是默認定義好的:
music
- 音樂播放通道。sound
- 音效播放通道。voice
- 語音播放通道。通用通道支持音訊的播放和音訊隊列,但同一時間只能播放1個音訊檔案。可以使用
renpy.music.register_channel()
函數註冊新的通用通道。
遊戲內自訂配置菜單中的“音樂音量”、“音效音量”和“語音音量”設置的值,會應用於以上對應的音訊通道。
另外,除了通用通道,還存在特殊音訊通道 audio
。audio通道支持同時播放多個音訊檔案,但不支持隊列播放和中途停止。
音效的用途,包括按鈕(button)、菜單選項、圖片地圖(imagemap)的滑鼠懸停和啟動狀態。詳見
按鈕樣式屬性. 兩個配置項, config.main_menu_music
和 config.game_menu_music
,分別對應主選單和遊戲菜單播放的音樂。
遊戲內播放音樂和音效的常用辦法,是使用Ren’Py的三種音樂/音效語句。
play
語句用於播放音效和音樂。如果某個文件正在透過通用通道播放,播放會被中斷,並開始播放新的文件。
音訊通道名(通常就是“sound”、“music”、“voice”或者“audio”)需要跟在關鍵字 play
後面。通道名後面是音訊檔案。音訊檔案可以是單個文件,也可以是文件列表。如果是文件列表的話,列表內元素順序播放。
fadein
和 fadeout
分句是可選的。 fadeout指定了正在播放音樂需要停止時的淡出時間,單位為秒。fadein指定了播放新音樂的開頭淡入時間。如果沒有fadeout時間沒有指定,就使用 config.fade_music
的配置值。
loop
和 noloop
分句也是可選的。 loop分句表示音樂循環播放,noloop分句表示音樂只播放一次。如果這兩個分句都沒有出現,根據通道的默認配置決定實際播放情況。
play music "mozart.ogg"
play sound "woof.mp3"
play myChannel "punch.wav" # 'myChannel'需要先使用renpy.music.register_channel()定義。
"我們也可以播放一個音效或音樂的列表。"
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0
在audio通道上,同時播放多個音效文件:
play audio "sfx1.opus"
play audio "sfx2.opus"
此處可以使用變數替代字串。如果某個變數在 音訊命名空間 中存在,它就可以在預設的命名空間中直接引用。
play music illurock
Files placed into the audio namespace may automatically define variables that can be used like this.
queue
語句用於組建音訊檔案隊列。當前播放的文件被播放完畢之後,queue語句組建的音訊檔案隊列就會開始播放。
queue語句以關鍵字 queue
開頭,後面跟播放使用的音訊通道名。最後是否帶 fadein
、 loop
或 noloop
分句是可選的。
queue sound "woof.mp3"
queue music [ "a.ogg", "b.ogg" ]
queue語句也可以使用 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語句出現,且沒有給任何隊列指定互動行為情況下,所有的聲音文件都將加入到隊列中。 在某個互動行為發生後,第一個queue語句對應的隊列將清空,除非其已經被某個play或stop語句清空過。
此處可以使用變數替代字串。如果某個變數在 音訊命名空間 中存在,它就可以在預設的命名空間中直接引用。
使用這些語句的優點是,當lint工具運行時,可以檢測出你程序中是否有遺失的音樂音效文件。後面的一些函數允許python接入和控制這些文件,並且會揭示一些高級(卻很少用到)的特性。
Ren’Py支持節選播放音訊檔案。節選播放的語法是,在play語句的檔案名之前,加上用英文角括號<>包含的播放起始點。節選播放規範應該包含成對屬性名和屬性值,並用空格分隔。
屬性值以秒為單位,集成在檔案名前面的英文角括號<>內。三種屬性名分別為:
from
to
loop
from
指定的時間點。)舉例:
play music "<from 5 to 15.5>waves.opus"
將從5秒的標記處開始,播放總計10.5秒waves.opus文件內容。下面這條語句:
play music "<loop 6.333>song.opus"
將會在完整播放完文件song.opus後,回到6.333秒標記處重新播放至結尾,並不斷循環重複。
某段音訊音訊的起始播放位置可以同步到另一個音訊通道,只需要使用特定的檔案名,比如“<sync channelname>track.opus”。 其中channelname就是需要同步的通道名稱,可以是music、sound或其他任意註冊過的音訊通道。
該功能可用於多個循環播放音軌的同步。比如:
play music_2 [ "<sync music_1>layer_2.opus", "layer_2.opus" ]
layer_2.opus播放時將會與music_1通道的循環保持同步,即music_1從頭開始播放時也跟隨從頭播放,而不再會播放完之後再循環。
一段指定時間範圍播放靜音,格式類似“<silence 3.0>”,其中3.0表示需要的靜音持續時間,單位為秒。播放靜音用於延遲音效文件的播放點。例如:
play audio [ "<silence .5>", "boom.opus" ]
將播放半秒的靜音,然後出現一個爆炸音效。
play
和 queue
語句在音訊命名空間內計算入參的值。這意味著可以使用define語句,為音訊檔案提供一個別名(alias)。
例如,我們可以這樣寫:
define audio.sunflower = "music/sun-flower-slow-jam.ogg"
然後這樣使用:
play music sunflower
Ren’Py會將 game/audio
目錄下的文件自動識別為音訊檔案,並根據檔案名在audio命名空間中生成對應變數。
該目錄下直接支持的幾種音訊音訊,會被去掉文件副檔名(當前包括.wav、.mp2、.mp3、.ogg和.opus),剩下的檔案名強制轉為小寫字母,並放入audio命名空間。
需要注意,檔案名會放入audio命名空間並不表示就會播放。如果需要播放一個名為“opening_song.ogg”文件,需要寫:
play music opening_song
某些檔案名無法使用這種方式,因為這些檔案名不符合Python變數命名規範。例如,“my song.mp3”、“8track.opus”和“this-is-a-song.ogg”就有這種情況。
AudioData
(data, filename) link該類會指向一個byte編碼對象,包含音訊數據。該對象可以傳入音訊播放系統。包含的音訊數據應該是Ren’Py支持的格式(例如RIFF、WAV格式)。
renpy.
play
(filename, channel=None, **kwargs) link播放一個音效。如果channel為None,預設值為config.play_channel。該函數用在各種樣式(style)定義,滑鼠懸停聲(hover_sound)和啟動聲(activate_sound)。
renpy.
seen_audio
(filename) link如果filename對應的音訊檔案在用戶系統中至少被播放過一次,則返回True。
renpy.music.
get_duration
(channel='music') link返回目前 channel 通道上正在播放的音訊或影片檔案的全長。若 channel 通道上沒有正在播放的文件,則返回0.0。
renpy.music.
get_loop
(channel=u'music') link返回音訊通道上正在循環播放的文件列表,如果沒有文件在循環播放則返回None。 如果循環列表還在待播放隊列中排隊,並沒有播放,依然會返回循環列表,而不是正在播放的音樂。
renpy.music.
get_pause
(channel='music') link返回 channel 通道上的pause標記的值。
renpy.music.
get_playing
(channel='music') link若入參channel上有音訊正在播放,返回檔案名。否則返回None。
renpy.music.
get_pos
(channel='music') link返回入參channel通道上正在播放的音訊或者影片檔案的已播放進度,單位為秒。如果 channel 通道上沒有任何音訊或影片檔案正在播放,返回None。
由於在某個通道開始播放前,總是會返回None;也可能對應的音訊通道已經被靜音(mute)。該函數的調用者應該能夠處理空值。
renpy.music.
is_playing
(channel='music') link若入參channel上正在播放一個音訊則返回True,否則返回False。或者當聲音系統沒有工作的情況也返回False。
renpy.music.
play
(filenames, channel='music', loop=None, fadeout=None, synchro_start=False, fadein=0, tight=None, if_changed=False) link該函數會立即停止入參channel上正在播放的聲音,解散音訊隊列,並開始播放入參filenames指定的文件。
該函數會清空對應通道上所有的pause標記。
renpy.music.
queue
(filenames, channel='music', loop=None, clear_queue=True, fadein=0, tight=None) link該函數將檔案名為filenames的文件加入指定通道channel的播放隊列。
該函數會清空對應通道上所有的pause標記。
renpy.music.
register_channel
(name, mixer=None, loop=None, stop_on_mute=True, tight=False, file_prefix='', file_suffix='', buffer_queue=True, movie=False) link該函數用於註冊新的名為入參name的音訊通道。之後就可以使用play或queue語句在name通道上播放音訊了。
renpy.music.
set_pan
(pan, delay, channel='music') link設置該通道的聲像(pan)。
renpy.music.
set_pause
(value, channel='music') link將入參value賦值給通道名為channel的暫停標識。若value為True,通道會被暫停,否則正常播放。
renpy.music.
set_queue_empty_callback
(callback, channel='music') link該函數設置了一個callback函數,當播放隊列為空時,將會調用callback函數。播放隊列首次變空時callback函數將被調用,且每次會導致播放隊列清空的互動行為都會至少調用一次。
callback函數被調用時不帶任何參數。其會使用合適的參數調用renpy.music.queue,將聲音組件成一個隊列。請注意,某個聲音在播放時callback就可能會被調用,因為當時待播放隊列已經空了。
renpy.music.
set_volume
(volume, delay=0, channel='music') link設置通道的音量volume。對於控制多個通道的混合器(mixer),該值表示混合器的一個音量分量。 Sets the volume of this channel, as a fraction of the volume of the mixer controlling the channel.
renpy.music.
stop
(channel='music', fadeout=None) link該函數停止正在播放的音樂,並解散播放隊列。如果入參fadeout為None,使用config.fade_music配置值作為淡出效果時間,否則就是用fadeout入參值。
該函數將最後組建的待播放文件列表設置為None。
大多數 renpy.music
函數在 renpy.sound
有別名(alias)。這些函數功能類似,主要差別在於它們默認作用於音效(sound)通道而不是音樂(music)通道,且默認不循環播放。