音訊 link

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

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

在Web瀏覽器上，Ren’Py會檢查一個音訊格式列表，並根據瀏覽器支持的格式啟用一個更快更少卡頓的模式。如果你的遊戲只是用mp3，而且不考慮Safari瀏覽器，可以直接修改 config.webaudio_required_types 的值。

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語句 link

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

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

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'需要先使用renpy.music.register_channel()定義。

"我們也可以播放一個音效或音樂的列表。"
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0

當提供了 if_changed 從句，並且對應的音訊通道正在播放，播放指令不會中斷當前播放的音訊。

label market_side:
    play music market
    "我們正在進入市場。"
    jump market_main

label market_main:
    play music market if_changed
    "我們可能剛進入市場，也可能已經在市場裡一段時間了。"
    "如果我們已經在市場裡一段時間了，音樂不會停止並重從播放，只是繼續播放。"
    jump market_main

volume 從句也是可選的，可以指定音量值，音量範圍為0.0到1.0。這樣每次指定音訊檔案時，也可以同時設置音量。

play sound "woof.mp3" volume 0.5

在audio通道上，同時播放多個音效文件：

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

此處可以使用變數替代字串。如果某個變數在音訊命名空間中存在，它就可以在預設的命名空間中直接引用。

play music illurock

放入audio命名空間的文件會根據檔案名自動定義變數並使用。

stop語句 link

stop語句以關鍵字 stop 開頭，後面跟需要靜音的音訊通道名。最後有一個可選的 fadeout 分句。如果沒有fadeout時間沒有指定，就使用 config.fadeout_audio 的配置值。

stop sound
stop music fadeout 1.0

queue語句 link

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語句清空過。

此處可以使用變數替代字串。如果某個變數在音訊命名空間中存在，它就可以在預設的命名空間中直接引用：

define audio.woof = "woof.mp3"

# ...

play sound woof

使用這些語句的優點是，當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

播放音訊時的音量與以下變數都有關：

混音器“main”的音量值
相關音訊通道的混音器音量值
音訊通道的音量值
音訊自身音量

以上4項音量值都介於0與1之間，最終音量值是它們相乘後的結果。

例如，main音量值80%(0.8)，混音器音量值100%，音訊通道音量值50%(0.5)，音訊自身音量25%(0.25)。最終音量為 .8*1.*.5*.25 = .1，即10% 。

混音器音量可以使用 preferences.set_mixer() 函數、SetMixer() 行為和 Preference() 行為指定 "mixer <mixer> volume" 進行設置。 audio和sound音訊通道相關的混音器為“sfx”，music音訊通道相關的混音器為“music”，而voice音訊通道相關的混音器為“voice”。每個音訊通道都與“main”混音器相關。

使用 renpy.music.set_volume() 函數可以設置某個音訊通道的音量。通常僅當多個音訊通道共用同一混音器時才需要用。 renpy.music.register_channel() 函數的 mixer 參數可以在註冊音訊通道時指定關聯的混音器，如果混音器不存在則直接創建一個。

在 play語句後面加 volume 從句可以直接設置音訊檔案的相對音量。

除了音量值，各音訊通道關聯的混音器都有靜音標識。啟用靜音標識後，會將音量直接設置為0. 可以使用 SetMute()、ToggleMute()、Preference() 或 preferences.set_mute()，指定“mixer <mixer> mute”啟用對應混音器的靜音標識。

播放靜音 link

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

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

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

音訊命名空間和目錄 link

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”就有這種情況。

Ren’Py搜索音訊檔案時，如果在game目錄中沒有對應的匹配文件，會再次在audio目錄中尋找。例如：

play music "opening.ogg"

Will first look for game/opening.ogg. If not found, Ren’Py will look for game/audio/opening.ogg. 會先尋找 game/opening.ogg。若未果則會尋找 game/audio/opening.ogg 。

行為函數 link

詳見音訊行為。

相關函數 link

AudioData(data, filename) link

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

data: 包含音訊檔案數據的byte編碼對象。
filename: 與音訊數據相關的複合檔案名。它可以表示音訊數據格式，也可以用做報錯資訊。

renpy.mark_audio_seen(filename) link: 將指定檔案名的文件標記為當前用戶已播放過至少一次。

renpy.mark_audio_unseen(filename) link: 將指定檔案名的文件標記為當前用戶未播放過。

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='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，當前真在播放的音訊不會被立刻停止/淡出，而會繼續播放。
relative_volume: 當前音訊通道播放音訊時的相對音量值。指定文件將以該音量值播放。如果沒有指定該音量值則預設為1.0，表示以音訊檔案原始音量播放，再乘以混音器、音訊通道和相關第二音量的值。

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

renpy.music.pump() link

“pump”是指對音訊系統的操作。通常來說，使用 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) link

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

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

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

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，該通道會被設為播放影片。
framedrop: 該參數控制影片卡頓時的處理方式。若為True，則會跳幀以保持影音同步。若為False，Ren’Py會無視影片遲延。

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)通道，且默認不循環播放。