mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2026-01-05 14:10:19 +03:00
227 lines
10 KiB
ReStructuredText
227 lines
10 KiB
ReStructuredText
:github_url: hide
|
|
|
|
.. _class_AudioStreamGenerator:
|
|
|
|
AudioStreamGenerator
|
|
====================
|
|
|
|
**Hereda:** :ref:`AudioStream<class_AudioStream>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
|
|
|
|
Una transmisión de audio con utilidades para la generación de sonido procedimental.
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
Descripción
|
|
----------------------
|
|
|
|
**AudioStreamGenerator** is a type of audio stream that does not play back sounds on its own; instead, it expects a script to generate audio data for it. See also :ref:`AudioStreamGeneratorPlayback<class_AudioStreamGeneratorPlayback>`.
|
|
|
|
Here's a sample on how to use it to generate a sine wave:
|
|
|
|
|
|
.. tabs::
|
|
|
|
.. code-tab:: gdscript
|
|
|
|
var playback # Will hold the AudioStreamGeneratorPlayback.
|
|
@onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
|
|
var pulse_hz = 440.0 # The frequency of the sound wave.
|
|
var phase = 0.0
|
|
|
|
func _ready():
|
|
$AudioStreamPlayer.play()
|
|
playback = $AudioStreamPlayer.get_stream_playback()
|
|
fill_buffer()
|
|
|
|
func fill_buffer():
|
|
var increment = pulse_hz / sample_hz
|
|
var frames_available = playback.get_frames_available()
|
|
|
|
for i in range(frames_available):
|
|
playback.push_frame(Vector2.ONE * sin(phase * TAU))
|
|
phase = fmod(phase + increment, 1.0)
|
|
|
|
.. code-tab:: csharp
|
|
|
|
[Export] public AudioStreamPlayer Player { get; set; }
|
|
|
|
private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback.
|
|
private float _sampleHz;
|
|
private float _pulseHz = 440.0f; // The frequency of the sound wave.
|
|
private double phase = 0.0;
|
|
|
|
public override void _Ready()
|
|
{
|
|
if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate.
|
|
{
|
|
_sampleHz = generator.MixRate;
|
|
Player.Play();
|
|
_playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback();
|
|
FillBuffer();
|
|
}
|
|
}
|
|
|
|
public void FillBuffer()
|
|
{
|
|
float increment = _pulseHz / _sampleHz;
|
|
int framesAvailable = _playback.GetFramesAvailable();
|
|
|
|
for (int i = 0; i < framesAvailable; i++)
|
|
{
|
|
_playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau));
|
|
phase = Mathf.PosMod(phase + increment, 1.0);
|
|
}
|
|
}
|
|
|
|
|
|
|
|
In the example above, the "AudioStreamPlayer" node must use an **AudioStreamGenerator** as its stream. The ``fill_buffer`` function provides audio data for approximating a sine wave.
|
|
|
|
See also :ref:`AudioEffectSpectrumAnalyzer<class_AudioEffectSpectrumAnalyzer>` for performing real-time audio spectrum analysis.
|
|
|
|
\ **Note:** Due to performance constraints, this class is best used from C# or from a compiled language via GDExtension. If you still want to use this class from GDScript, consider using a lower :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>` such as 11,025 Hz or 22,050 Hz.
|
|
|
|
.. rst-class:: classref-introduction-group
|
|
|
|
Tutoriales
|
|
--------------------
|
|
|
|
- `Demo de Generador de Audio <https://godotengine.org/asset-library/asset/2759>`__
|
|
|
|
.. rst-class:: classref-reftable-group
|
|
|
|
Propiedades
|
|
----------------------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
|
|
| :ref:`float<class_float>` | :ref:`buffer_length<class_AudioStreamGenerator_property_buffer_length>` | ``0.5`` |
|
|
+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
|
|
| :ref:`float<class_float>` | :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>` | ``44100.0`` |
|
|
+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
|
|
| :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` | :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` | ``2`` |
|
|
+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------+-------------+
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Enumeraciones
|
|
--------------------------
|
|
|
|
.. _enum_AudioStreamGenerator_AudioStreamGeneratorMixRate:
|
|
|
|
.. rst-class:: classref-enumeration
|
|
|
|
enum **AudioStreamGeneratorMixRate**: :ref:`🔗<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>`
|
|
|
|
.. _class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT:
|
|
|
|
.. rst-class:: classref-enumeration-constant
|
|
|
|
:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_OUTPUT** = ``0``
|
|
|
|
Frecuencia de mezcla de salida actual de :ref:`AudioServer<class_AudioServer>`.
|
|
|
|
.. _class_AudioStreamGenerator_constant_MIX_RATE_INPUT:
|
|
|
|
.. rst-class:: classref-enumeration-constant
|
|
|
|
:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_INPUT** = ``1``
|
|
|
|
Frecuencia de mezcla de entrada actual de :ref:`AudioServer<class_AudioServer>`.
|
|
|
|
.. _class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM:
|
|
|
|
.. rst-class:: classref-enumeration-constant
|
|
|
|
:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_CUSTOM** = ``2``
|
|
|
|
Tasa de mezcla personalizada, especificada por :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>`.
|
|
|
|
.. _class_AudioStreamGenerator_constant_MIX_RATE_MAX:
|
|
|
|
.. rst-class:: classref-enumeration-constant
|
|
|
|
:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **MIX_RATE_MAX** = ``3``
|
|
|
|
Valor máximo para la enumeración del modo de velocidad de mezcla.
|
|
|
|
.. rst-class:: classref-section-separator
|
|
|
|
----
|
|
|
|
.. rst-class:: classref-descriptions-group
|
|
|
|
Descripciones de Propiedades
|
|
--------------------------------------------------------
|
|
|
|
.. _class_AudioStreamGenerator_property_buffer_length:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`float<class_float>` **buffer_length** = ``0.5`` :ref:`🔗<class_AudioStreamGenerator_property_buffer_length>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_buffer_length**\ (\ value\: :ref:`float<class_float>`\ )
|
|
- :ref:`float<class_float>` **get_buffer_length**\ (\ )
|
|
|
|
La duración del búfer a generar (en segundos). Valores más bajos resultan en menor latencia, pero requieren que el script genere los datos de audio más rápido, lo que aumenta el uso de la CPU y el riesgo de interrupciones en el audio (cracking) si la CPU no puede mantener el ritmo.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_AudioStreamGenerator_property_mix_rate:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`float<class_float>` **mix_rate** = ``44100.0`` :ref:`🔗<class_AudioStreamGenerator_property_mix_rate>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_mix_rate**\ (\ value\: :ref:`float<class_float>`\ )
|
|
- :ref:`float<class_float>` **get_mix_rate**\ (\ )
|
|
|
|
The sample rate to use (in Hz). Higher values are more demanding for the CPU to generate, but result in better quality.
|
|
|
|
In games, common sample rates in use are ``11025``, ``16000``, ``22050``, ``32000``, ``44100``, and ``48000``.
|
|
|
|
According to the `Nyquist-Shannon sampling theorem <https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem>`__, there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are generating lower-pitched sounds such as voices, lower sample rates such as ``32000`` or ``22050`` may be usable with no loss in quality.
|
|
|
|
\ **Note:** **AudioStreamGenerator** is not automatically resampling input data, to produce expected result :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` should match the sampling rate of input data.
|
|
|
|
\ **Note:** If you are using :ref:`AudioEffectCapture<class_AudioEffectCapture>` as the source of your data, set :ref:`mix_rate_mode<class_AudioStreamGenerator_property_mix_rate_mode>` to :ref:`MIX_RATE_INPUT<class_AudioStreamGenerator_constant_MIX_RATE_INPUT>` or :ref:`MIX_RATE_OUTPUT<class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT>` to automatically match current :ref:`AudioServer<class_AudioServer>` mixing rate.
|
|
|
|
.. rst-class:: classref-item-separator
|
|
|
|
----
|
|
|
|
.. _class_AudioStreamGenerator_property_mix_rate_mode:
|
|
|
|
.. rst-class:: classref-property
|
|
|
|
:ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **mix_rate_mode** = ``2`` :ref:`🔗<class_AudioStreamGenerator_property_mix_rate_mode>`
|
|
|
|
.. rst-class:: classref-property-setget
|
|
|
|
- |void| **set_mix_rate_mode**\ (\ value\: :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>`\ )
|
|
- :ref:`AudioStreamGeneratorMixRate<enum_AudioStreamGenerator_AudioStreamGeneratorMixRate>` **get_mix_rate_mode**\ (\ )
|
|
|
|
Mixing rate mode. If set to :ref:`MIX_RATE_CUSTOM<class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM>`, :ref:`mix_rate<class_AudioStreamGenerator_property_mix_rate>` is used, otherwise current :ref:`AudioServer<class_AudioServer>` mixing rate is used.
|
|
|
|
.. |virtual| replace:: :abbr:`virtual (Normalmente, este método debería ser sobreescrito por el usuario para que tenga algún efecto.)`
|
|
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
|
|
.. |const| replace:: :abbr:`const (Este método no tiene efectos secundarios. No modifica ninguna de las variables miembro de la instancia.)`
|
|
.. |vararg| replace:: :abbr:`vararg (Este método permite agregar cualquier número de argumentos después de los descritos aquí.)`
|
|
.. |constructor| replace:: :abbr:`constructor (Este método se utiliza para construir un tipo.)`
|
|
.. |static| replace:: :abbr:`static (Este método no necesita una instancia para ser llamado, por lo que puede llamarse directamente utilizando el nombre de la clase.)`
|
|
.. |operator| replace:: :abbr:`operator (Este método describe un operador válido para usar con este tipo como operando izquierdo.)`
|
|
.. |bitfield| replace:: :abbr:`BitField (Este valor es un entero compuesto como una máscara de bits de las siguientes banderas.)`
|
|
.. |void| replace:: :abbr:`void (Sin valor de retorno.)`
|