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...

AudioStreamPlayer3D

Успадковує: Node3D < Node < Object

Відтворює позиційний звук у тривимірному просторі.

Опис

Відтворює аудіо з позиційними звуковими ефектами на основі відносної позиції аудіослухача. Позиційні ефекти включають ослаблення на відстані, спрямованість і ефект Доплера. Для більшої реалістичності до віддалених звуків застосовано фільтр низьких частот. Це можна вимкнути, встановивши attenuation_filter_cutoff_hz на 20500.

За замовчуванням звук лунає з камери. Це можна змінити, додавши до сцени вузол AudioListener3D і ввімкнувши його, викликавши для нього AudioListener3D.make_current().

Перегляньте також AudioStreamPlayer, щоб відтворити звук непозиційно.

Примітка: Приховування вузла AudioStreamPlayer3D не вимикає його аудіовихід. Щоб тимчасово вимкнути аудіовихід AudioStreamPlayer3D, установіть volume_db на дуже низьке значення, як-от -100 (яке не чутно для людського слуху).

Посібники

Властивості

int

area_mask

0

float

attenuation_filter_cutoff_hz

5000.0

float

attenuation_filter_db

-24.0

AttenuationModel

attenuation_model

0

bool

autoplay

false

StringName

bus

&"Master"

DopplerTracking

doppler_tracking

0

float

emission_angle_degrees

45.0

bool

emission_angle_enabled

false

float

emission_angle_filter_attenuation_db

-12.0

float

max_db

3.0

float

max_distance

0.0

int

max_polyphony

1

float

panning_strength

1.0

float

pitch_scale

1.0

PlaybackType

playback_type

0

bool

playing

false

AudioStream

stream

bool

stream_paused

false

float

unit_size

10.0

float

volume_db

0.0

float

volume_linear

Методи

float

get_playback_position()

AudioStreamPlayback

get_stream_playback()

bool

has_stream_playback()

void

play(from_position: float = 0.0)

void

seek(to_position: float)

void

stop()

Сигнали

finished() 🔗

Видається, коли звук припиняється.

Переліки

enum AttenuationModel: 🔗

AttenuationModel ATTENUATION_INVERSE_DISTANCE = 0

Зниження гучності відповідно до лінійної відстані.

AttenuationModel ATTENUATION_INVERSE_SQUARE_DISTANCE = 1

Зниження гучності відповідно до квадрата відстані.

AttenuationModel ATTENUATION_LOGARITHMIC = 2

Послаблення гучності відповідно до логарифмічної відстані.

AttenuationModel ATTENUATION_DISABLED = 3

Немає ослаблення гучності відповідно до відстані. На відміну від AudioStreamPlayer, звук буде чути позиційно. ATTENUATION_DISABLED можна об’єднати зі значенням max_distance, більшим за 0.0, щоб досягти лінійного затухання, прикріпленого до сфери певного розміру.

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

Вимикає доплерівське відстеження.

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

Виконує доплерівське відстеження під час кадрів процесу (див. Node.NOTIFICATION_INTERNAL_PROCESS).

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

Виконує доплерівське відстеження під час кадрів фізики (див. Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS).

Описи властивостей

int area_mask = 0 🔗

  • void set_area_mask(value: int)

  • int get_area_mask()

Визначає, які шари Area3D впливають на звук ефектів реверберації та аудіошини. Області можна використовувати для перенаправлення AudioStream, щоб вони відтворювалися на певній аудіошині. Прикладом того, як це можна використовувати, є створення «водної» області, щоб звуки, що відтворюються у воді, перенаправлялися через аудіошину, щоб вони звучали так, ніби вони відтворюються під водою.

float attenuation_filter_cutoff_hz = 5000.0 🔗

  • void set_attenuation_filter_cutoff_hz(value: float)

  • float get_attenuation_filter_cutoff_hz()

Частота зрізу фільтра низьких частот ослаблення, Гц. Звук вище цієї частоти послаблюється більше, ніж звук нижче цієї частоти. Щоб вимкнути цей ефект, встановіть значення 20500, оскільки ця частота перевищує межу людського слуху.

float attenuation_filter_db = -24.0 🔗

  • void set_attenuation_filter_db(value: float)

  • float get_attenuation_filter_db()

Величина впливу фільтра на гучність, у децибелах.

AttenuationModel attenuation_model = 0 🔗

Вирішує, чи повинен звук зменшуватися з відстанню лінійно, квадратично, логарифмічно, чи на нього відстань не впливає, фактично вимикаючи затухання.

bool autoplay = false 🔗

  • void set_autoplay(value: bool)

  • bool is_autoplay_enabled()

Якщо true, звук відтворюється, коли вузол AudioStreamPlayer3D додається до дерева сцен.

StringName bus = &"Master" 🔗

  • void set_bus(value: StringName)

  • StringName get_bus()

Автобус, на якому відтворюється цей звук.

Примітка: Встановлюючи цю властивість, майте на увазі, що перевірка не виконується, щоб побачити, чи дане ім’я відповідає існуючій шині. Це пояснюється тим, що макети аудіошини можуть завантажуватися після встановлення цієї властивості. Якщо це задане ім’я не може бути визначено під час виконання, воно повернеться до "Master".

DopplerTracking doppler_tracking = 0 🔗

Визначає, на якому кроці слід розраховувати ефект Доплера.

Примітка: Якщо doppler_tracking не є DOPPLER_TRACKING_DISABLED, але для поточного Camera3D/AudioListener3D вимкнено доплерівське відстеження, ефект Доплера буде чути, але рух поточного слухача не враховуватиметься. Якщо потрібен точний ефект Доплера, доплерівське відстеження слід увімкнути як для AudioStreamPlayer3D, так і для поточного Camera3D/AudioListener3D.

float emission_angle_degrees = 45.0 🔗

  • void set_emission_angle(value: float)

  • float get_emission_angle()

Кут, під яким аудіо доходить до слухача без ослаблення.

bool emission_angle_enabled = false 🔗

  • void set_emission_angle_enabled(value: bool)

  • bool is_emission_angle_enabled()

Якщо true, аудіо повинні бути загартовані за напрямком звуку.

float emission_angle_filter_attenuation_db = -12.0 🔗

  • void set_emission_angle_filter_attenuation_db(value: float)

  • float get_emission_angle_filter_attenuation_db()

Коефіцієнт ослаблення, який використовується, якщо слухач знаходиться за межами emission_angle_degrees і встановлено emission_angle_enabled, у децибелах.

float max_db = 3.0 🔗

  • void set_max_db(value: float)

  • float get_max_db()

Встановлює абсолютний максимум рівня звуку в децибелах.

float max_distance = 0.0 🔗

  • void set_max_distance(value: float)

  • float get_max_distance()

Відстань, за якою звук більше не чути взагалі. Має ефект, лише якщо встановлено значення більше за 0.0. max_distance працює в тандемі з unit_size. Однак, на відміну від unit_size, поведінка якого залежить від attenuation_model, max_distance завжди працює лінійно. Це можна використовувати, щоб AudioStreamPlayer3D не вимагав мікшування звуку, коли слухач знаходиться далеко, що економить ресурси ЦП.

int max_polyphony = 1 🔗

  • void set_max_polyphony(value: int)

  • int get_max_polyphony()

Максимальна кількість звуків, які цей вузол може відтворювати одночасно. Відтворення додаткових звуків після досягнення цього значення призведе до відрізання найстаріших звуків.

float panning_strength = 1.0 🔗

  • void set_panning_strength(value: float)

  • float get_panning_strength()

Масштабує силу панорамування для цього вузла шляхом множення базового значення ProjectSettings.audio/general/3d_panning_strength на цей коефіцієнт. Якщо продукт має значення 0.0, то стереопанорамування вимкнено, а гучність однакова для всіх каналів. Якщо продукт має версію 1.0, то один із каналів буде вимкнено, коли звук буде розташований точно ліворуч (або праворуч) від слухача.

Двоколонна стереосистема реалізує Стандарт WebAudio для панорамування StereoPannerNode, де гучність дорівнює косинусу половини азимутального кута до вуха.

Для інших схем розташування динаміків, таких як 5.1 та 7.1, реалізовано алгоритм SPCAP (Speaker-Placement Correction Amplitude - корекція амплітуди розташування динаміків).

float pitch_scale = 1.0 🔗

  • void set_pitch_scale(value: float)

  • float get_pitch_scale()

Висота звуку та темп аудіо як множник частоти дискретизації семплу аудіо.

PlaybackType playback_type = 0 🔗

Експериментальний: Ця властивість може бути змінена або усунута у наступних версіях.

Тип відтворення потокового програвача. Якщо встановлено інше значення, ніж значення за замовчуванням, цей тип відтворення буде примусово.

bool playing = false 🔗

  • void set_playing(value: bool)

  • bool is_playing()

Якщо true, аудіо відтворюється або стоїть у черзі для відтворення (див. play()).

AudioStream stream 🔗

Ресурс AudioStream для відтворення.

bool stream_paused = false 🔗

  • void set_stream_paused(value: bool)

  • bool get_stream_paused()

Якщо true, відтворення буде призупинено. Ви можете відновити його, встановивши для stream_paused значення false.

float unit_size = 10.0 🔗

  • void set_unit_size(value: float)

  • float get_unit_size()

Коефіцієнт ефекту ослаблення. Вищі значення роблять звук чутним на більшій відстані.

float volume_db = 0.0 🔗

  • void set_volume_db(value: float)

  • float get_volume_db()

Базовий рівень звуку до загасання, в децибелах.

float volume_linear 🔗

  • void set_volume_linear(value: float)

  • float get_volume_linear()

Базовий рівень звуку до загасання, як лінійне значення.

Примітка: цей учасник змінює volume_db для зручності. Повернене значення еквівалентно результату @GlobalScope.db_to_linear() на volume_db. Налаштування цього члена еквівалентно встановленню volume_db для результату @GlobalScope.linear_to_db() для значення.

Описи методів

float get_playback_position() 🔗

Повертає позицію в AudioStream.

AudioStreamPlayback get_stream_playback() 🔗

Повертає об’єкт AudioStreamPlayback, пов’язаний із цим AudioStreamPlayer3D.

bool has_stream_playback() 🔗

Повертає, чи може AudioStreamPlayer повертати об’єкт AudioStreamPlayback.

void play(from_position: float = 0.0) 🔗

Ставить аудіо в чергу для відтворення на наступному кадрі фізики, починаючи з заданої позиції from_position, за секунди.

void seek(to_position: float) 🔗

Встановлює позицію, з якої буде відтворюватися звук, у секундах.

void stop() 🔗

Зупиняє аудіо.