音訊 link

Ren’Py支持在後台播放音樂和音效,支持的音訊檔案格式如下:

  • Opus
  • Ogg Vorbis
  • MP3
  • WAV (未壓縮的有符號16bit型PCM編碼格式)

Opus和Ogg Vorbis格式可能不被某些基於WebKit的瀏覽器(比如Safari),但對氣態平台來說是最好的選擇。

Ren’Py支持任意數量的音訊通道。有三種一般音訊通道是默認定義好的:

  • music - 音樂播放通道。
  • sound - 音效播放通道。
  • voice - 語音播放通道。

通用通道支持音訊的播放和音訊隊列,但同一時間只能播放1個音訊檔案。可以使用 renpy.music.register_channel() 函數註冊新的通用通道。

遊戲內自訂配置菜單中的“音樂音量”、“音效音量”和“語音音量”設置的值,會應用於以上對應的音訊通道。

另外,除了通用通道,還存在特殊音訊通道 audio 。audio通道支持同時播放多個音訊檔案,但不支持隊列播放和中途停止。

音效的用途,包括按鈕(button)、菜單選項、圖片地圖(imagemap)的滑鼠懸停和啟動狀態。詳見 按鈕樣式屬性. 兩個配置項, config.main_menu_musicconfig.game_menu_music ,分別對應主選單和遊戲菜單播放的音樂。

遊戲內播放音樂和音效的常用辦法,是使用Ren’Py的三種音樂/音效語句。

play語句 link

play 語句用於播放音效和音樂。如果某個文件正在透過通用通道播放,播放會被中斷,並開始播放新的文件。

音訊通道名(通常就是“sound”、“music”、“voice”或者“audio”)需要跟在關鍵字 play 後面。通道名後面是音訊檔案。音訊檔案可以是單個文件,也可以是文件列表。如果是文件列表的話,列表內元素順序播放。

fadeinfadeout 分句是可選的。 fadeout指定了正在播放音樂需要停止時的淡出時間,單位為秒。fadein指定了播放新音樂的開頭淡入時間。如果沒有fadeout時間沒有指定,就使用 config.fade_music 的配置值。

loopnoloop 分句也是可選的。 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.

stop語句 link

stop語句以關鍵字 stop 開頭,後面跟需要靜音的音訊通道名。最後有一個可選的 fadeout 分句。

stop sound
stop music fadeout 1.0

queue語句 link

queue 語句用於組建音訊檔案隊列。當前播放的文件被播放完畢之後,queue語句組建的音訊檔案隊列就會開始播放。

queue語句以關鍵字 queue 開頭,後面跟播放使用的音訊通道名。最後是否帶 fadeinloopnoloop 分句是可選的。

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接入和控制這些文件,並且會揭示一些高級(卻很少用到)的特性。

節選播放 link

Ren’Py支持節選播放音訊檔案。節選播放的語法是,在play語句的檔案名之前,加上用英文角括號<>包含的播放起始點。節選播放規範應該包含成對屬性名和屬性值,並用空格分隔。

屬性值以秒為單位,集成在檔案名前面的英文角括號<>內。三種屬性名分別為:

from
指定播放文件的起始時間點。(預設值為0.0秒)
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秒標記處重新播放至結尾,並不斷循環重複。

同步起始位置 link

某段音訊音訊的起始播放位置可以同步到另一個音訊通道,只需要使用特定的檔案名,比如“<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從頭開始播放時也跟隨從頭播放,而不再會播放完之後再循環。

播放靜音 link

一段指定時間範圍播放靜音,格式類似“<silence 3.0>”,其中3.0表示需要的靜音持續時間,單位為秒。播放靜音用於延遲音效文件的播放點。例如:

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

將播放半秒的靜音,然後出現一個爆炸音效。

音訊命名空間 link

playqueue 語句在音訊命名空間內計算入參的值。這意味著可以使用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”就有這種情況。

相關函數 link

AudioData(data, filename) link

該類會指向一個byte編碼對象,包含音訊數據。該對象可以傳入音訊播放系統。包含的音訊數據應該是Ren’Py支持的格式(例如RIFF、WAV格式)。

data
包含音訊檔案數據的byte編碼對象。
filename
與音訊數據相關的複合檔案名。它可以表示音訊數據格式,也可以用做報錯訊息。
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指定的文件。

filenames
該值可以是單個文件,也可以是待播放的文件列表。
channel
播放聲音使用的通道。
loop
若該值為True,音軌會循環播放,前提是其已經是播放隊列最後一個音訊。
fadeout
若不為空,這是一個淡出效果的持續時間,單位為秒。否則,淡出時間使用config.fade_music的值。
synchro_start
Ren’Py會確保所有synchro_start標誌為True的通道,能夠在幾乎同一時間一齊開始播放音訊。當我們需要兩個音訊檔案相互同步時,synchro_start就應該被設置為True。
fadein
音訊開始淡入效果持續時間,單位為秒,在循環播放時僅對第一遍播放有效。
tight
若該值為True,淡出效果將作用至同一個隊列中後面的聲音。若為空,當loop為True時tight也為True,否則為False。
if_changed
若該值為True,當前真在播放的音訊不會被立刻停止/淡出,而會繼續播放。

該函數會清空對應通道上所有的pause標記。

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

該函數將檔案名為filenames的文件加入指定通道channel的播放隊列。

filenames
該值可以是單個文件,也可以是待播放的文件列表。
channel
播放聲音使用的通道。
loop
若該值為True,音軌會循環播放,前提是其已經是播放隊列最後一個音訊。
clear_queue
若為True,當前播放文件結束後,播放隊列中原有文件將被清空。若為False,新增文件會被加在原有隊列結尾。無論實際哪種情況,如果當前沒有任何音訊正在播放,新隊列中的音訊都會立刻被播放。
fadein
音訊開始淡入效果持續時間,單位為秒,在循環播放時僅對第一遍播放有效。
tight
若該值為True,淡出效果將作用至同一個隊列中後面的聲音。若為空,當loop為True時tight也為True,否則為False。

該函數會清空對應通道上所有的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通道上播放音訊了。

mixer
混合器(mixer)使用的通道名。默認情況下,Ren’Py能識別“music”、“sfx”和“voice”混合器。使用其他名稱也是可行的,不過可能要修改個性化界面。
loop
若為True,在新註冊通道上的音訊默認循環播放。
stop_on_mute
若為True,當新註冊通道被靜音(mute)時,通道上所有音訊都會停止播放。
tight
若為True,即使有淡出效果,依然可以循環播放。若要實現音效、音樂的無縫連接,就應該把這項設為True。若使用音樂的淡出效果則設置為False。
file_prefix
在該通道上播放的所有聲音文件都會添加的檔案名前綴。
file_suffix
在該通道上播放的所有聲音文件都會添加的檔案名後綴。
buffer_queue
我們是否應快取一兩個文件或者一個文件隊列?如果通道是播放音訊的話應該設置為True,如果播放影片的話應該設置為False。
movie
若值為True,該通道會被設為播放影片。
renpy.music.set_pan(pan, delay, channel='music') link

設置該通道的聲像(pan)。

pan
控制音訊的音源位置的一個值,位於-1至1的閉區間內。若該值為-1,所有音訊使用左聲道。若該值為0,左右聲道均衡發聲。若該值為1,所有音訊使用右聲道。
delay
為了形成聲像使用的延遲時間。
channel
應用聲像的通道名。可以是音樂或音效通道。通常使用通道7,也就是預設的音樂通道。
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.

volume
該值位於0.0至1.0的閉合區間。對於控制多個通道的混合器(mixer),該值表示混合器的一個音量分量。
delay
該值代表一個時間量,用於新舊音量值切換/平滑過渡時的時延,單位為秒。該值會保存在存檔中,並接受回滾操作。
channel
需要設置的通道名。
renpy.music.stop(channel='music', fadeout=None) link

該函數停止正在播放的音樂,並解散播放隊列。如果入參fadeout為None,使用config.fade_music配置值作為淡出效果時間,否則就是用fadeout入參值。

該函數將最後組建的待播放文件列表設置為None。

channel
需要停止播放的通道名。
fadeout
若不為None,包含一個淡出效果時間,單位為秒。否則淡出時間取決於config.fade_music。

音效函數 link

大多數 renpy.music 函數在 renpy.sound 有別名(alias)。這些函數功能類似,主要差別在於它們默認作用於音效(sound)通道而不是音樂(music)通道,且默認不循環播放。