`pyxen.Music`

Ein gestreamter Audiotrack, der einem Entity als Komponente angehängt wird.

Music wird bei Bedarf dekodiert und eignet sich für längere Tracks wie Hintergrundmusik und Umgebungsklänge.

Audio-Konzepte findest du unter Audio.

Konstruktor

Music(filename)

Ein erforderliches positionelles Argument: der Name eines Musik-Assets im Projekt, ohne Dateiendung.

Parameter

Parameter	Typ	Beschreibung
`filename`	`str`	Name des Musik-Assets, ohne Endung

Beispiel

theme = Music("theme")

Music anhängen

Beim Spawn:

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

Oder nachträglich:

entity.music = Music("theme")

Das Zuweisen von Music startet die Wiedergabe sofort.

Komponenteneigenschaften

Zugriff über entity.music:

Eigenschaft	Typ	L/S	Beschreibung
`loop`	`bool`	L/S	Schleife aktivieren
`volume`	`float`	L/S	Lautstärke (begrenzt >= 0.0)
`pan`	`float`	L/S	Stereo-Panning (-1.0 bis 1.0)
`time`	`float`	L	Aktuelle Wiedergabeposition (Sekunden)
`duration`	`float`	L	Gesamtlänge (Sekunden)
`finished`	`bool`	L	True wenn Wiedergabe abgeschlossen

`loop`

entity.music.loop = True

Wenn aktiviert, startet der Track nach dem Ende automatisch neu. Typisch für Hintergrundmusik.

`volume`

entity.music.volume = 0.5

Werte unter 0.0 werden auf 0.0 begrenzt.

`pan`

entity.music.pan = -1.0  # ganz links
entity.music.pan =  1.0  # ganz rechts
entity.music.pan =  0.0  # Mitte

Begrenzt auf den Bereich -1.0 bis 1.0.

`time`

t = entity.music.time

Nur lesbar. Aktuelle Wiedergabeposition in Sekunden.

`duration`

d = entity.music.duration

Nur lesbar. Gesamtlänge des Tracks in Sekunden.

`finished`

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

Nur lesbar. True wenn der Track fertig abgespielt wurde (und loop False ist).

Format

Ein Musik-Asset kann OGG Vorbis (.ogg), MIDI (.mid, .midi) oder ein Tracker-Modul sein — ProTracker (.mod), FastTracker II (.xm), Impulse Tracker (.it) oder Scream Tracker 3 (.s3m).

Das Asset wird über den Basisnamen gefunden: Music("theme") findet theme.ogg, theme.mod oder welche dieser Endungen im Projekt vorhanden ist. Die Endung mitzugeben ist der häufigste Fehler — Music("theme.ogg") sucht nach theme.ogg.ogg und löst eine Ausnahme aus.

Ein Tracker-Modul ist oft nur wenige Kilobyte groß, wo dasselbe Stück als OGG mehrere Megabyte belegt, und es loopt bauartbedingt nahtlos — ideal für ein kleines Spiel.

Im Gegensatz zu Sound (WAV, vollständig in den Speicher geladen) wird Music gestreamt und bei Bedarf dekodiert — besser geeignet für längere Audiodateien.

Häufige Fehler

Fehlender Dateiname

Music()

ValueError: Music must have a file

Ungültiges Asset

Music("nonexistent")
Music("theme.ogg")     # die Endung gehört an die Datei, nicht in den Namen

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