`pyxen.Music`

Una pista de audio en streaming adjunta a un Entity como componente.

La música se decodifica bajo demanda, lo que la hace adecuada para pistas largas como música de fondo y ambientación.

Para conceptos de audio, consulta Audio.

Constructor

Music(filename)

Un argumento posicional requerido: el nombre de un recurso musical del proyecto, sin su extensión de archivo.

Parámetros

Parámetro	Tipo	Descripción
`filename`	`str`	Nombre del recurso musical, sin extensión

Ejemplo

theme = Music("theme")

Adjuntar Music

Durante spawn:

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

O después:

entity.music = Music("theme")

Asignar música inicia la reproducción inmediatamente.

Propiedades del componente

Acceso mediante entity.music:

Propiedad	Tipo	L/E	Descripción
`loop`	`bool`	L/E	Activar bucle
`volume`	`float`	L/E	Ganancia (limitada >= 0.0)
`pan`	`float`	L/E	Paneo estéreo (-1.0 a 1.0)
`time`	`float`	L	Posición actual de reproducción (segundos)
`duration`	`float`	L	Duración total (segundos)
`finished`	`bool`	L	True cuando la reproducción ha terminado

`loop`

entity.music.loop = True

Cuando está activado, la pista se reinicia automáticamente al terminar. Típico para música de fondo.

`volume`

entity.music.volume = 0.5

Los valores por debajo de 0.0 se limitan a 0.0.

`pan`

entity.music.pan = -1.0  # totalmente a la izquierda
entity.music.pan =  1.0  # totalmente a la derecha
entity.music.pan =  0.0  # centro

Limitado al rango -1.0 a 1.0.

`time`

t = entity.music.time

Solo lectura. Posición actual de reproducción en segundos.

`duration`

d = entity.music.duration

Solo lectura. Duración total de la pista en segundos.

`finished`

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

Solo lectura. True cuando la pista ha terminado de reproducirse (y loop es False).

Formato

Un recurso musical puede ser OGG Vorbis (.ogg), MIDI (.mid, .midi) o un módulo de tracker: ProTracker (.mod), FastTracker II (.xm), Impulse Tracker (.it) o Scream Tracker 3 (.s3m).

El recurso se busca por su nombre base: Music("theme") encuentra theme.ogg, theme.mod o la de esas extensiones que exista en el proyecto. Pasar la extensión es el error más frecuente: Music("theme.ogg") busca theme.ogg.ogg y lanza una excepción.

Un módulo de tracker suele ocupar unos pocos kilobytes donde la misma pieza en OGG ocupa megabytes, y se repite sin costuras por construcción — ideal para un juego pequeño.

A diferencia de Sound (WAV, cargado completamente en memoria), Music se transmite y decodifica bajo demanda — más adecuado para audio largo.

Errores comunes

Nombre de archivo faltante

Music()

ValueError: Music must have a file

Recurso inválido

Music("nonexistent")
Music("theme.ogg")     # la extensión va en el archivo, no en el nombre

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