`pyxen.Music`

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

Music is decoded on-demand, 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 a music asset in the project, without its file extension.

Parameters

Parameter	Type	Description
`filename`	`str`	Name of the music asset, without its extension

Example

theme = Music("theme")

Attaching Music

During spawn:

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

Or later:

entity.music = Music("theme")

Assigning music starts playback immediately.

Component Properties

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

`loop`

entity.music.loop = True

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

`volume`

entity.music.volume = 0.5

Values below 0.0 are clamped to 0.0.

`pan`

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.

`time`

t = entity.music.time

Read-only. Current playback position in seconds.

`duration`

d = entity.music.duration

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

`finished`

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

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

Format

A music asset can be OGG Vorbis (.ogg), MIDI (.mid, .midi), or a tracker module — ProTracker (.mod), FastTracker II (.xm), Impulse Tracker (.it) or Scream Tracker 3 (.s3m).

The asset is found by base name, so Music("theme") picks up theme.ogg, theme.mod, or whichever of those extensions exists in the project. Passing the extension is the most common mistake: Music("theme.ogg") looks for theme.ogg.ogg and raises.

A tracker module is often a few kilobytes where the same tune as OGG is megabytes, and it loops seamlessly by construction — a good fit for a small game.

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

Common Errors

Missing Filename

Music()

ValueError: Music must have a file

Invalid Asset

Music("nonexistent")
Music("theme.ogg")     # the extension belongs on the file, not in the name

ValueError: Music 'nonexistent' not found. Use the asset name without its extension (.ogg, .mid, .mod, .xm, .it, .s3m).

Mini samples

Open from Samples & Tutorials inside Pyxen:

Music() playback — Stream a MIDI file from the project.
music.finished — Detect the end of a one-shot music track.