audiotools.player — the Audio Player Module

The audiotools.player module contains the Player and AudioOutput classes for playing AudioFiles.

audiotools.player.available_outputs()

Iterates over all available AudioOutput objects. This will always return at least one output object.

audiotools.player.open_output(output)

Given a string of an AudioOutput class’ NAME attribute, returns the given AudioOutput object.

Raises ValueError if the output cannot be found.

Player Objects

This class is an audio player which plays audio data from an opened audio file object to a given output sink.

class audiotools.player.Player(audio_output[, replay_gain[, next_track_callback]])

audio_output is an AudioOutput object.

replay_gain is either RG_NO_REPLAYGAIN, RG_TRACK_GAIN or RG_ALBUM_GAIN, indicating the level of ReplayGain to apply to tracks being played back.

next_track_callback is a function which takes no arguments, to be called when the currently playing track is completed.

Raises ValueError if unable to start player subprocess.

Player.open(audiofile)

Opens the given audiotools.AudioFile object for playing. Any currently playing file is stopped.

Player.play()

Begins or resumes playing the currently opened audiotools.AudioFile object, if any.

Player.set_replay_gain(replay_gain)

Sets the given ReplayGain level to apply during playback. Choose from RG_NO_REPLAYGAIN, RG_TRACK_GAIN or RG_ALBUM_GAIN ReplayGain cannot be applied mid-playback. One must stop() and play() a file for it to take effect.

Player.set_output(audio_output)

Changes where the audio will be played to the given output where audio_output is an AudioOutput object.

The current state and progress of the player remains unchanged, but the output volume and description may change.

Player.pause()

Pauses playback of the current file. Playback may be resumed with play() or toggle_play_pause()

Player.toggle_play_pause()

Pauses the file if playing, play the file if paused.

Player.stop()

Stops playback of the current file. If play() is called, playback will start from the beginning.

Player.state()

Returns the current state of the player which will be either PLAYER_STOPPED, PLAYER_PAUSED or PLAYER_PLAYING integers.

Player.close()

Closes the player for playback. The player thread is halted and the AudioOutput object is closed.

Player.progress()

Returns a (pcm_frames_played, pcm_frames_total) tuple. This indicates the current playback status in terms of PCM frames.

Player.current_output_description()

Returns the human-readable description of the current output device as a Unicode string.

Player.current_output_name()

Returns the NAME attribute of the current output device as a plain string.

Player.get_volume()

Returns the current volume level as a floating point value between 0.0 and 1.0, inclusive.

Player.set_volume(volume)

Given a floating point value between 0.0 and 1.0, inclusive, sets the current volume level to that value.

Player.change_volume(delta)

Given a floating point delta value which may be positive (to increase volume) or negative (to decrease volume), adjusts the current volume by that amount and returns the new volume as a floating point value between 0.0 and 1.0, inclusive.

CDPlayer Objects

This class is an audio player which plays audio data from a CDDA disc to a given output sink.

class audiotools.player.CDPlayer(cdda, audio_output[, next_track_callback])

cdda is a audiotools.CDDA object. audio_output is a AudioOutput object subclass which audio data will be played to. next_track_callback is a function which takes no arguments, to be called when the currently playing track is completed.

CDPlayer.open(track_number)

Opens the given track number for reading, where track_number starts from 1.

CDPlayer.play()

Begins or resumes playing the currently opened track, if any.

CDPlayer.pause()

Pauses playback of the current track. Playback may be resumed with play() or toggle_play_pause()

CDPlayer.toggle_play_pause()

Pauses the track if playing, play the track if paused.

CDPlayer.stop()

Stops playback of the current track. If play() is called, playback will start from the beginning.

CDPlayer.close()

Closes the player for playback. The player thread is halted and the AudioOutput object is closed.

CDPlayer.progress()

Returns a (pcm_frames_played, pcm_frames_total) tuple. This indicates the current playback status in terms of PCM frames.

AudioOutput Objects

This is an abstract class used to implement audio output sinks.

class audiotools.player.AudioOutput

AudioOutput.NAME

The name of the AudioOutput subclass as a string.

AudioOutput.description()

Returns a user-friendly name of the output device as a Unicode string.

AudioOutput.compatible(sample_rate, channels, channel_mask, bits_per_sample)

Returns True if the given attributes are compatible with the currently opened output stream.

AudioOutput.set_format(sample_rate, channels, channel_mask, bits_per_sample)

Sets the output stream to the given format.

If the stream hasn’t been initialized, this method initializes it to that format.

If the stream has been initialized to a different format, this method closes and reports the stream to the new format.

If the stream has been initialized to the same format, this method does nothing.

AudioOutput.play(framelist)

Plays the given FrameList object to the output stream. This presumes the output stream’s format has been set correctly.

AudioOutput.pause()

Pauses output of playing data.

Note

Although suspending the transmission of data to output will also have the same effect as pausing, calling the output’s .pause() method will typically suspend output immediately instead of having to wait for the buffer to empty - which may take a fraction of a second.

AudioOutput.resume()

Resumes playing data to output after it has been paused.

AudioOutput.get_volume()

Returns a floating-point volume value between 0.0 and 1.0, inclusive.

AudioOutput.set_volume(volume)

Given a floating-point volume value between 0.0 and 1.0, inclusive, sets audio output to that volume.

AudioOutput.close()

Closes the output stream for further playback.

classmethod AudioOutput.available()

Returns True if the AudioOutput implementation is available on the system.