`pyxen.Sound`

Un clip de audio corto adjunto a un Entity como componente.

Los sonidos se cargan completamente en memoria — úsalos para efectos cortos como saltos, golpes y recolecciones.

Para conceptos de audio, consulta Audio.

Constructor

Sound(filename, *, volume=1.0, pan=0.0, loop=False, delay=0.0, pitch=1.0)

filename es el único argumento posicional: el nombre de un recurso de audio WAV del proyecto. Los otros cinco son solo por palabra clave y fijan el valor inicial de la propiedad del mismo nombre (consulta Propiedades del componente).

Parámetros

Parámetro	Tipo	Descripción
`filename`	`str`	Nombre del recurso WAV, sin su extensión; un sonido dentro de un banco de sonidos es `bank/sound`
`volume`	`float`	Ganancia inicial. Por defecto `1.0`
`pan`	`float`	Posición estéreo inicial, de `-1.0` a `1.0`. Por defecto `0.0`
`loop`	`bool`	Repetir al terminar. Por defecto `False`
`delay`	`float`	Segundos de silencio antes de empezar. Por defecto `0.0`
`pitch`	`float`	Velocidad de reproducción, de `0.25` a `4.0`. Por defecto `1.0`

Ejemplo

jump_sound = Sound("jump")
quiet_echo = Sound("jump", volume=0.3, delay=0.15)
high_jump = Sound("jump", pitch=2.0)

Adjuntar un Sound

Durante spawn:

sfx = world.spawn(sound=Sound("jump"))

O después:

entity.sound = Sound("jump")

Asignar un sonido inicia la reproducción inmediatamente.

Propiedades del componente

Acceso mediante entity.sound:

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`	R/W	Posición de reproducción actual (segundos)
`delay`	`float`	R/W	Segundos de silencio antes de empezar
`pitch`	`float`	R/W	Velocidad de reproducción (0.25 a 4.0)
`duration`	`float`	L	Duración total (segundos)
`finished`	`bool`	L	True cuando la reproducción ha terminado

`loop`

entity.sound.loop = True

Cuando está activado, el sonido se reinicia automáticamente al terminar.

`volume`

entity.sound.volume = 0.5

Los valores por debajo de 0.0 se limitan a 0.0.

`pan`

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

Limitado al rango -1.0 a 1.0.

`time`

t = entity.sound.time
entity.sound.time = 0.25     # salta el primer cuarto de segundo

La posición de reproducción en segundos. Asignarle un valor busca esa posición; más allá del final se limita al final, y buscar en un sonido terminado vuelve a reproducirlo.

`delay`

entity.sound.delay = 0.002   # empieza dentro de dos milisegundos

Segundos de silencio antes de que el sonido empiece. A diferencia de time, no se salta nada: el sonido sigue empezando en su primera muestra, solo que más tarde.

Es lo que hay que usar cuando el mismo efecto se dispara varias veces en un fotograma. Las copias de una misma onda que empiezan en la misma muestra se suman en fase: dos dan el doble de amplitud, no 1,4 veces, y diez llevarán la mezcla más allá de la escala completa por mucho cuidado que se haya puesto en cada una. Unos pocos milisegundos de separación bastan para descorrelacionarlas, y son demasiado poco para oírse como un hueco.

Un retardo separa los ataques, así que ayuda sobre todo con efectos percusivos cortos y no hace nada con un tono sostenido.

`pitch`

entity.sound.pitch = 2.0     # una octava más alto
entity.sound.pitch = 0.5     # una octava más bajo

La velocidad a la que se reproduce el sonido: 1.0 tal como se grabó, 2.0 una octava más alto y en la mitad de tiempo, 0.5 una octava más bajo y el doble de largo. Los valores se limitan de 0.25 a 4.0, dos octavas hacia cada lado. Un mismo sonido con un tono que sube forma una escala, así que una cadena o una racha necesita un sonido, no uno por nota:

def on_match(step):
    world.spawn(sound=Sound("match", pitch=1 + 0.12 * step))

time y duration siguen en los segundos del propio sonido: con pitch 2.0, un sonido de un segundo suena medio segundo mientras su time va de 0.0 a 1.0.

`duration`

d = entity.sound.duration

Solo lectura. Duración total del sonido en segundos, tal como se grabó (sea cual sea su pitch).

`finished`

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

Solo lectura. True cuando el sonido ha terminado de reproducirse (y loop es False).

Formato

Los recursos de sonido deben ser archivos WAV.

Errores comunes

Nombre de archivo faltante

Sound()

ValueError: Sound must have a file

Recurso inválido

Sound("nonexistent")

ValueError: Sound 'nonexistent' not found. For sounds inside a sound bank, use 'bank/sound'.

El juego se detiene con este error. Nombra el recurso sin su extensión .wav; un sonido dentro de un banco de sonidos se llama bank/sound.