Sound

class arcade.Sound(file_name: str | Path, streaming: bool = False)

Bases:

Holds playable loaded audio data.

Important

Streaming disables features!

When streaming=True, play() and play_sound():

• raise a RuntimeError if there is already another active playback

• do not support looping

To learn about the restrictions on streaming, please see:

• Streaming Saves Memory

• The pyglet.media.codecs.base.StreamingSource class used internally

To learn about cross-platform loading and file format concerns, please see:

• Arcade’s sound documentation:

  • Streaming or Static Loading?

  • The Most Reliable Formats & Features

  • Loading In-Depth

• The pyglet guide to Playing Sound and Video

Parameters:

• file_name – The path of a file to load, optionally prefixed with a resource handle.

• streaming – If True, attempt to load data from file_path via via streaming.

get_length() → float

Get length of the loaded audio in seconds

get_stream_position(player: Player) → float

Return where we are in the stream. This will reset back to zero when it is done playing.

Parameters:

player – A pyglet Player from play_sound() or Sound.play().

get_volume(player: Player) → float

Get the current volume.

Parameters:

player – A pyglet Player from play_sound() or Sound.play().

Returns:

A volume between 0.0 (silent) and 1.0 (full volume).

is_complete(player: Player) → bool

True if the sound is done playing.

is_playing(player: Player) → bool

True if player is currently playing, otherwise False.

Parameters:

player – A pyglet Player from play_sound() or Sound.play().

Returns:

True if the passed pyglet player is playing.

play(volume: float = 1.0, pan: float = 0.0, loop: bool = False, speed: float = 1.0) → Player

Try to play this Sound and return a pyglet Player.

Important

A Sound with streaming=True loses features!

Neither loop nor simultaneous playbacks will work. See :py;class:Sound and Streaming or Static Loading?.

Parameters:

• volume – Volume (0.0 is silent, 1.0 is loudest).

• pan – Left / right channel balance (-1 is left, 0.0 is center, and 1.0 is right).

• loop – True attempts to restart playback after finishing.

• speed – Change the speed (and pitch) of the sound. Default speed is 1.0.

Returns:

A pyglet Player for this playback.

set_volume(volume: float, player: Player) → None

Set the volume of a sound as it is playing.

Parameters:

• volume – Floating point volume. 0 is silent, 1 is full.

• player – A pyglet Player from play_sound() or Sound.play().

stop(player: Player) → None

Stop and delete() player.

All references to it in the internal table for pyglet.media.Source will be deleted.

Parameters:

player – A pyglet pyglet Player from play_sound() or Sound.play().

arcade.load_sound(path: str | Path, streaming: bool = False) → Sound

Load a file as a Sound data object.

Important

A Sound with streaming=True loses features!

Neither loop nor simultaneous playbacks will work. See :py;class:Sound and Streaming or Static Loading?.

Parameters:

• path – a path which may be prefixed with a resource_handle.

• streaming – Boolean for determining if we stream the sound or load it all into memory. Set to True for long sounds to save memory, False for short sounds to speed playback.

Returns:

ref:playable <sound-basics-playing>` instance of a Sound object.

Return type:

A

arcade.play_sound(sound: Sound | None, volume: float = 1.0, pan: float = 0.0, loop: bool = False, speed: float = 1.0) → Player | None

Try to play the sound and return a pyglet Player.

The sound must be a loaded Sound object. If you pass a path or str, the function will raise a TypeError.

Important

A Sound with streaming=True loses features!

Neither loop nor simultaneous playbacks will work. See :py;class:Sound and Streaming or Static Loading?.

The output and return value depend on whether playback succeeded: .. # Note: substitutions don’t really work inside tables, so the .. # pyglet player below is left as a normal class cross-reference.

Success?	Console output	Return value
No / sound is None	Log a warning	None
Yes	N/A	A pyglet Player

To learn more about the streaming keyword and restrictions, please see:

• Sound

• Change Ongoing Playbacks via Player Objects

• Configure New Playbacks via Keyword Arguments

Parameters:

• sound – A Sound instance or None.

• volume – From 0.0 (silent) to 1.0 (max volume).

• pan – The left / right ear balance (-1 is left, 0 is center,

• right) (and 1 is)

• loop – True makes playback restart each time it reaches the end.

• speed – How fast to play. Slower than 1.0 deepens sound while values higher than 1.0 raise the pitch.

Returns:

A pyglet Player instance for this playback or None if playback failed.

arcade.stop_sound(player: Player) → None

Stop and delete a pyglet Player which is currently playing.

Parameters:

player – A pyglet pyglet Player from play_sound() or Sound.play().