`pyxen.Sound`

Un clip audio court attaché à une Entity en tant que composant.

Les sons sont chargés entièrement en mémoire — utilisez-les pour des effets courts comme les sauts, les coups et les collectes d’objets.

Pour les concepts audio, consultez Audio.

Constructeur

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

filename est l’unique argument positionnel : le nom d’un asset audio WAV du projet. Les cinq autres sont réservés aux mots-clés (keyword-only) et fixent la valeur de départ de la propriété du même nom (voir Propriétés du composant).

Paramètres

Paramètre	Type	Description
`filename`	`str`	Nom de l’asset WAV, sans son extension ; un son d’une banque de sons s’écrit `bank/sound`
`volume`	`float`	Gain de départ. `1.0` par défaut
`pan`	`float`	Position stéréo de départ, de `-1.0` à `1.0`. `0.0` par défaut
`loop`	`bool`	Rejouer le son quand il se termine. `False` par défaut
`delay`	`float`	Secondes de silence avant le départ. `0.0` par défaut
`pitch`	`float`	Vitesse de lecture, de `0.25` à `4.0`. `1.0` par défaut

Exemple

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

Attacher un Sound

Lors du spawn :

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

Ou plus tard :

entity.sound = Sound("jump")

L’assignation d’un son lance la lecture immédiatement.

Propriétés du composant

Accès via entity.sound :

Propriété	Type	L/E	Description
`loop`	`bool`	L/E	Activer la lecture en boucle
`volume`	`float`	L/E	Gain (minimum 0.0)
`pan`	`float`	L/E	Panoramique stéréo (-1.0 à 1.0)
`time`	`float`	R/W	Position de lecture actuelle (secondes)
`delay`	`float`	R/W	Secondes de silence avant le démarrage
`pitch`	`float`	R/W	Vitesse de lecture (0.25 à 4.0)
`duration`	`float`	L	Durée totale (secondes)
`finished`	`bool`	L	True lorsque la lecture est terminée

`loop`

entity.sound.loop = True

Lorsqu’activé, le son redémarre automatiquement après la fin de la lecture.

`volume`

entity.sound.volume = 0.5

Les valeurs inférieures à 0.0 sont limitées à 0.0.

`pan`

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

Limité à la plage -1.0 à 1.0.

`time`

t = entity.sound.time
entity.sound.time = 0.25     # saute le premier quart de seconde

Position de lecture en secondes. Lui affecter une valeur déplace la tête de lecture ; au-delà de la fin elle est ramenée à la fin, et déplacer un son terminé le relance.

`delay`

entity.sound.delay = 0.002   # démarre dans deux millisecondes

Secondes de silence avant que le son ne démarre. Contrairement à time, rien n’est sauté : le son commence bien à son premier échantillon, simplement plus tard.

C’est l’outil à utiliser quand le même effet est déclenché plusieurs fois dans une frame. Des copies d’une même forme d’onde qui démarrent sur le même échantillon s’additionnent en phase : deux copies donnent le double d’amplitude, pas 1,4 fois, et dix feront dépasser le niveau maximal quel que soit le soin apporté à chacune. Quelques millisecondes d’écart suffisent à les décorréler, et c’est bien trop court pour s’entendre comme un trou.

Un délai sépare les attaques : il est donc surtout utile pour des effets percussifs courts et ne change rien à un son tenu.

`pitch`

entity.sound.pitch = 2.0     # une octave plus haut
entity.sound.pitch = 0.5     # une octave plus bas

La vitesse à laquelle le son est joué : 1.0 tel qu’enregistré, 2.0 une octave plus haut et en deux fois moins de temps, 0.5 une octave plus bas et deux fois plus long. Les valeurs sont limitées de 0.25 à 4.0, deux octaves de part et d’autre. Un même son à une hauteur qui monte fait une gamme : une chaîne ou une série n’a besoin que d’un son, pas d’un par note :

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

time et duration restent dans les secondes du son lui-même : à pitch 2.0, un son d’une seconde dure une demi-seconde, pendant que son time va de 0.0 à 1.0.

`duration`

d = entity.sound.duration

Lecture seule. Durée totale du son en secondes, tel qu’enregistré (quel que soit son pitch).

`finished`

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

Lecture seule. True lorsque le son a fini de jouer (et que loop est False).

Format

Les assets audio doivent être des fichiers WAV.

Erreurs courantes

Nom de fichier manquant

Sound()

ValueError: Sound must have a file

Asset invalide

Sound("nonexistent")

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

Le jeu s’arrête sur cette erreur. Nommez l’asset sans son extension .wav ; un son d’une banque de sons se nomme bank/sound.