rpaudio#

Submodules#

Package Contents#

class rpaudio.AudioChannel#

current_audio_data()#

Retrieves metadata and current playback information.

This method returns a dictionary containing various metadata fields such as album artist, album title, artist, channels, duration, and more, along with current playback information like volume and position.

Returns:

Dict[str, Union[str, float, int, None]]: A dictionary with audio metadata and playback details, including:

album_artist (str): The artist of the album.

album_title (str): The title of the album.

artist (str): The artist of the audio track.

channels (int): The number of audio channels.

comment (Optional[str]): Comments about the track.

composer (Optional[str]): The composer of the audio.

date (Optional[str]): The release date of the audio.

disc_number (Optional[int]): The disc number in a multi-disc set.

duration (float): The duration of the audio in seconds.

genre (Optional[str]): The genre of the audio.

sample_rate (int): The sample rate of the audio in Hz.

title (str): The title of the audio track.

total_discs (Optional[int]): The total number of discs in a multi-disc set.

total_tracks (Optional[int]): The total number of tracks in the album.

track_number (Optional[int]): The track number on the album.

year (Optional[int]): The year the audio was released.

speed (float): The current playback speed.

position (float): The current playback position in seconds.

volume (float): The current volume level.

effects (List[Dict[str, Any]]): List of effects applied to the audio.

Return type:: Dict[str, Union[str, float, int, None]]

drop_current_audio()#

Stops the currently playing audio, if any, and removes it from the channel.

Example:

channel = AudioChannel()
channel.drop_current_audio()  # Stops and clears the currently playing audio

Return type:: None

effects()#

Get the list of effects in the audio processing chain.

This method retrieves the effects currently applied to the audio sink and returns them as a list. Each effect in the list is represented by its corresponding effect class instance.

Returns:: List[Union[FadeIn, FadeOut, ChangeSpeed]]: A list containing the effects.

Return type:: List[Union[effects.FadeIn, effects.FadeOut, effects.ChangeSpeed]]

is_playing()#

Returns True if audio is currently playing, otherwise False.

Example:

channel = AudioChannel()
if channel.is_playing():
    print("Audio is playing")
else:
    print("No audio is playing")

Return type:: bool

push(audio)#

Adds an AudioSink object to the queue.

Example:

channel = AudioChannel()
sink = AudioSink("my_audio_file.mp3")
channel.push(sink)

Parameters:: audio (AudioSink)
Return type:: None

set_effects_chain(effect_list)#

Sets the effects chain for the audio channel.

This method accepts a list of effects and applies them to the audio channel. The effects can include FadeIn, FadeOut, and ChangeSpeed.

Example:

channel = AudioChannel()
fade_in_effect = FadeIn(start_val=0.0, end_val=1.0, duration=3.0)
fade_out_effect = FadeOut(end_val=0.0, duration=10.0)
speed_up_effect = ChangeSpeed(end_val=1.5, duration=5.0)

channel.set_effects_chain([fade_in_effect, fade_out_effect, speed_up_effect])

Parameters:: effect_list (list) – A list of effects to set for the audio channel.
Raises:: TypeError – If an unknown effect type is provided.
Return type:: None

property auto_consume: bool#

Returns whether the channel automatically consumes the queue.

Return type:: bool

property current_audio: AudioSink#

Returns the currently playing AudioSink object.

Example:

channel = AudioChannel()
current_sink = channel.current_audio()
if current_sink:
    print("Currently playing:", current_sink)
else:
    print("No audio is playing")

Return type:: AudioSink

currently_playing: AudioSink | None#

effects_chain: List[ActionType]#

queue: List[AudioSink]#

property queue_contents: List[AudioSink]#

Returns the current queue of AudioSink objects.

Example:

channel = AudioChannel()
queue = channel.queue_contents()
print(f"Queue has {len(queue)} items")

Return type:: List[AudioSink]

class rpaudio.AudioSink(callback=None)#

Interface that wraps functionality for audio files.

This class provides methods to load, play, pause, stop audio playback, manage audio effects, and manipulate playback speed and volume. An optional callback function can be invoked when the audio stops playing.

Example:

handler = AudioHandler(callback=my_callback)
handler.load_audio("my_audio_file.mp3")
handler.play()
handler.pause()
handler.stop()

Args:: callback (Optional[Callable[[], None]]): A function that will be called when the audio stops playing.
Attributes:: is_playing (bool): Flag indicating whether the audio is currently playing.

Parameters:: callback (Optional[Callable[[], None]])

apply_effects(effect_list)#

Apply a list of audio effects such as fade-in, fade-out, or speed changes.

Parameters:

effect_list (list) – A list of effects to apply. Each effect must be an instance of FadeIn, FadeOut, ChangeSpeed, or similar.

Raises:

TypeError – If an unknown effect type is provided.
RuntimeError – If an error occurs while applying the effects.

Return type:

None

callback()#

Get the callback function associated with the audio sink.

Returns:: Optional[Callable]: The Python callable if set; otherwise, None.

Return type:: Optional[Callable]

cancel_callback()#

Cancels the current audio callback.

This method sets a flag to indicate that the audio callback should be canceled. Once called, the audio sink will stop processing the current audio callback.

Example:

audio_sink = AudioSink()
audio_sink.cancel_callback()
print("Audio callback has been canceled.")

Raises:: RuntimeError – If there is an issue acquiring the lock on the callback.
Return type:: None

empty()#

Check if the audio sink is empty.

Returns:: bool: True if the audio sink is empty; otherwise, False.

Return type:: bool

get_pos()#

Get the current playback position in seconds.

Returns:: The playback position.
Return type:: float
Raises:: RuntimeError – If playback has not started.

get_remaining_time()#

Get the remaining time of the audio playback.

Returns:

The remaining time of the audio in seconds, rounded to two decimal places.

Return type:

float

Raises:

RuntimeError – If the audio duration is not available.
RuntimeError – If no sink is available or audio is not loaded.

get_speed()#

Get the current playback speed of the audio.

Returns:: The playback speed.
Return type:: float

get_volume()#

Get the current volume level.

Returns:: The current volume level.
Return type:: float

load_audio(filename)#

Load an audio file for playback.

Parameters:: filename (str) – The path to the audio file to load.
Return type:: AudioSink

pause()#

Pause the currently playing audio, if any.

Raises:: RuntimeError: If no audio has been loaded.

Example:

handler = AudioHandler(callback=my_callback)
handler.load_audio("my_audio_file.mp3")
handler.play()
handler.pause()

Return type:: None

play()#

Start playing the loaded audio.

This method begins playback of the audio that was loaded using the load_audio method. If the audio is already playing, this method has no effect.

Raises:: RuntimeError: If no audio has been loaded.

Example:

handler = AudioHandler(callback=my_callback)
handler.load_audio("my_audio_file.mp3")
handler.play()

Return type:: None

playback_data()#

Retrieve playback metadata and effects associated with the audio sink.

Returns:

Dict[str, Any]: A dictionary containing playback metadata, a list of effects, and the current playback position. The dictionary includes the following keys:

‘effects’: A list of effect dictionaries, each representing an action (e.g.,

FadeIn, FadeOut, ChangeSpeed). - ‘position’: The current playback position.

Return type:: Dict[str, Any]

set_duration(duration)#

Set the length of the audio file to the meta data.

Parameters:: duration (float) – The duration. Must be a float
Return type:: None

set_speed(speed)#

Set the playback speed of the audio.

Parameters:

speed (float) – The playback speed. Must be a float.

Raises:

ValueError – If the speed is not a valid float.
EffectConflictException – Raised when an attempt is made to change the volume while

Return type:

None

effects are actively being applied. This ensures that audio effects do not conflict during playback.

set_volume(volume)#

Set the volume level for playback.

Parameters:

volume (float) – The volume level. Must be between 0.0 and 1.0.

Raises:

ValueError – If the volume is not between 0.0 and 1.0.
EffectConflictException – Raised when an attempt is made to change the volume while

Return type:

None

effects are actively being applied. This ensures that audio effects do not conflict during playback.

stop()#

Stop the currently playing audio, if any.

Raises:: RuntimeError: If no audio has been loaded.

Example:

handler = AudioHandler(callback=my_callback)
handler.load_audio("my_audio_file.mp3")
handler.play()
handler.stop()

Return type:: None

try_seek(position)#

Attempt to seek to a specific position in the audio playback.

Parameters:: position (float) – The position in seconds to seek to.
Raises:: ValueError – If the position is negative or not a valid time in the audio.
Return type:: None

property is_playing: bool#

Flag indicating whether the audio is currently playing.

Returns:: bool: True if the audio is playing, False otherwise.

Example:

handler = AudioHandler(callback=my_callback)
handler.load_audio("my_audio_file.mp3")
handler.play()
print(handler.is_playing)  # True if audio is playing

Return type:: bool

property metadata: MetaData#

Get metadata for the audio file.

Example:

audio_1: rpaudio.AudioSink = rpaudio.AudioSink(callback=on_audio_stop)
audio_1.load_audio("ex.wav")
data = audio_1.metadata

Returns:: An instance of the MetaData class containing metadata for the audio file.
Return type:: MetaData

property metadata_dict: dict[str, any]#

Get metadata for the audio file as a dictionary.

Example:

audio_1: rpaudio.AudioSink = rpaudio.AudioSink(callback=on_audio_stop)
audio_1.load_audio("ex.wav")
data_dict = audio_1.metadata_dict

Returns:: A dictionary containing metadata for the audio file.
Return type:: dict[str, any]

class rpaudio.ChannelManager#

Manages multiple audio channels and provides an API to control them.

Example:

# Intializing 2 audio sinks
audio_1 = AudioSink(callback=on_audio_stop)
audio_1.load_audio("ex.wav")
audio_2 = AudioSink(callback=on_audio_stop)
audio_2.load_audio("Acrylic.mp3")
print(audio_1.metadata)

# Intializing 1st audio channel
channel_1 = AudioChannel()
channel_1.push(audio_1)
channel_1.push(audio_2)

# Intializing 2 more audio sinks
audio_3 = AudioSink(callback=on_audio_stop)
audio_3.load_audio("ex.wav")
audio_4 = AudioSink(callback=on_audio_stop)
audio_4.load_audio("Acrylic.mp3")
# Intializing 2nd audio channel
channel_2 = AudioChannel()
channel_2.push(audio_3)
channel_2.push(audio_4)

# Intializing ChannelManager
manager = ChannelManager()
manager.add_channel("Channel1", channel_1)
manager.add_channel("Channel2", channel_2)

Variables:: channels (dict) – A dictionary mapping channel identifiers to their corresponding AudioChannel instances.

add_channel(name, channel)#

Adds a new audio channel to the manager. :param name: The unique identifier for the channel. :type name: str :param channel: The audio channel to add. :type channel: AudioChannel

Parameters:

name (str)
channel (AudioChannel)

Return type:

None

channel(name)#

Retrieves a channel by its identifier. :param name: The unique identifier of the channel. :type name: str :return: The corresponding AudioChannel instance, or None if not found. :rtype: Optional[AudioChannel]

Parameters:: name (str)
Return type:: Optional[AudioChannel]

drop_channel(name)#

Drops an audio channel from the manager. :param name: The unique identifier of the channel to drop. :type name: str :raises RuntimeError: If the channel is not found.

Parameters:: name (str)
Return type:: None

start_all()#

Starts auto-consuming audio on all channels.

Return type:: None

stop_all()#

Stops auto-consuming audio on all channels.

Return type:: None

channels: dict[str, AudioChannel]#