psychos.sound.Player

class psychos.sound.Player

Bases: EventDispatcher

High-level sound and video player.

__init__() → None

Initialize the Player with a MasterClock.

Methods

__init__()	Initialize the Player with a MasterClock.
delete()	Release the resources acquired by this player.
dispatch_event(event_type, *args)	Dispatch an event to the attached event handlers.
event(*args)	Function decorator for an event handler.
next_source()	Move immediately to the next source in the current playlist.
on_driver_reset()	The audio driver has been reset.
on_eos()	The current source ran out of data.
on_player_eos()	The player ran out of sources.
on_player_next_source()	The player starts to play the next queued source in the playlist.
pause()	Pause playback of the current source.
play()	Begin playing the current source.
pop_handlers()	Pop the top level of event handlers off the stack.
post_event(event_type, *args)	Post an event to the main application thread.
push_handlers(*args, **kwargs)	Push a new level onto the handler stack, and add 0 or more handlers.
queue(source)	Queue the source on this player.
register_event_type(name)	Register an event type with the dispatcher.
remove_handler(name, handler)	Remove a single event handler.
remove_handlers(*args, **kwargs)	Remove event handlers from the event stack.
seek(timestamp)	Seek for playback to the indicated timestamp on the current source.
seek_next_frame()	Step forwards one video frame in the current source.
set_handler(name, handler)	Attach a single event handler.
set_handlers(*args, **kwargs)	Attach one or more event handlers to the top level of the handler stack.
update_texture([dt])	Manually update the texture from the current source.

Attributes

cone_inner_angle	The interior angle of the inner cone.
cone_orientation	The direction of the sound in 3D space.
cone_outer_angle	The interior angle of the outer cone.
cone_outer_gain	The gain applied outside the cone.
event_types
max_distance	The distance at which no further attenuation is applied.
min_distance	The distance beyond which the sound volume drops by half, and within which no attenuation is applied.
pitch	The pitch shift to apply to the sound.
playing	The current playing state.
position	The position of the sound in 3D space.
source	Read-only.
texture	Get the texture for the current video frame, if any.
time	Read-only.
volume	The volume level of sound playback.
loop	Loop the current source indefinitely or until next_source() is called.

cone_inner_angle

The interior angle of the inner cone.

The angle is given in degrees, and defaults to 360. When the listener is positioned within the volume defined by the inner cone, the sound is played at normal gain (see volume).

cone_orientation

The direction of the sound in 3D space.

The direction is specified as a tuple of floats (x, y, z), and has no unit. The default direction is (0, 0, -1). Directional effects are only noticeable if the other cone properties are changed from their default values.

cone_outer_angle

The interior angle of the outer cone.

The angle is given in degrees, and defaults to 360. When the listener is positioned within the volume defined by the outer cone, but outside the volume defined by the inner cone, the gain applied is a smooth interpolation between volume and cone_outer_gain.

cone_outer_gain

The gain applied outside the cone.

When the listener is positioned outside the volume defined by the outer cone, this gain is applied instead of volume.

delete() → None

Release the resources acquired by this player.

The internal audio player and the texture will be deleted.

event_types: list = ['on_eos', 'on_player_eos', 'on_player_next_source', 'on_driver_reset']

loop

Loop the current source indefinitely or until next_source() is called. Defaults to False.

Type:

bool

Added in version 1.4.

max_distance

The distance at which no further attenuation is applied.

When the distance from the listener to the player is greater than this value, attenuation is calculated as if the distance were value. By default the maximum distance is infinity.

The unit defaults to meters, but can be modified with the listener properties.

min_distance

The distance beyond which the sound volume drops by half, and within which no attenuation is applied.

The minimum distance controls how quickly a sound is attenuated as it moves away from the listener. The gain is clamped at the nominal value within the min distance. By default the value is 1.0.

The unit defaults to meters, but can be modified with the listener properties.

next_source() → None

Move immediately to the next source in the current playlist.

If the playlist is empty, discard it and check if another playlist is queued. There may be a gap in playback while the audio buffer is refilled.

on_driver_reset()

The audio driver has been reset.

By default this will kill the current audio player, create a new one, and requeue the buffers. Any buffers that may have been queued in a player will be resubmitted. It will continue from the last buffers submitted, not played, and may cause sync issues if using video.

on_eos()

The current source ran out of data.

The default behaviour is to advance to the next source in the playlist if the loop attribute is set to False. If loop attribute is set to True, the current source will start to play again until next_source() is called or loop is set to False.

on_player_eos()

The player ran out of sources. The playlist is empty.

on_player_next_source()

The player starts to play the next queued source in the playlist.

This is a useful event for adjusting the window size to the new source VideoFormat for example.

pause() → None

Pause playback of the current source.

This has no effect if the player is already paused.

pitch

The pitch shift to apply to the sound.

The nominal pitch is 1.0. A pitch of 2.0 will sound one octave higher, and play twice as fast. A pitch of 0.5 will sound one octave lower, and play twice as slow. A pitch of 0.0 is not permitted.

play() → None

Begin playing the current source.

This has no effect if the player is already playing.

property playing: bool

The current playing state.

The playing property is irrespective of whether or not there is actually a source to play. If playing is True and a source is queued, it will begin to play immediately. If playing is False, it is implied that the player is paused. There is no other possible state.

position

The position of the sound in 3D space.

The position is given as a tuple of floats (x, y, z). The unit defaults to meters, but can be modified with the listener properties.

queue(source: Source | Iterable[Source]) → None

Queue the source on this player.

If the player has no source, the player will start to play immediately or pause depending on its playing attribute.

seek(timestamp: float) → None

Seek for playback to the indicated timestamp on the current source.

Timestamp is expressed in seconds. If the timestamp is outside the duration of the source, it will be clamped to the end.

seek_next_frame() → None

Step forwards one video frame in the current source.

property source: Source | None

Read-only. The current Source, or None.

property texture: Texture | None

Get the texture for the current video frame, if any.

You should query this property every time you display a frame of video, as multiple textures might be used. This property will be None if the current Source does not contain video.

property time: float

Read-only. Current playback time of the current source.

The playback time is a float expressed in seconds, with 0.0 being the beginning of the media. The playback time returned represents the player master clock time which is used to synchronize both the audio and the video.

update_texture(dt: float | None = None) → None

Manually update the texture from the current source.

This happens automatically, so you shouldn’t need to call this method.

Parameters:

dt – The time elapsed since the last call to update_texture.

volume

The volume level of sound playback.

The nominal level is 1.0, and 0.0 is silence.

The volume level is affected by the distance from the listener (if positioned).