virtualx-engine/doc/classes/AudioServer.xml

379 lines
16 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioServer" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Server interface for low-level audio access.
</brief_description>
<description>
[AudioServer] is a low-level server interface for audio access. It is in charge of creating sample data (playable audio) as well as its playback via a voice interface.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
<link title="Audio Device Changer Demo">https://godotengine.org/asset-library/asset/2758</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<methods>
<method name="add_bus">
<return type="void" />
<param index="0" name="at_position" type="int" default="-1" />
<description>
Adds a bus at [param at_position].
</description>
</method>
<method name="add_bus_effect">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect" type="AudioEffect" />
<param index="2" name="at_position" type="int" default="-1" />
<description>
Adds an [AudioEffect] effect to the bus [param bus_idx] at [param at_position].
</description>
</method>
<method name="generate_bus_layout" qualifiers="const">
<return type="AudioBusLayout" />
<description>
Generates an [AudioBusLayout] using the available buses and effects.
</description>
</method>
<method name="get_bus_channels" qualifiers="const">
<return type="int" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the number of channels of the bus at index [param bus_idx].
</description>
</method>
<method name="get_bus_effect">
<return type="AudioEffect" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
Returns the [AudioEffect] at position [param effect_idx] in bus [param bus_idx].
</description>
</method>
<method name="get_bus_effect_count">
<return type="int" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the number of effects on the bus at [param bus_idx].
</description>
</method>
2019-04-15 14:49:41 +02:00
<method name="get_bus_effect_instance">
<return type="AudioEffectInstance" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="channel" type="int" default="0" />
2019-04-15 14:49:41 +02:00
<description>
Returns the [AudioEffectInstance] assigned to the given bus and effect indices (and optionally channel).
2019-04-15 14:49:41 +02:00
</description>
</method>
<method name="get_bus_index" qualifiers="const">
<return type="int" />
<param index="0" name="bus_name" type="StringName" />
<description>
Returns the index of the bus with the name [param bus_name]. Returns [code]-1[/code] if no bus with the specified name exist.
</description>
</method>
<method name="get_bus_name" qualifiers="const">
<return type="String" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the name of the bus with the index [param bus_idx].
</description>
</method>
<method name="get_bus_peak_volume_left_db" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="channel" type="int" />
<description>
Returns the peak volume of the left speaker at bus index [param bus_idx] and channel index [param channel].
</description>
</method>
<method name="get_bus_peak_volume_right_db" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="channel" type="int" />
<description>
Returns the peak volume of the right speaker at bus index [param bus_idx] and channel index [param channel].
</description>
</method>
<method name="get_bus_send" qualifiers="const">
<return type="StringName" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the name of the bus that the bus at index [param bus_idx] sends to.
</description>
</method>
<method name="get_bus_volume_db" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the volume of the bus at index [param bus_idx] in dB.
</description>
</method>
<method name="get_input_device_list">
<return type="PackedStringArray" />
2018-04-10 10:12:42 +02:00
<description>
Returns the names of all audio input devices detected on the system.
[b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
</description>
</method>
<method name="get_mix_rate" qualifiers="const">
<return type="float" />
<description>
2019-07-02 12:04:26 +02:00
Returns the sample rate at the output of the [AudioServer].
</description>
</method>
<method name="get_output_device_list">
<return type="PackedStringArray" />
<description>
Returns the names of all audio output devices detected on the system.
</description>
</method>
<method name="get_output_latency" qualifiers="const">
<return type="float" />
<description>
Returns the audio driver's effective output latency. This is based on [member ProjectSettings.audio/driver/output_latency], but the exact returned value will differ depending on the operating system and audio driver.
[b]Note:[/b] This can be expensive; it is not recommended to call [method get_output_latency] every frame.
</description>
</method>
<method name="get_speaker_mode" qualifiers="const">
<return type="int" enum="AudioServer.SpeakerMode" />
<description>
Returns the speaker configuration.
</description>
</method>
<method name="get_time_since_last_mix" qualifiers="const">
<return type="float" />
<description>
Returns the relative time since the last mix occurred.
</description>
</method>
<method name="get_time_to_next_mix" qualifiers="const">
<return type="float" />
<description>
Returns the relative time until the next mix occurs.
</description>
</method>
<method name="is_bus_bypassing_effects" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is bypassing effects.
</description>
</method>
<method name="is_bus_effect_enabled" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
If [code]true[/code], the effect at index [param effect_idx] on the bus at index [param bus_idx] is enabled.
</description>
</method>
<method name="is_bus_mute" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is muted.
</description>
</method>
<method name="is_bus_solo" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is in solo mode.
</description>
</method>
2024-04-18 16:50:34 +02:00
<method name="is_stream_registered_as_sample" experimental="">
<return type="bool" />
<param index="0" name="stream" type="AudioStream" />
<description>
If [code]true[/code], the stream is registered as a sample. The engine will not have to register it before playing the sample.
If [code]false[/code], the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with [method register_stream_as_sample].
</description>
</method>
<method name="lock">
<return type="void" />
<description>
Locks the audio driver's main loop.
[b]Note:[/b] Remember to unlock it afterwards.
</description>
</method>
<method name="move_bus">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="to_index" type="int" />
<description>
Moves the bus from index [param index] to index [param to_index].
</description>
</method>
2024-04-18 16:50:34 +02:00
<method name="register_stream_as_sample" experimental="">
<return type="void" />
<param index="0" name="stream" type="AudioStream" />
<description>
Forces the registration of a stream as a sample.
[b]Note:[/b] Lag spikes may occur when calling this method, especially on single-threaded builds. It is suggested to call this method while loading assets, where the lag spike could be masked, instead of registering the sample right before it needs to be played.
</description>
</method>
<method name="remove_bus">
<return type="void" />
<param index="0" name="index" type="int" />
<description>
Removes the bus at index [param index].
</description>
</method>
<method name="remove_bus_effect">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
Removes the effect at index [param effect_idx] from the bus at index [param bus_idx].
</description>
</method>
<method name="set_bus_bypass_effects">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is bypassing effects.
</description>
</method>
<method name="set_bus_effect_enabled">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="enabled" type="bool" />
<description>
If [code]true[/code], the effect at index [param effect_idx] on the bus at index [param bus_idx] is enabled.
</description>
</method>
<method name="set_bus_layout">
<return type="void" />
<param index="0" name="bus_layout" type="AudioBusLayout" />
<description>
Overwrites the currently used [AudioBusLayout].
</description>
</method>
<method name="set_bus_mute">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is muted.
</description>
</method>
<method name="set_bus_name">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="name" type="String" />
<description>
Sets the name of the bus at index [param bus_idx] to [param name].
</description>
</method>
<method name="set_bus_send">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="send" type="StringName" />
<description>
Connects the output of the bus at [param bus_idx] to the bus named [param send].
</description>
</method>
<method name="set_bus_solo">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is in solo mode.
</description>
</method>
<method name="set_bus_volume_db">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="volume_db" type="float" />
<description>
Sets the volume of the bus at index [param bus_idx] to [param volume_db].
</description>
</method>
<method name="set_enable_tagging_used_audio_streams">
<return type="void" />
<param index="0" name="enable" type="bool" />
<description>
If set to [code]true[/code], all instances of [AudioStreamPlayback] will call [method AudioStreamPlayback._tag_used_streams] every mix step.
[b]Note:[/b] This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews.
</description>
</method>
<method name="swap_bus_effects">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="by_effect_idx" type="int" />
<description>
Swaps the position of two effects in bus [param bus_idx].
</description>
</method>
<method name="unlock">
<return type="void" />
<description>
Unlocks the audio driver's main loop. (After locking it, you should always unlock it.)
</description>
</method>
</methods>
<members>
2019-07-02 12:04:26 +02:00
<member name="bus_count" type="int" setter="set_bus_count" getter="get_bus_count" default="1">
Number of available audio buses.
</member>
<member name="input_device" type="String" setter="set_input_device" getter="get_input_device" default="&quot;Default&quot;">
Name of the current device for audio input (see [method get_input_device_list]). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value [code]"Default"[/code] will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code].
[b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
</member>
<member name="output_device" type="String" setter="set_output_device" getter="get_output_device" default="&quot;Default&quot;">
Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code].
</member>
<member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0">
Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). See also [member Engine.time_scale] to affect the general simulation speed, which is independent from [member AudioServer.playback_speed_scale].
</member>
</members>
<signals>
<signal name="bus_layout_changed">
<description>
2023-09-14 12:39:23 +02:00
Emitted when an audio bus is added, deleted, or moved.
</description>
</signal>
<signal name="bus_renamed">
<param index="0" name="bus_index" type="int" />
<param index="1" name="old_name" type="StringName" />
<param index="2" name="new_name" type="StringName" />
<description>
Emitted when the audio bus at [param bus_index] is renamed from [param old_name] to [param new_name].
</description>
</signal>
</signals>
<constants>
2017-11-24 23:16:30 +01:00
<constant name="SPEAKER_MODE_STEREO" value="0" enum="SpeakerMode">
2019-07-02 12:04:26 +02:00
Two or fewer speakers were detected.
</constant>
2018-10-25 15:14:36 +02:00
<constant name="SPEAKER_SURROUND_31" value="1" enum="SpeakerMode">
2019-07-02 12:04:26 +02:00
A 3.1 channel surround setup was detected.
2018-10-25 15:14:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name="SPEAKER_SURROUND_51" value="2" enum="SpeakerMode">
A 5.1 channel surround setup was detected.
</constant>
2017-11-24 23:16:30 +01:00
<constant name="SPEAKER_SURROUND_71" value="3" enum="SpeakerMode">
A 7.1 channel surround setup was detected.
</constant>
2024-04-18 16:50:34 +02:00
<constant name="PLAYBACK_TYPE_DEFAULT" value="0" enum="PlaybackType" experimental="">
The playback will be considered of the type declared at [member ProjectSettings.audio/general/default_playback_type].
</constant>
<constant name="PLAYBACK_TYPE_STREAM" value="1" enum="PlaybackType" experimental="">
Force the playback to be considered as a stream.
</constant>
<constant name="PLAYBACK_TYPE_SAMPLE" value="2" enum="PlaybackType" experimental="">
Force the playback to be considered as a sample. This can provide lower latency and more stable playback (with less risk of audio crackling), at the cost of having less flexibility.
[b]Note:[/b] Only currently supported on the web platform.
[b]Note:[/b] [AudioEffect]s are not supported when playback is considered as a sample.
</constant>
<constant name="PLAYBACK_TYPE_MAX" value="3" enum="PlaybackType" experimental="">
Represents the size of the [enum PlaybackType] enum.
</constant>
</constants>
</class>