Controlling playback

You can implement many functions common to a media player using the Player class. Use of this class is also necessary for video playback. There are no parameters to its construction:

player =

A player will play any source that is "queued" on it. Any number of sources can be queued on a single player, but once queued, a source can never be dequeued (until it is removed automatically once complete). The main use of this queuing mechanism is to facilitate "gapless" transitions between playback of media files.

A StreamingSource can only ever be queued on one player, and only once on that player. StaticSource objects can be queued any number of times on any number of players. Recall that a StaticSource can be created by passing streaming=False to the load method.

In the following example, two sounds are queued onto a player:


Playback begins with the player's play method is called:

Standard controls for controlling playback are provided by these methods:

Method Description
play Begin or resume playback of the current source.
pause Pause playback of the current source.
next Dequeue the current source and move to the next one immediately.
seek Seek to a specific time within the current source.

Note that there is no stop method. If you do not need to resume playback, simply pause playback and discard the player and source objects. Using the next method does not guarantee gapless playback.

There are several properties that describe the player's current state:

Property Description
time The current playback position within the current source, in seconds. This is read-only (but see the seek method).
playing True if the player is currently playing, False if there are no sources queued or the player is paused. This is read-only (but see the pause and play methods).
source A reference to the current source being played. This is read-only (but see the queue method).
volume The audio level, expressed as a float from 0 (mute) to 1 (normal volume). This can be set at any time.

When a player reaches the end of the current source, by default it will move immediately to the next queued source. If there are no more sources, playback stops until another is queued. There are several other possible behaviours, specified by setting the eos_action attribute on the player:

eos_action Description
EOS_NEXT The default action: playback continues at the next source.
EOS_PAUSE Playback pauses at the end of the source, which remains the current source for this player.
EOS_LOOP Playback continues immediately at the beginning of the current source.
EOS_STOP Valid only for ManagedPlayer, for which it is default: the player is discarded when the current source finishes.

You can change a player's eos_action at any time, but be aware that unless sufficient time is given for the future data to be decoded and buffered there may be a stutter or gap in playback. If eos_action is set well in advance of the end of the source (say, several seconds), there will be no disruption.