`pyxen.Music`

A streamed audio track attached to an Entity as a component.

Music is decoded on-demand (OGG Vorbis), making it suitable for longer tracks like background music and ambience.

For audio concepts, see Audio.

Constructor

Music(filename)

One required positional argument: the name of an OGG Vorbis audio asset in the project.

Parameter	Type	Description
`filename`	`str`	Name of the OGG asset

theme = Music("theme")

During spawn:

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

Or later:

entity.music = Music("theme")

Assigning music starts playback immediately.

Access via entity.music:

Property	Type	R/W	Description
`loop`	`bool`	R/W	Enable looping
`volume`	`float`	R/W	Gain (clamped >= 0.0)
`pan`	`float`	R/W	Stereo panning (-1.0 to 1.0)
`time`	`float`	R	Current playback position (seconds)
`duration`	`float`	R	Total length (seconds)
`finished`	`bool`	R	True when playback has completed

entity.music.loop = True

When enabled, the track restarts automatically after finishing. Typical for background music.

entity.music.volume = 0.5

Values below 0.0 are clamped to 0.0.

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

Clamped to the range -1.0 to 1.0.

t = entity.music.time

Read-only. Current playback position in seconds.

d = entity.music.duration

Read-only. Total length of the track in seconds.

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

Read-only. True when the track has finished playing (and loop is False).

Music assets must be OGG Vorbis files.

Unlike Sound (WAV, loaded entirely into memory), Music is streamed and decoded on-demand — better suited for longer audio.

Music()

ValueError: Music must have a file

Music("nonexistent")

The music object is created but playback will fail silently with a warning logged.