Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

AudioStreamPlayer2D

继承: Node2D < CanvasItem < Node < Object

在 2D 空间中播放与位置相关的声音。

描述

播放随与监听者的距离增大而衰减的音频。

默认情况下,音频是从屏幕中心收听的。要修改这个位置,可以在场景中添加一个 AudioListener2D 节点,并通过调用 AudioListener2D.make_current 将其启用。

另请参阅 AudioStreamPlayer 以非定位的方式播放声音。

注意:隐藏 AudioStreamPlayer2D 节点并不能禁用其音频输出。要暂时禁用 AudioStreamPlayer2D 的音频输出,请将 volume_db 设置为非常低的值,如 -100(人的听觉听不到)。

教程

属性

int

area_mask

1

float

attenuation

1.0

bool

autoplay

false

StringName

bus

&"Master"

float

max_distance

2000.0

int

max_polyphony

1

float

panning_strength

1.0

float

pitch_scale

1.0

bool

playing

false

AudioStream

stream

bool

stream_paused

false

float

volume_db

0.0

方法

float

get_playback_position ( )

AudioStreamPlayback

get_stream_playback ( )

bool

has_stream_playback ( )

void

play ( float from_position=0.0 )

void

seek ( float to_position )

void

stop ( )


信号

finished ( )

当音频停止播放时发出。


属性说明

int area_mask = 1

  • void set_area_mask ( int value )

  • int get_area_mask ( )

决定对混响及音频总线效果有影响的 Area2D 层。可使用区域对 AudioStream 进行重定向,使其在特定的音频总线中播放。一个例子是可以用来制作“水域”,将水中播放的声音重定向至单独的音频总线,让声音听起来像是在水下播放。


float attenuation = 1.0

  • void set_attenuation ( float value )

  • float get_attenuation ( )

以该属性为指数,将音量随着距离的增加而衰减。


bool autoplay = false

  • void set_autoplay ( bool value )

  • bool is_autoplay_enabled ( )

如果为 true,在添加到场景树时将播放音频。


StringName bus = &"Master"

这个音频在哪个总线上播放。

注意:设置这个属性时,请记住它并不会对给定的名称是否与现有总线匹配进行校验。这是因为音频总线布局可以在设置这个属性后再加载。如果这个给定的名称在运行时无法解析,就会回退到 "Master"


float max_distance = 2000.0

  • void set_max_distance ( float value )

  • float get_max_distance ( )

音频仍可听到的最大距离。


int max_polyphony = 1

  • void set_max_polyphony ( int value )

  • int get_max_polyphony ( )

该节点可以同时播放的最大声音数。达到此值后,播放额外的声音将切断最旧的声音。


float panning_strength = 1.0

  • void set_panning_strength ( float value )

  • float get_panning_strength ( )

通过将基础 ProjectSettings.audio/general/2d_panning_strength 乘以该因子,来缩放该节点的声像强度。与较低的值相比,较高的值将从左到右更显著地声像移动音频。


float pitch_scale = 1.0

  • void set_pitch_scale ( float value )

  • float get_pitch_scale ( )

音频的音高和节奏,作为音频样本的采样率的倍数。


bool playing = false

  • bool is_playing ( )

如果为 true,则音频正在播放,或者已加入播放队列(见 play)。


AudioStream stream

要播放的 AudioStream 对象。


bool stream_paused = false

  • void set_stream_paused ( bool value )

  • bool get_stream_paused ( )

如果为 true,则播放会暂停。你可以通过将 stream_paused 设置为 false来恢复它。


float volume_db = 0.0

  • void set_volume_db ( float value )

  • float get_volume_db ( )

衰减前的基础音量。


方法说明

float get_playback_position ( )

返回 AudioStream 中的位置。


AudioStreamPlayback get_stream_playback ( )

返回与该 AudioStreamPlayer2D 相关联的 AudioStreamPlayback 对象。


bool has_stream_playback ( )

返回该 AudioStreamPlayer 是否能够返回 AudioStreamPlayback 对象。


void play ( float from_position=0.0 )

将要播放的音频入队,将在下一物理帧从给定的位置 from_position 开始播放,单位为秒。


void seek ( float to_position )

设置音频的播放位置,以秒为单位。


void stop ( )

停止音频。