pyxen.Music

附加到 Entity 作为组件的流式音频轨道。

Music 按需解码（OGG Vorbis），适合较长的曲目如背景音乐和环境音。

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

构造函数

Music(filename)

一个必需的位置参数：项目中 OGG Vorbis 音频素材的名称。

参数

参数类型描述
filenamestrOGG 素材的名称

示例

theme = Music("theme")

附加 Music

在生成时：

bgm = world.spawn(music=Music("theme"))

或稍后：

entity.music = Music("theme")

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

组件属性

通过 entity.music 访问：

属性类型读/写描述
loopbool读/写启用循环
volumefloat读/写增益（限制 >= 0.0）
panfloat读/写立体声声像（-1.0 到 1.0）
timefloat只读当前播放位置（秒）
durationfloat只读总时长（秒）
finishedbool只读播放完成时为 True

loop

entity.music.loop = True

启用后，曲目结束后自动重新开始。适用于背景音乐。

volume

entity.music.volume = 0.5

低于 0.0 的值被限制为 0.0。

pan

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

限制在 -1.0 到 1.0 范围内。

time

t = entity.music.time

只读。当前播放位置（秒）。

duration

d = entity.music.duration

只读。曲目总时长（秒）。

finished

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

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

格式

Music 素材必须是 OGG Vorbis 文件。

与 Sound（WAV，完全加载到内存）不同，Music 是流式且按需解码的——更适合较长的音频。

常见错误

缺少文件名

Music()
ValueError: Music must have a file

无效素材

Music("nonexistent")

音乐对象会被创建，但播放会静默失败并记录警告。