`pyxen.Sound`

A short audio clip attached to an Entity as a component.

Sounds are loaded entirely into memory — use them for short effects like jumps, hits, and pickups.

For audio concepts, see Audio.

Constructor

Sound(filename)

One required positional argument: the name of a WAV audio asset in the project.

Parameters

Parameter	Type	Description
`filename`	`str`	Name of the WAV asset

Example

jump_sound = Sound("jump")

Attaching a Sound

During spawn:

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

Or later:

entity.sound = Sound("jump")

Assigning a sound starts playback immediately.

Component Properties

Access via entity.sound:

Property	Type	R/W	Description
`loop`	`bool`	R/W	Enable looping
`volume`	`float`	R/W	Gain (clamped >= 0.0)
`pan`	`float`	R/W	Stereo panning (-1.0 to 1.0)
`time`	`float`	R/W	Current playback position (seconds)
`delay`	`float`	R/W	Seconds of silence before it starts
`duration`	`float`	R	Total length (seconds)
`finished`	`bool`	R	True when playback has completed

`loop`

entity.sound.loop = True

When enabled, the sound restarts automatically after finishing.

`volume`

entity.sound.volume = 0.5

Values below 0.0 are clamped to 0.0.

`pan`

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

Clamped to the range -1.0 to 1.0.

`time`

t = entity.sound.time
entity.sound.time = 0.25     # skip the first quarter second

The playback position in seconds. Assigning to it seeks; a value past the end is clamped to the end, and seeking a finished sound starts it playing again.

`delay`

entity.sound.delay = 0.002   # start two milliseconds from now

Seconds of silence before the sound starts. Unlike time this does not skip anything — the sound still begins at its first sample, it just begins later.

This is what to reach for when the same effect fires several times in one frame. Copies of one waveform that start on the same sample add up in phase: two are twice the amplitude, not 1.4 times, and ten will take a mix past full scale however carefully each one was set. A few milliseconds apart is enough to decorrelate them and far too short to hear as a gap.

for i, brick in enumerate(broken):
    e = world.spawn(sound=Sound("brick"))
    e.sound.delay = i * 0.002

What a delay separates is the attacks, so it helps most with short percussive effects and does nothing for a sustained tone — once every copy of a steady sound is playing, they sum to the same level whatever order they started in.

`duration`

d = entity.sound.duration

Read-only. Total length of the sound in seconds.

`finished`

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

Read-only. True when the sound has finished playing (and loop is False).

Format

Sound assets must be WAV files.

Common Errors

Missing Filename

Sound()

ValueError: Sound must have a file

Invalid Asset

Sound("nonexistent")

The sound object is created but playback will fail silently with a warning logged.

Mini samples

Open from Samples & Tutorials inside Pyxen:

Sound() one-shot — Click to play a short WAV.
sound.loop / pan / volume — Continuous sound — mouse drives stereo pan.