Sound

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

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:

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

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[source]

Get length of the loaded audio in seconds

get_stream_position(player: Player) → float[source]

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[source]

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[source]

True if the sound is done playing.

is_playing(player: Player) → bool[source]

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[source]

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 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[source]

Set the volume of a sound as it is playing.

Parameters:
source: Source

The pyglet.media.Source object that holds the audio data.

stop(player: Player) → None[source]

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[source]

Load a file as a Sound data object.

Important

A Sound with streaming=True loses features!

Neither loop nor simultaneous playbacks will work. See 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:

A playable instance of a Sound object.

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

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 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:

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[source]

Stop and delete a pyglet Player which is currently playing.

Parameters:

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