1/**************************************************************************/
2/* audio_server.h */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#ifndef AUDIO_SERVER_H
32#define AUDIO_SERVER_H
33
34#include "core/math/audio_frame.h"
35#include "core/object/class_db.h"
36#include "core/os/os.h"
37#include "core/templates/safe_list.h"
38#include "core/variant/variant.h"
39#include "servers/audio/audio_effect.h"
40#include "servers/audio/audio_filter_sw.h"
41
42#include <atomic>
43
44class AudioDriverDummy;
45class AudioStream;
46class AudioStreamWAV;
47class AudioStreamPlayback;
48
49class AudioDriver {
50 static AudioDriver *singleton;
51 uint64_t _last_mix_time = 0;
52 uint64_t _last_mix_frames = 0;
53
54#ifdef DEBUG_ENABLED
55 uint64_t prof_ticks = 0;
56 uint64_t prof_time = 0;
57#endif
58
59protected:
60 Vector<int32_t> input_buffer;
61 unsigned int input_position = 0;
62 unsigned int input_size = 0;
63
64 void audio_server_process(int p_frames, int32_t *p_buffer, bool p_update_mix_time = true);
65 void update_mix_time(int p_frames);
66 void input_buffer_init(int driver_buffer_frames);
67 void input_buffer_write(int32_t sample);
68
69 int _get_configured_mix_rate();
70
71#ifdef DEBUG_ENABLED
72 _FORCE_INLINE_ void start_counting_ticks() { prof_ticks = OS::get_singleton()->get_ticks_usec(); }
73 _FORCE_INLINE_ void stop_counting_ticks() { prof_time += OS::get_singleton()->get_ticks_usec() - prof_ticks; }
74#else
75 _FORCE_INLINE_ void start_counting_ticks() {}
76 _FORCE_INLINE_ void stop_counting_ticks() {}
77#endif
78
79public:
80 double get_time_since_last_mix(); //useful for video -> audio sync
81 double get_time_to_next_mix();
82
83 enum SpeakerMode {
84 SPEAKER_MODE_STEREO,
85 SPEAKER_SURROUND_31,
86 SPEAKER_SURROUND_51,
87 SPEAKER_SURROUND_71,
88 };
89
90 static AudioDriver *get_singleton();
91 void set_singleton();
92
93 // Virtual API to implement.
94
95 virtual const char *get_name() const = 0;
96
97 virtual Error init() = 0;
98 virtual void start() = 0;
99 virtual int get_mix_rate() const = 0;
100 virtual SpeakerMode get_speaker_mode() const = 0;
101 virtual float get_latency() { return 0; }
102
103 virtual void lock() = 0;
104 virtual void unlock() = 0;
105 virtual void finish() = 0;
106
107 virtual PackedStringArray get_output_device_list();
108 virtual String get_output_device();
109 virtual void set_output_device(const String &p_name) {}
110
111 virtual Error input_start() { return FAILED; }
112 virtual Error input_stop() { return FAILED; }
113
114 virtual PackedStringArray get_input_device_list();
115 virtual String get_input_device() { return "Default"; }
116 virtual void set_input_device(const String &p_name) {}
117
118 //
119
120 SpeakerMode get_speaker_mode_by_total_channels(int p_channels) const;
121 int get_total_channels_by_speaker_mode(SpeakerMode) const;
122
123 Vector<int32_t> get_input_buffer() { return input_buffer; }
124 unsigned int get_input_position() { return input_position; }
125 unsigned int get_input_size() { return input_size; }
126
127#ifdef DEBUG_ENABLED
128 uint64_t get_profiling_time() const { return prof_time; }
129 void reset_profiling_time() { prof_time = 0; }
130#endif
131
132 AudioDriver() {}
133 virtual ~AudioDriver() {}
134};
135
136class AudioDriverManager {
137 enum {
138 MAX_DRIVERS = 10
139 };
140
141 static AudioDriver *drivers[MAX_DRIVERS];
142 static int driver_count;
143
144 static AudioDriverDummy dummy_driver;
145
146public:
147 static const int DEFAULT_MIX_RATE = 44100;
148
149 static void add_driver(AudioDriver *p_driver);
150 static void initialize(int p_driver);
151 static int get_driver_count();
152 static AudioDriver *get_driver(int p_driver);
153};
154
155class AudioBusLayout;
156
157class AudioServer : public Object {
158 GDCLASS(AudioServer, Object);
159
160public:
161 //re-expose this here, as AudioDriver is not exposed to script
162 enum SpeakerMode {
163 SPEAKER_MODE_STEREO,
164 SPEAKER_SURROUND_31,
165 SPEAKER_SURROUND_51,
166 SPEAKER_SURROUND_71,
167 };
168
169 enum {
170 AUDIO_DATA_INVALID_ID = -1,
171 MAX_CHANNELS_PER_BUS = 4,
172 MAX_BUSES_PER_PLAYBACK = 6,
173 LOOKAHEAD_BUFFER_SIZE = 64,
174 };
175
176 typedef void (*AudioCallback)(void *p_userdata);
177
178private:
179 uint64_t mix_time = 0;
180 int mix_size = 0;
181
182 uint32_t buffer_size = 0;
183 uint64_t mix_count = 0;
184 uint64_t mix_frames = 0;
185#ifdef DEBUG_ENABLED
186 uint64_t prof_time = 0;
187#endif
188
189 float channel_disable_threshold_db = 0.0f;
190 uint32_t channel_disable_frames = 0;
191
192 int channel_count = 0;
193 int to_mix = 0;
194
195 float playback_speed_scale = 1.0f;
196
197 bool tag_used_audio_streams = false;
198
199 struct Bus {
200 StringName name;
201 bool solo = false;
202 bool mute = false;
203 bool bypass = false;
204
205 bool soloed = false;
206
207 // Each channel is a stereo pair.
208 struct Channel {
209 bool used = false;
210 bool active = false;
211 AudioFrame peak_volume = AudioFrame(AUDIO_MIN_PEAK_DB, AUDIO_MIN_PEAK_DB);
212 Vector<AudioFrame> buffer;
213 Vector<Ref<AudioEffectInstance>> effect_instances;
214 uint64_t last_mix_with_audio = 0;
215 Channel() {}
216 };
217
218 Vector<Channel> channels;
219
220 struct Effect {
221 Ref<AudioEffect> effect;
222 bool enabled = false;
223#ifdef DEBUG_ENABLED
224 uint64_t prof_time = 0;
225#endif
226 };
227
228 Vector<Effect> effects;
229 float volume_db = 0.0f;
230 StringName send;
231 int index_cache = 0;
232 };
233
234 struct AudioStreamPlaybackBusDetails {
235 bool bus_active[MAX_BUSES_PER_PLAYBACK] = {};
236 StringName bus[MAX_BUSES_PER_PLAYBACK];
237 AudioFrame volume[MAX_BUSES_PER_PLAYBACK][MAX_CHANNELS_PER_BUS];
238 };
239
240 struct AudioStreamPlaybackListNode {
241 enum PlaybackState {
242 PAUSED = 0, // Paused. Keep this stream playback around though so it can be restarted.
243 PLAYING = 1, // Playing. Fading may still be necessary if volume changes!
244 FADE_OUT_TO_PAUSE = 2, // About to pause.
245 FADE_OUT_TO_DELETION = 3, // About to stop.
246 AWAITING_DELETION = 4,
247 };
248 // If zero or positive, a place in the stream to seek to during the next mix.
249 SafeNumeric<float> setseek;
250 SafeNumeric<float> pitch_scale;
251 SafeNumeric<float> highshelf_gain;
252 SafeNumeric<float> attenuation_filter_cutoff_hz; // This isn't used unless highshelf_gain is nonzero.
253 AudioFilterSW::Processor filter_process[8];
254 // Updating this ref after the list node is created breaks consistency guarantees, don't do it!
255 Ref<AudioStreamPlayback> stream_playback;
256 // Playback state determines the fate of a particular AudioStreamListNode during the mix step. Must be atomically replaced.
257 std::atomic<PlaybackState> state = AWAITING_DELETION;
258 // This data should only ever be modified by an atomic replacement of the pointer.
259 std::atomic<AudioStreamPlaybackBusDetails *> bus_details = nullptr;
260 // Previous bus details should only be accessed on the audio thread.
261 AudioStreamPlaybackBusDetails *prev_bus_details = nullptr;
262 // The next few samples are stored here so we have some time to fade audio out if it ends abruptly at the beginning of the next mix.
263 AudioFrame lookahead[LOOKAHEAD_BUFFER_SIZE];
264 };
265
266 SafeList<AudioStreamPlaybackListNode *> playback_list;
267 SafeList<AudioStreamPlaybackBusDetails *> bus_details_graveyard;
268
269 // TODO document if this is necessary.
270 SafeList<AudioStreamPlaybackBusDetails *> bus_details_graveyard_frame_old;
271
272 Vector<Vector<AudioFrame>> temp_buffer; //temp_buffer for each level
273 Vector<AudioFrame> mix_buffer;
274 Vector<Bus *> buses;
275 HashMap<StringName, Bus *> bus_map;
276
277 void _update_bus_effects(int p_bus);
278
279 static AudioServer *singleton;
280
281 void init_channels_and_buffers();
282
283 void _mix_step();
284 void _mix_step_for_channel(AudioFrame *p_out_buf, AudioFrame *p_source_buf, AudioFrame p_vol_start, AudioFrame p_vol_final, float p_attenuation_filter_cutoff_hz, float p_highshelf_gain, AudioFilterSW::Processor *p_processor_l, AudioFilterSW::Processor *p_processor_r);
285
286 // Should only be called on the main thread.
287 AudioStreamPlaybackListNode *_find_playback_list_node(Ref<AudioStreamPlayback> p_playback);
288
289 struct CallbackItem {
290 AudioCallback callback;
291 void *userdata = nullptr;
292 };
293
294 SafeList<CallbackItem *> update_callback_list;
295 SafeList<CallbackItem *> mix_callback_list;
296 SafeList<CallbackItem *> listener_changed_callback_list;
297
298 friend class AudioDriver;
299 void _driver_process(int p_frames, int32_t *p_buffer);
300
301protected:
302 static void _bind_methods();
303
304public:
305 _FORCE_INLINE_ int get_channel_count() const {
306 switch (get_speaker_mode()) {
307 case SPEAKER_MODE_STEREO:
308 return 1;
309 case SPEAKER_SURROUND_31:
310 return 2;
311 case SPEAKER_SURROUND_51:
312 return 3;
313 case SPEAKER_SURROUND_71:
314 return 4;
315 }
316 ERR_FAIL_V(1);
317 }
318
319 // Do not use from outside audio thread.
320 bool thread_has_channel_mix_buffer(int p_bus, int p_buffer) const;
321 AudioFrame *thread_get_channel_mix_buffer(int p_bus, int p_buffer);
322 int thread_get_mix_buffer_size() const;
323 int thread_find_bus_index(const StringName &p_name);
324
325 void set_bus_count(int p_count);
326 int get_bus_count() const;
327
328 void remove_bus(int p_index);
329 void add_bus(int p_at_pos = -1);
330
331 void move_bus(int p_bus, int p_to_pos);
332
333 void set_bus_name(int p_bus, const String &p_name);
334 String get_bus_name(int p_bus) const;
335 int get_bus_index(const StringName &p_bus_name) const;
336
337 int get_bus_channels(int p_bus) const;
338
339 void set_bus_volume_db(int p_bus, float p_volume_db);
340 float get_bus_volume_db(int p_bus) const;
341
342 void set_bus_send(int p_bus, const StringName &p_send);
343 StringName get_bus_send(int p_bus) const;
344
345 void set_bus_solo(int p_bus, bool p_enable);
346 bool is_bus_solo(int p_bus) const;
347
348 void set_bus_mute(int p_bus, bool p_enable);
349 bool is_bus_mute(int p_bus) const;
350
351 void set_bus_bypass_effects(int p_bus, bool p_enable);
352 bool is_bus_bypassing_effects(int p_bus) const;
353
354 void add_bus_effect(int p_bus, const Ref<AudioEffect> &p_effect, int p_at_pos = -1);
355 void remove_bus_effect(int p_bus, int p_effect);
356
357 int get_bus_effect_count(int p_bus);
358 Ref<AudioEffect> get_bus_effect(int p_bus, int p_effect);
359 Ref<AudioEffectInstance> get_bus_effect_instance(int p_bus, int p_effect, int p_channel = 0);
360
361 void swap_bus_effects(int p_bus, int p_effect, int p_by_effect);
362
363 void set_bus_effect_enabled(int p_bus, int p_effect, bool p_enabled);
364 bool is_bus_effect_enabled(int p_bus, int p_effect) const;
365
366 float get_bus_peak_volume_left_db(int p_bus, int p_channel) const;
367 float get_bus_peak_volume_right_db(int p_bus, int p_channel) const;
368
369 bool is_bus_channel_active(int p_bus, int p_channel) const;
370
371 void set_playback_speed_scale(float p_scale);
372 float get_playback_speed_scale() const;
373
374 // Convenience method.
375 void start_playback_stream(Ref<AudioStreamPlayback> p_playback, StringName p_bus, Vector<AudioFrame> p_volume_db_vector, float p_start_time = 0, float p_pitch_scale = 1);
376 // Expose all parameters.
377 void start_playback_stream(Ref<AudioStreamPlayback> p_playback, HashMap<StringName, Vector<AudioFrame>> p_bus_volumes, float p_start_time = 0, float p_pitch_scale = 1, float p_highshelf_gain = 0, float p_attenuation_cutoff_hz = 0);
378 void stop_playback_stream(Ref<AudioStreamPlayback> p_playback);
379
380 void set_playback_bus_exclusive(Ref<AudioStreamPlayback> p_playback, StringName p_bus, Vector<AudioFrame> p_volumes);
381 void set_playback_bus_volumes_linear(Ref<AudioStreamPlayback> p_playback, HashMap<StringName, Vector<AudioFrame>> p_bus_volumes);
382 void set_playback_all_bus_volumes_linear(Ref<AudioStreamPlayback> p_playback, Vector<AudioFrame> p_volumes);
383 void set_playback_pitch_scale(Ref<AudioStreamPlayback> p_playback, float p_pitch_scale);
384 void set_playback_paused(Ref<AudioStreamPlayback> p_playback, bool p_paused);
385 void set_playback_highshelf_params(Ref<AudioStreamPlayback> p_playback, float p_gain, float p_attenuation_cutoff_hz);
386
387 bool is_playback_active(Ref<AudioStreamPlayback> p_playback);
388 float get_playback_position(Ref<AudioStreamPlayback> p_playback);
389 bool is_playback_paused(Ref<AudioStreamPlayback> p_playback);
390
391 uint64_t get_mix_count() const;
392 uint64_t get_mixed_frames() const;
393
394 void notify_listener_changed();
395
396 virtual void init();
397 virtual void finish();
398 virtual void update();
399 virtual void load_default_bus_layout();
400
401 /* MISC config */
402
403 virtual void lock();
404 virtual void unlock();
405
406 virtual SpeakerMode get_speaker_mode() const;
407 virtual float get_mix_rate() const;
408
409 virtual float read_output_peak_db() const;
410
411 static AudioServer *get_singleton();
412
413 virtual double get_output_latency() const;
414 virtual double get_time_to_next_mix() const;
415 virtual double get_time_since_last_mix() const;
416
417 void add_listener_changed_callback(AudioCallback p_callback, void *p_userdata);
418 void remove_listener_changed_callback(AudioCallback p_callback, void *p_userdata);
419
420 void add_update_callback(AudioCallback p_callback, void *p_userdata);
421 void remove_update_callback(AudioCallback p_callback, void *p_userdata);
422
423 void add_mix_callback(AudioCallback p_callback, void *p_userdata);
424 void remove_mix_callback(AudioCallback p_callback, void *p_userdata);
425
426 void set_bus_layout(const Ref<AudioBusLayout> &p_bus_layout);
427 Ref<AudioBusLayout> generate_bus_layout() const;
428
429 PackedStringArray get_output_device_list();
430 String get_output_device();
431 void set_output_device(const String &p_name);
432
433 PackedStringArray get_input_device_list();
434 String get_input_device();
435 void set_input_device(const String &p_name);
436
437 void set_enable_tagging_used_audio_streams(bool p_enable);
438
439 AudioServer();
440 virtual ~AudioServer();
441};
442
443VARIANT_ENUM_CAST(AudioServer::SpeakerMode)
444
445class AudioBusLayout : public Resource {
446 GDCLASS(AudioBusLayout, Resource);
447
448 friend class AudioServer;
449
450 struct Bus {
451 StringName name;
452 bool solo = false;
453 bool mute = false;
454 bool bypass = false;
455
456 struct Effect {
457 Ref<AudioEffect> effect;
458 bool enabled = false;
459 };
460
461 Vector<Effect> effects;
462
463 float volume_db = 0.0f;
464 StringName send;
465
466 Bus() {}
467 };
468
469 Vector<Bus> buses;
470
471protected:
472 bool _set(const StringName &p_name, const Variant &p_value);
473 bool _get(const StringName &p_name, Variant &r_ret) const;
474 void _get_property_list(List<PropertyInfo> *p_list) const;
475
476public:
477 AudioBusLayout();
478};
479
480typedef AudioServer AS;
481
482#endif // AUDIO_SERVER_H
483