Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
自訂 AudioStream
前言
AudioStream 是所有音訊發出物件的基底類別。AudioStreamPlayer 會繫結到 AudioStream 上,將 PCM 資料傳送至 AudioServer,由 AudioServer 管理音訊驅動程式。
所有音訊資源都需有兩個基礎類別:AudioStream 以及 AudioStreamPlayback。AudioStream 作為資料容器,會包含音訊資源並對 GDScript 開放存取。AudioStream 會參照其內部自訂的 AudioStreamPlayback,將 AudioStream 轉換成 PCM 資料。
本指南假設讀者已熟悉如何建立 C++ 模組。如尚未了解,請先參考這篇指南:以 C++ 自訂模組。
參考資料:
用途說明?
繫結外部函式庫(如 Wwise、FMOD 等)。
新增自訂音訊佇列
增加更多音訊格式的支援
建立 AudioStream
一個 AudioStream 由三個組成元件構成:資料容器、串流名稱,以及 AudioStreamPlayback 友類產生器。音訊資料可透過多種方式載入,例如作為音調產生器的內部計數器、內部或外部緩衝區,或是檔案參照。
有些 AudioStream 需為無狀態(stateless),如由 ResourceLoader 載入的物件。ResourceLoader 只會載入一次,無論針對特定資源呼叫幾次 load,都會參照同一個物件。因此,播放狀態必須完全封裝於 AudioStreamPlayback 之中。
#pragma once
#include "servers/audio/audio_stream.h"
class AudioStreamMyTone : public AudioStream {
GDCLASS(AudioStreamMyTone, AudioStream)
private:
friend class AudioStreamPlaybackMyTone;
public:
virtual Ref<AudioStreamPlayback> instantiate_playback() override;
virtual String get_stream_name() const override;
virtual double get_length() const override { return 0.0; }
virtual void get_parameter_list(List<Parameter> *r_parameters) override;
protected:
static void _bind_methods();
};
#include "audiostream_mytone.h"
#include "audiostream_playback_mytone.h"
Ref<AudioStreamPlayback> AudioStreamMyTone::instantiate_playback() {
Ref<AudioStreamPlaybackMyTone> playback;
playback.instantiate();
playback->base = Ref<AudioStreamMyTone>(this);
playback->init();
return playback;
}
String AudioStreamMyTone::get_stream_name() const {
return "MyTone";
}
void AudioStreamMyTone::get_parameter_list(List<Parameter> *r_parameters) {
r_parameters->push_back(Parameter(PropertyInfo(Variant::FLOAT, "Frequency", PROPERTY_HINT_RANGE, "44.0, 16000.0"), "220.0"));
}
void AudioStreamMyTone::_bind_methods() {}
參考資料:
建立 AudioStreamPlayback
AudioStreamPlayer 會使用 mix 回呼來取得 PCM 資料。此回呼必須符合取樣率,並填滿緩衝區。
由於 AudioStreamPlayback 受音訊執行緒控制,因此禁止進行 I/O 或動態記憶體分配。
#pragma once
#include "servers/audio/audio_stream.h"
class AudioStreamMyTone;
class AudioStreamPlaybackMyTone : public AudioStreamPlayback {
GDCLASS(AudioStreamPlaybackMyTone, AudioStreamPlayback)
friend AudioStreamMyTone;
private:
Ref<AudioStreamMyTone> base;
double pos = 0.0;
float freq_hz = 220.0f;
bool active = false;
public:
virtual ~AudioStreamPlaybackMyTone() = default;
virtual void start(double p_from_pos = 0.0) override;
virtual void stop() override;
virtual bool is_playing() const override;
virtual int get_loop_count() const override;
virtual double get_playback_position() const override;
virtual void seek(double p_time) override;
virtual int mix(AudioFrame *p_buffer, float p_rate_scale, int p_frames) override;
virtual void set_parameter(const StringName &p_name, const Variant &p_value) override;
virtual Variant get_parameter(const StringName &p_name) const override;
protected:
void reset();
bool init();
void generate(AudioFrame *pcm_buf, int size);
void set_freq(float value);
float get_freq() const;
static void _bind_methods();
};
#include "audiostream_playback_mytone.h"
#include <core/math/math_funcs.h>
#include <core/object/class_db.h>
#include <servers/audio/audio_server.h>
void AudioStreamPlaybackMyTone::start(double p_from_pos) {
active = true;
}
void AudioStreamPlaybackMyTone::stop() {
active = false;
}
bool AudioStreamPlaybackMyTone::is_playing() const {
return active;
}
int AudioStreamPlaybackMyTone::get_loop_count() const {
return 0;
}
double AudioStreamPlaybackMyTone::get_playback_position() const {
return 0.0;
}
void AudioStreamPlaybackMyTone::seek(double p_time) {
if (p_time < 0) {
p_time = 0;
}
const float mix_rate = AudioServer::get_singleton()->get_mix_rate();
pos = p_time * mix_rate;
}
int AudioStreamPlaybackMyTone::mix(AudioFrame *p_buffer, float p_rate, int p_frames) {
ERR_FAIL_COND_V(!is_playing(), 0);
if (!is_playing()) {
return 0;
}
generate(p_buffer, p_frames);
return p_frames;
}
void AudioStreamPlaybackMyTone::set_parameter(const StringName &p_name, const Variant &p_value) {
if (p_name == SNAME("Frequency")) {
const float value = p_value;
set_freq(value);
}
}
Variant AudioStreamPlaybackMyTone::get_parameter(const StringName &p_name) const {
if (p_name == SNAME("Frequency")) {
return Variant(get_freq());
}
ERR_FAIL_COND_V(true, Variant());
return Variant{};
}
void AudioStreamPlaybackMyTone::reset() {
seek(0.0);
}
bool AudioStreamPlaybackMyTone::init() {
reset();
return true;
}
void AudioStreamPlaybackMyTone::generate(AudioFrame *pcm_buf, int size) {
if (!active) {
return;
}
const float mix_rate = AudioServer::get_singleton()->get_mix_rate();
for (int i = 0; i < size; i++) {
const float sample = 32767.0f * Math::sin(2.0f * Math::PI * float(pos + i) / (mix_rate / freq_hz));
pcm_buf[i].left = sample;
pcm_buf[i].right = sample;
}
pos += size;
}
void AudioStreamPlaybackMyTone::set_freq(float value) {
freq_hz = CLAMP(value, 44.0f, 16000.0f);
}
float AudioStreamPlaybackMyTone::get_freq() const {
return freq_hz;
}
void AudioStreamPlaybackMyTone::_bind_methods() {
ClassDB::bind_method(D_METHOD("reset"), &AudioStreamPlaybackMyTone::reset);
ClassDB::bind_method(D_METHOD("set_freq", "value"), &AudioStreamPlaybackMyTone::set_freq);
ClassDB::bind_method(D_METHOD("get_freq"), &AudioStreamPlaybackMyTone::get_freq);
}
用法
set_freq 和 get_freq 方法允許直接修改頻率參數,但也可以透過更通用的屬性方式,使用 get/set("parameters/Frequency") 存取參數。
extends AudioStreamPlayer3D
var control: float = 0.0
func _input(event):
if event.is_action_pressed("play"):
if is_playing():
stop()
else:
play()
control = get_stream_playback().get_freq()
# Parameter equivalent:
# control = get("parameters/Frequency") as float
print(control)
if event.is_action_pressed("up"):
control *= 1.1
set_freq(control)
print(control)
if event.is_action_pressed("down"):
control *= 0.9
set_freq(control)
print(control)
func set_freq(value):
var stream_playback = get_stream_playback()
if stream_playback:
stream_playback.set_freq(control)
# Parameter equivalent:
#set("parameters/Frequency", control)
重新取樣
Godot 的 AudioServer 目前採用 44100 Hz 取樣率。若需其他取樣率(如 48000 Hz),可自行提供或使用 AudioStreamPlaybackResampled。Godot 提供三次方內插(cubic interpolation)進行音訊重新取樣。
AudioStreamPlaybackResampled 並非複寫 mix,而是使用 _mix_internal 查詢 AudioFrame,並以 get_stream_sampling_rate 取得目前混音取樣率。