# Class pyglet.media.Player

    event.EventDispatcher --+
                            |
                           Player

Known Subclasses:
  ManagedSoundPlayer

A sound and/or video player.

Queue sources on this player to play them.

## Events

| on_eos() The player has reached the end of the current source.

## Methods

| __init__(self)
| queue(self, source) Queue the source on this player.
| play(self) Begin playing the current source.
| pause(self) Pause playback of the current source.
| seek(self, timestamp) Seek for playback to the indicated timestamp in seconds on the current source.
| next(self) Move immediately to the next queued source.
| dispatch_events(self, dt=None) Dispatch any pending events and perform regular heartbeat functions to maintain playback.
pyglet.image.Texture | get_texture(self) Get the texture for the current video frame.
| dispatch_event(self, event_type, *args) Dispatch a single event to the attached handlers. (Inherited from pyglet.event.EventDispatcher)
| event(self, *args) Function decorator for an event handler. (Inherited from pyglet.event.EventDispatcher)
| pop_handlers(self) Pop the top level of event handlers off the stack. (Inherited from pyglet.event.EventDispatcher)
| push_handlers(self, *args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers. (Inherited from pyglet.event.EventDispatcher)
| register_event_type(cls, name) Register an event type with the dispatcher. (Inherited from pyglet.event.EventDispatcher)
| remove_handler(self, name, handler) Remove a single event handler. (Inherited from pyglet.event.EventDispatcher)
| remove_handlers(self, *args, **kwargs) Remove event handlers from the event stack. (Inherited from pyglet.event.EventDispatcher)
| set_handler(self, name, handler) Attach a single event handler. (Inherited from pyglet.event.EventDispatcher)
| set_handlers(self, *args, **kwargs) Attach one or more event handlers to the top level of the handler stack. (Inherited from pyglet.event.EventDispatcher)

## Properties

float | time Retrieve the current playback time of the current source.
Source | source Return the current source.
str | eos_action Set the behaviour of the player when it reaches the end of the current source.
bool | playing Determine if the player state is playing.
float | volume The volume level of sound playback.
3-tuple of float | position The position of the sound in 3D space.
float | min_distance The distance beyond which the sound volume drops by half, and within which no attenuation is applied.
float | max_distance The distance at which no further attenuation is applied.
float | pitch The pitch shift to apply to the sound.
3-tuple of float | cone_orientation The direction of the sound in 3D space.
float | cone_inner_angle The interior angle of the inner cone.
float | cone_outer_angle The interior angle of the outer cone.
float | cone_outer_gain The gain applied outside the cone.
pyglet.image.Texture | texture The video texture.

## Class Variables

| event_types = ``[``'``on_eos``'``]``

## Constants

| EOS_PAUSE = ``'``pause``'`` The player will pause when it reaches the end of the stream.
| EOS_LOOP = ``'``loop``'`` The player will loop the current stream continuosly.
| EOS_NEXT = ``'``next``'`` The player will move on to the next queued stream when it reaches the end of the current source.
| EOS_STOP = ``'``stop``'`` The player will stop entirely; valid only for ManagedSoundPlayer.

## Event Details

### on_eos

on_eos()

The player has reached the end of the current source.

This event is dispatched regardless of the EOS action. You can alter the EOS action in this event handler, however playback may stutter as the media device will not have enough time to decode and buffer the new data in advance.

## Method Details

### queue

queue(self, source)

Queue the source on this player.

If the player has no source, the player will be paused immediately on this source.

Parameters:
  source : Source
    The source to queue.

### play

play(self)

Begin playing the current source.

This has no effect if the player is already playing.

### pause

pause(self)

Pause playback of the current source.

This has no effect if the player is already paused.

### seek

seek(self, timestamp)
Seek for playback to the indicated timestamp in seconds on the current source. If the timestamp is outside the duration of the source, it will be clamped to the end.

Parameters:
  timestamp : float
    Timestamp to seek to.

### next

next(self)

Move immediately to the next queued source.

There may be a gap in playback while the audio buffer is refilled.

### dispatch_events

dispatch_events(self, dt=None)
Dispatch any pending events and perform regular heartbeat functions to maintain playback.

Parameters:
  dt : None
    Ignored (for compatibility with pyglet.clock.schedule)

Deprecated: Since pyglet 1.1, Player objects schedule themselves on the default clock automatically. Applications should not call this method.

### get_texture

get_texture(self)

Get the texture for the current video frame.

You should call this method every time you display a frame of video, as multiple textures might be used. The return value will be `None` if there is no video in the current source.

Returns: pyglet.image.Texture

Since: pyglet 1.1

## Property Details

### time

Retrieve the current playback time of the current source.

The playback time is a float expressed in seconds, with 0.0 being the beginning of the sound. The playback time returned represents the time encoded in the source, and may not reflect actual time passed due to pitch shifting or pausing.

Read-only.

Type:
  float

### source

Return the current source.

Read-only.

Type:
  Source

### eos_action

Set the behaviour of the player when it reaches the end of the current source.

This must be one of the constants EOS_NEXT, EOS_PAUSE or EOS_LOOP.

Type:
  str

### playing

Determine if the player state is playing.

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 playing immediately. If playing is False, it is implied that the player is paused. There is no other possible state.

Read-only.

Type:
  bool

### 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).

Type:
  float

### 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.

Type:
  3-tuple of float

### 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.

Type:
  float

### 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.

Type:
  float

### 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.

Type:
  float

### 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.

Type:
  3-tuple of float

### 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).

Type:
  float

### 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.

Type:
  float

### 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.

Type:
  float

### texture

The video texture.

You should rerequest this property every time you display a frame of video, as multiple textures might be used. This property will be `None` if there is no video in the current source.

Deprecated: Use get_texture.

Type:
  pyglet.image.Texture

## Constant Details

### EOS_NEXT

The player will move on to the next queued stream when it reaches the end of the current source. If there is no source queued, the player will pause.

Value:

      'next'