音訊濾波器

音訊濾波器可以在遊戲中更改音訊通道上的聲音。常用於給聲音添加效果，包括混響、延遲/回聲、高通/低通濾波等。

音訊濾波器位於 renpy.audio.filter 模組。 不是嚴格要求，只是推薦引用該模組時使用一個簡短的別名，比如 af：

define af = renpy.audio.filter

可以調用 renpy.music.set_audio_filter() 函數設置想用的音訊濾波器：

$ renpy.music.set_audio_filter("music", af.Reverb(0.5))

默認情況下，音訊濾波器設置之後會在下一個播放的音訊檔案時生效。 如果想要立刻生效，可以使用 replace 參數：

$ renpy.music.set_audio_filter("music", af.Lowpass(440), replace=True)

這樣就能讓音訊盡可能快地應用新的濾波器。

最後，創作者可以傳入None來清除所有濾波器效果：

$ renpy.music.set_audio_filter("music", None)

(也可以使用None搭配 replace 來立刻清除所有濾波器效果。)

濾波器復用

在某個音訊通道設置濾波器後，在該通道播放的所有音訊都會受到濾波器的影響。 特別是梳狀濾波器(comb filter)、延遲濾波器和混響濾波器，會根據舊音訊產生一些輸出結果， 對新播放的音訊產生影響。

Ren’Py會在濾波器對象中保留一些音訊資訊。因此，在不同音訊通道間共用濾波器不是個好主意。 在單個音訊通道裡多次使用同一個濾波器對象也不行。

靜音銜接

當啟用音訊濾波器後，對應音訊通道切換播放的音訊內容時，Ren’Py會在該通道添加2秒的靜音， 以確保延遲、混響等濾波器能完整播放。

如果需要更久的靜音，可以在播放隊列中設置：

queue sound "<silence 10">

多個音訊濾波器

除了使用單個濾波器，我們還可以使用一個濾波器列表，即一個 renpy.audio.filter.Sequence 對象：

renpy.music.set_audio_filter("music", [af.Reverb(0.5), af.Lowpass(440)])

也等效於：

renpy.music.set_audio_filter("music",
    af.Sequence([
        af.Reverb(0.5),
        af.Lowpass(440),
        ]))

除此之外，也可以用多個音訊濾波器組成下列類的對象。 出於性能考慮，現在不能自訂濾波器類。

renpy.audio.filter.Allpass(frequency=350, q=1.0)

全通濾波器，可以允許所有頻率通過，但會更改各頻率間的相位關係。

frequency

相位變化的中心頻率。

q

控制相位移動(phase shift)的形狀。該數值越大，相位移動的形狀約尖銳。

renpy.audio.filter.Bandpass(frequency=350, q=1.0)

帶通濾波器。

frequency

中心頻率。

q

該值控制頻帶寬度。當q的值減少後，頻帶會變窄。

class renpy.audio.filter.Comb(delay, filter=None, multiplier=1.0, wet=True)

梳狀濾波器類。梳狀濾波器由一些多次延遲效果疊加並混合輸出，並將輸出進一步回饋回延遲，最終會疊加多次。

(譯者註：中文網路上大多數關於梳狀濾波器的說明都是扯淡。 “梳狀”來源於該濾波器的 頻域 特性曲線有明顯的週期性峰谷，類似梳子，可以產生回聲效果。 其他幾種濾波器，比如“高通”、“低通”、“帶通”、“全通”都指濾波器的 頻域 特性。)

delay

延遲時間，單位為秒。如果該參數是一個列表，則各個子通道的延遲分別對應列表中具有相同索引的元素。 延遲時間最小為0.01秒。

filter

對延遲之後的信號應用的濾波器。若為None，則使用Null濾波器。

multiplier

對濾波之後信號的乘數。

wet

若為True，濾波器輸出結果包含，輸入信號、濾波後信號和計算乘數後的信號。 若為False，濾波器輸出結果僅包含，濾波後信號和計算乘數後的信號。

class renpy.audio.filter.Delay(delay)

該濾波器實現了一度時間的延遲輸出。從輸入端採樣得到的結果，會在延遲 delay 秒之後再輸出。

delay

延遲時間，單位為秒。如果該參數是一個列表，則各個子通道的延遲分別對應列表中具有相同索引的元素。 延遲時間最小為0.01秒。

renpy.audio.filter.Highpass(frequency=350, q=1.0)

高通濾波器。低於閾值的頻率每低一個八度(頻率減半)就會有12/dB的衰減。

frequency

閾值頻率。

q

以分貝形式控制結果的峰值。在該類濾波器中，q值並非傳統的Q值(品質參數)，而是一個轉化為分貝的共振結果。

renpy.audio.filter.Highshelf(frequency=350, gain=0)

highshelf濾波器，可以讓所有頻率通過，但會增強高於某個頻率的部分。

(譯者註：未找到high-shelf濾波器通用的中文譯名。)

frequency

頻率閾值。

gain

大於閾值的頻率會獲得的增益強度，單位為分貝。

renpy.audio.filter.Lowpass(frequency=350, q=1.0)

低通濾波器。高於閾值的頻率每高一個八度(頻率加倍)就會有12/dB的衰減。

frequency

閾值頻率。

q

以分貝形式控制結果的峰值。在該類濾波器中，q值並非傳統的Q值(品質參數)，而是一個轉化為分貝的共振結果。

renpy.audio.filter.Lowshelf(frequency=350, gain=0)

highshelf濾波器，可以讓所有頻率通過，但會增強低於某個頻率的部分。

(譯者註：未找到low-shelf濾波器通用的中文譯名。)

frequency

頻率閾值。

gain

小於閾值的頻率會獲得的增益強度，單位為分貝。

class renpy.audio.filter.Mix(*filters)

該音訊過濾器會將自身輸入切分為多個音訊串流，各音訊串流應用不同的過濾器，最終將各音訊串流相加作為輸出。

例如：

init python:

    import renpy.audio.filter as af

    # 此效果將信號延遲0.3秒後與原輸入信號混合。
    $ echo = af.Mix(af.Null(), af.Delay(.3))

class renpy.audio.filter.Multiply(multiplier)

該音訊過濾器直接將輸入與 multiplier 相乘並輸出。

renpy.audio.filter.Notch(frequency=350, q=1.0)

陷波濾波器，與帶通濾波器相反，frequency 兩邊一定範圍內的信號被屏蔽，範圍外的則可以通過。

frequency

中心頻率。

q

控制陷波濾波器的作用頻帶寬度。當q的值增加時，作用頻帶會變窄。

class renpy.audio.filter.Null

輸入與輸出完全一樣的音訊濾波器。

renpy.audio.filter.Peaking(frequency=350, q=1.0, gain=0)

峰化濾波器可以讓所有頻率通過，但會增強 frequency 兩邊一定範圍內的信號。

frequency

中心頻率。

q

控制峰值形狀。q值越大，峰值越尖銳。

gain

中心頻率兩邊一定範圍內的信號的增益強度，單位為分貝。

renpy.audio.filter.Reverb(resonance=.5, dampening=880, wet=1.0, dry=1.0, delay_multiplier=1.0, delay_times=[0.0253, 0.0269, 0.029, 0.0307, 0.0322, 0.0338, 0.0353, 0.0367], delay_subchannel=0.001, allpass_frequences=[225, 556, 441, 341])

來自Freeverb庫，帶瑕疵的混響濾波器，用於模擬在房間內或者大廳中的聲音。

resonance

混響的回饋值。該值應介於0到1之間，值越大則混響的持續越久。該值過大可能會讓混響效果失控。

dampening

該參數使用了一個低通濾波器，在每次混響時都會應用。模擬了聲音通過空氣傳播時會遺失部分高頻信號的現象。

wet

該參數會與混音信號相乘並輸出最終結果。

dry

該參數會與原始輸入信號相乘。若該值為0.0則最終只有混音結果，而沒有原始聲音。

delay_multiplier

該參數會與 delay_times 相乘，用於調整各混音訊段的長度。

delay_times

延遲時間列表，單位為秒。用於創建前期迴響，類似於梳狀濾波器。

delay_subchannel

子通道延遲時間，單位為秒。可以用於營造立體聲效果。

allpass_frequences

一個頻率列表，單位為赫茲(Hz)。用於創建全通濾波器，模擬後期迴響。

class renpy.audio.filter.Sequence

該音訊濾波器會依次應用一個濾波器隊列的所有濾波器效果。通常內部使用，很少直接用。

class renpy.audio.filter.WetDry(filter, wet=1.0, dry=1.0)

該濾波器會將輸入與經過另一個濾波器的輸出混合。

filter

應用到輸入信號上的濾波器。

wet

該參數是一個介於0.0到1.0之間的值，與 filter 輸出結果相乘，用作最終輸出的一部分。

dry

該參數是一個介於0.0到1.0之間的值，與輸入結果相乘，用作最終輸出的一部分。