Api Documentation¶

class playplot.Session(x, /, sr, *, close_with_last_plot=True, fps_target=60, plot_min_sleep=0.001, time=0, volume=0.8, looping=False, save_folder='.', show_msg_box_on_error_in_other_process=None)[source]¶

A Session allows audio playback linked to multiple interactive matplotlib plots. These plots receive a curser and navigation functions, to visualize the point in the audio and allow for navigation.

This Constructor allows the creation of a Session with a numpy array as basis. There is a nearly identical function see from_file(…), witch allows the same with a file location as audio source.

After construction start the audio process via start(). Wrap your plotting function(s) with this instance see __call__(…) and call these wrapped function with your parameters to create the plots.

Parameters

x (Union[ndarray, str]) – Audio data as one-dimensional (mono) or two-dimensional (stereo) (channels first) numpy float array
sr (int) – sampling rate
close_with_last_plot (bool (default: True)) – after last plot was closed no new plots can be created and audio playback will stop
fps_target (float (default: 60)) – target frames per seconds for plots
plot_min_sleep (float (default: 0.001)) – minimal time the plotting processes will yield for (default should suffice)
time (float (default: 0)) – start time see: time
volume (float (default: 0.8)) – audio volume as sample scalar (0-1)
looping (bool (default: False)) – restart at the beginning after the end is reached
save_folder (str (default: '.')) – existing folder where plot images get saved
show_msg_box_on_error_in_other_process (Optional[bool] (default: None)) – show a message box if an error occurs, useful if no explicit error handling is performed. on by default if running in an interactive context. (in jupyter notebooks the stderr is not shown)

__call__(func)[source]¶

Function to wrap plotting function to use with Session.

Possible use cases:

def plotFunc(args,kwargs):
    import matplotlib.pyplot as plt
    import numpy as np
    ...
    return fig, ax

wrapped_func = session(plotFunc)

or:

@session
def plotFunc(*args,**kwargs):
    import matplotlib.pyplot as plt
    import numpy as np
    ...
    return fig, ax

For more details and templates see plotting details.

Parameters: func – function to wrap
Returns: wrapped function same parameters as input, calling this function will plot in new process
Return type: Callable
Raises: RuntimeError – in case the session is already stopped

check()[source]¶

Check if something went wrong in another process.

Raises

AudioProcessException – Raised in case some error occurred in the audio process associated with this session since the last check/retrieve_errors instance of ForeignProcessException
PlotProcessException – Raised in case some error occurred in a plot process associated with this session since the last check/retrieve_errors instance of ForeignProcessException

property duration: float¶: Get the duration of the associated audio (in seconds).

classmethod from_file(file, /, *, close_with_last_plot=True, fps_target=60, plot_min_sleep=0.001, time=0, volume=0.8, looping=False, save_folder='.', show_msg_box_on_error_in_other_process=None)[source]¶

Construct a Session from an audio file. For more see the constructor of this class

Parameters

file (str) – Audio file to be loaded (storage medium seek times should be fast) loaded via soundfile
close_with_last_plot (bool (default: True)) – After last plot was closed no new plots can be created and audio playback will stop
fps_target (float (default: 60)) – target frames per seconds for plots
plot_min_sleep (float (default: 0.001)) – minimal time the plotting processes will yield for (default should suffice)
time (float (default: 0)) – start time see: time
volume (float (default: 0.8)) – audio volume as sample scalar (0-1)
looping (bool (default: False)) – restart at the beginning after the end is reached
save_folder (str (default: '.')) – existing folder where plot images get saved
show_msg_box_on_error_in_other_process (Optional[bool] (default: None)) – show a message box if an error occurs, useful if no explicit error handling is performed. on by default if running in an interactive context. (in jupyter notebooks the stderr is not shown)

Raises

URLError – file was a ‘url’ and the connection failed
ValueError – file was not a url and not a valid file path
RuntimeError – the file was found but SoundFile was unable to read it

Returns

Session instance

Return type

Session

property is_running: bool¶: Check if the Session is (still) running.

join(timeout=None, force_close_with_last_plot=True)[source]¶

Block until all Plots are closed

Parameters

timeout – raises TimeoutError if reached (default: blocks forever)
force_close_with_last_plot – close session even if the Session was constructed with close_with_last_plot=False

Raises

TimeoutError – Timeout reached

property looping: bool¶: Restart after end is reached. (argument in constructor)

property paused: bool¶: Audio playback control. (may stay false after session has stopped running)

retrieve_errors()[source]¶

Check if something went wrong in the other processes and get the errors as a list.

Returns: List of all errors that occurred in other processes associated with this session since the last check/retrieve_errors. Empty if no errors were raised.
Return type: list

save_plot_images(frame_number)[source]¶

Saves images of all currently open plots, in the folder save_folder provided to the constructor. The files are named title_frame_number.png. If multiple plots are saved the titles must differ. Don’t interact with the plots while this function runs.

Can be used to help creat a video:

start = 0
end = session.duration
fps = 30

for i in range(int((end-start)*fps)):
    session.time = i/fps+start
    session.save_plot_images(i)

It is not fast.

Parameters: frame_number (int) – part of the output file names

property show_msg_box_on_error_in_other_process: bool¶: Show msg box on error in other process. Can be used to decide if main process should check for exceptions.

start()[source]¶

Start the session. Required for Audio Playback. Only callable once. May be called before and after plots are opened.

Raises: RuntimeError – In case the session is already started

stop()[source]¶: Stop the session. This closes all interactive plots, no new plots can be opened. The Session can not be restarted. Calling multiple times is allowed.

property time: float¶: Current cursor time will be clamped between 0-duration. (argument in constructor)

property total_spawned_plots: int¶: Get the total amount of plots spawned by this session. This value get immediately incremented after calling the plot function

property volume: float¶: Current volume will be clamped between 0-1. (argument in constructor)

wait_for_plots_opening(number_of_plots=None, timeout=10, supress_timeout_error=True)[source]¶

Block until at least number_of_plots are open.

Parameters

number_of_plots – Wait until number of plots are open (>=0). Defaults to total number of plots spawned by this session.
timeout – Raises TimeoutError if reached (default: blocks forever) and supress_timeout_error is not set.
supress_timeout_error – Simply return when the timeout is reached.

Raises

TimeoutError – Timeout reached

class playplot.ForeignProcessException(original_exception, formatted_traceback, origin_stack)[source]¶

This Exception contains all attributes to capture important information coming from another process.

original_exception¶: exception raised in other process

formatted_traceback¶: traceback of exception raised in other process

origin_stack¶: stack of process creation (main process)

class playplot.AudioProcessException(original_exception, formatted_traceback, origin_stack)[source]¶: ForeignProcessException raised by audio process ForeignProcessException

class playplot.PlotProcessException(original_exception, formatted_traceback, origin_stack)[source]¶: ForeignProcessException raised by plot process ForeignProcessException