`pyxen.Sound`

附加到 Entity 作为组件的短音频片段。

Sound 完全加载到内存中——用于跳跃、击中和拾取等短效果。

有关音频概念，请参见音频。

构造函数

Sound(filename, *, volume=1.0, pan=0.0, loop=False, delay=0.0, pitch=1.0)

filename 是唯一的位置参数：项目中 WAV 音频素材的名称。其余五个只能用关键字传入，用来设定同名属性的初始值（见组件属性）。

参数	类型	描述
`filename`	`str`	WAV 素材的名称，不含扩展名；音效库中的音效写作 `bank/sound`
`volume`	`float`	初始增益。默认为 `1.0`
`pan`	`float`	初始立体声位置，`-1.0` 到 `1.0`。默认为 `0.0`
`loop`	`bool`	结束后重新播放。默认为 `False`
`delay`	`float`	开始播放前的静音秒数。默认为 `0.0`
`pitch`	`float`	播放速率，`0.25` 到 `4.0`。默认为 `1.0`

jump_sound = Sound("jump")
quiet_echo = Sound("jump", volume=0.3, delay=0.15)
high_jump = Sound("jump", pitch=2.0)

在生成时：

sfx = world.spawn(sound=Sound("jump"))

或稍后：

entity.sound = Sound("jump")

分配声音会立即开始播放。

通过 entity.sound 访问：

entity.sound.loop = True

启用后，声音结束后自动重新开始。

entity.sound.volume = 0.5

低于 0.0 的值被限制为 0.0。

entity.sound.pan = -1.0  # full left
entity.sound.pan =  1.0  # full right
entity.sound.pan =  0.0  # center

限制在 -1.0 到 1.0 范围内。

t = entity.sound.time
entity.sound.time = 0.25     # 跳过开头的四分之一秒

播放位置（秒）。为它赋值即可定位；超过结尾的值会被限制到结尾，而对已经结束的声音定位会让它重新播放。

entity.sound.delay = 0.002   # 两毫秒后开始

声音开始前的静音秒数。与 time 不同，它不会跳过任何内容——声音仍然从第一个采样开始，只是开始得更晚。

当同一个音效在一帧内被触发多次时，应该用它。 同一波形的多个副本若从同一个采样开始，就会同相叠加：两个是两倍振幅而不是 1.4 倍，十个则无论每一个的音量调得多仔细，都会让混音超出满刻度。相隔几毫秒就足以让它们去相关，而这个长度远不足以被听成一个空隙。

延迟分开的是起音，所以它对短促的打击类音效最有效，对持续音则毫无作用。

entity.sound.pitch = 2.0     # 升高一个八度
entity.sound.pitch = 0.5     # 降低一个八度

声音播放的快慢：1.0 按录制原样，2.0 升高一个八度、用一半的时间播完，0.5 降低一个八度、时长加倍。数值限制在 0.25 到 4.0 之间，上下各两个八度。同一个声音音高逐步升高就是一段音阶，所以连锁或连击只需要一个声音，而不必每个音符各做一个：

def on_match(step):
    world.spawn(sound=Sound("match", pitch=1 + 0.12 * step))

time 和 duration 仍按声音本身的秒数计算：pitch 为 2.0 时，一秒长的声音半秒就播完，同时它的 time 从 0.0 走到 1.0。

d = entity.sound.duration

只读。声音按录制原样的总时长（秒），与 pitch 无关。

if entity.sound.finished:
    world.destroy(entity)

只读。当声音播放完成时为 True（且 loop 为 False）。

Sound 素材必须是 WAV 文件。

Sound()

ValueError: Sound must have a file

Sound("nonexistent")

ValueError: Sound 'nonexistent' not found. For sounds inside a sound bank, use 'bank/sound'.

游戏会因此错误而停止。素材名不带 .wav 扩展名；声音库中的声音名为 bank/sound。