`pyxen.Sound`

Ein kurzer Audioclip, der einem Entity als Komponente angehängt wird.

Sounds werden vollständig in den Speicher geladen — verwende sie für kurze Effekte wie Sprünge, Treffer und Einsammelgeräusche.

Audio-Konzepte findest du unter Audio.

Konstruktor

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

filename ist das einzige Positionsargument: der Name eines WAV-Audio-Assets im Projekt. Die anderen fünf sind reine Schlüsselwortargumente und setzen den Startwert der gleichnamigen Eigenschaft (siehe Komponenteneigenschaften).

Parameter

Parameter	Typ	Beschreibung
`filename`	`str`	Name des WAV-Assets, ohne Endung; ein Sound in einer Sound-Bank heißt `bank/sound`
`volume`	`float`	Start-Lautstärke. Standard `1.0`
`pan`	`float`	Start-Stereoposition, `-1.0` bis `1.0`. Standard `0.0`
`loop`	`bool`	Beim Ende neu starten. Standard `False`
`delay`	`float`	Sekunden Stille vor dem Start. Standard `0.0`
`pitch`	`float`	Wiedergabegeschwindigkeit, `0.25` bis `4.0`. Standard `1.0`

Beispiel

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

Einen Sound anhängen

Beim Spawn:

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

Oder nachträglich:

entity.sound = Sound("jump")

Das Zuweisen eines Sounds startet die Wiedergabe sofort.

Komponenteneigenschaften

Zugriff über entity.sound:

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`	R/W	Aktuelle Wiedergabeposition (Sekunden)
`delay`	`float`	R/W	Sekunden Stille vor dem Start
`pitch`	`float`	R/W	Wiedergabegeschwindigkeit (0.25 bis 4.0)
`duration`	`float`	L	Gesamtlänge (Sekunden)
`finished`	`bool`	L	True wenn Wiedergabe abgeschlossen

`loop`

entity.sound.loop = True

Wenn aktiviert, startet der Sound nach dem Ende automatisch neu.

`volume`

entity.sound.volume = 0.5

Werte unter 0.0 werden auf 0.0 begrenzt.

`pan`

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

Begrenzt auf den Bereich -1.0 bis 1.0.

`time`

t = entity.sound.time
entity.sound.time = 0.25     # überspringt die erste Viertelsekunde

Die Wiedergabeposition in Sekunden. Eine Zuweisung springt an diese Stelle; Werte hinter dem Ende werden auf das Ende begrenzt, und ein beendeter Ton läuft danach wieder.

`delay`

entity.sound.delay = 0.002   # startet in zwei Millisekunden

Sekunden Stille, bevor der Ton startet. Anders als bei time wird nichts übersprungen — der Ton beginnt weiterhin bei seinem ersten Sample, nur später.

Das ist das Mittel der Wahl, wenn derselbe Effekt mehrfach in einem Frame ausgelöst wird. Kopien einer Wellenform, die auf demselben Sample beginnen, addieren sich phasengleich: zwei ergeben die doppelte Amplitude, nicht das 1,4-Fache, und zehn treiben jede Mischung über die Vollaussteuerung. Ein paar Millisekunden Abstand genügen, um sie zu dekorrelieren, und sind viel zu kurz, um als Lücke hörbar zu sein.

Eine Verzögerung trennt die Attacks und hilft daher vor allem bei kurzen perkussiven Effekten; bei einem gehaltenen Ton bewirkt sie nichts.

`pitch`

entity.sound.pitch = 2.0     # eine Oktave höher
entity.sound.pitch = 0.5     # eine Oktave tiefer

Wie schnell der Sound abgespielt wird: 1.0 wie aufgenommen, 2.0 eine Oktave höher und in der halben Zeit, 0.5 eine Oktave tiefer und doppelt so lang. Werte werden auf 0.25 bis 4.0 begrenzt, zwei Oktaven in jede Richtung. Ein Sound mit steigender Tonhöhe ergibt eine Tonleiter, also braucht eine Kette oder eine Serie einen Sound, nicht einen pro Note:

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

time und duration bleiben in den Sekunden des Sounds selbst: Bei pitch 2.0 spielt ein einsekündiger Sound eine halbe Sekunde, während sein time von 0.0 bis 1.0 läuft.

`duration`

d = entity.sound.duration

Nur lesbar. Gesamtlänge des Sounds in Sekunden, wie aufgenommen (unabhängig von pitch).

`finished`

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

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

Format

Sound-Assets müssen WAV-Dateien sein.

Häufige Fehler

Fehlender Dateiname

Sound()

ValueError: Sound must have a file

Ungültiges Asset

Sound("nonexistent")

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

Das Spiel hält mit diesem Fehler an. Gib den Asset-Namen ohne die Endung .wav an; ein Sound aus einer Soundbank heißt bank/sound.