AudioSignal¶

class modusa.signals.audio_signal.AudioSignal(y: ndarray, sr: int, t0: float = 0.0, title: str | None = None)[source]¶

Bases: ModusaSignal

Represents a 1D audio signal within modusa framework.

Note

It is highly recommended to use AudioLoader to instantiate an object of this class.
This class assumes audio is mono (1D numpy array).

Parameters:

y (np.ndarray) – 1D numpy array representing the audio signal.
sr (int | None) – Sampling rate in Hz. Required if t is not provided.
t0 (float, optional) – Starting time in seconds. Defaults to 0.0.
title (str | None, optional) – Optional title for the signal. Defaults to “Audio Signal”.

property y: ndarray¶: Returns audio data.

property sr: ndarray¶: Returns sampling rate of the audio.

property t0: ndarray¶: Returns start timestamp of the audio.

property t: ndarray¶: Timestamp array of the audio.

property Ts: float¶: Sampling Period of the audio.

property duration: float¶: Duration of the audio.

property shape: tuple¶: Shape of the audio signal.

property ndim: int¶: Dimension of the audio.

print_info() → None[source]¶: Prints info about the audio.

crop(t_min: int | float | None = None, t_max: int | float | None = None) → AudioSignal[source]¶

Crop the audio signal to a time range [t_min, t_max].

from modusa.generators import AudioSignalGenerator
audio_example = AudioSignalGenerator.generate_example()
cropped_audio = audio_example.crop(1.5, 2)

Parameters:

t_min (float or None) – Inclusive lower time bound. If None, no lower bound.
t_max (float or None) – Exclusive upper time bound. If None, no upper bound.

Returns:

Cropped audio signal.

Return type:

AudioSignal

Plot the audio waveform using matplotlib.

from modusa.generators import AudioSignalGenerator
audio_example = AudioSignalGenerator.generate_example()
audio_example.plot(color="orange", title="Example Audio")

Parameters:

ax (matplotlib.axes.Axes | None) – Pre-existing axes to plot into. If None, a new figure and axes are created.
fmt (str | None) – Format of the plot as per matplotlib standards (Eg. “k-” or “blue–o)
title (str | None) – Plot title. Defaults to the signal’s title.
label (str | None) – Label for the plot, shown as legend.
ylabel (str | None) – Label for the y-axis. Defaults to “Amplitude”.
xlabel (str | None) – Label for the x-axis. Defaults to “Time (sec)”.
ylim (tuple[float, float] | None) – Limits for the y-axis.
xlim (tuple[float, float] | None)
highlight (list[tuple[float, float]] | None) – List of time intervals to highlight on the plot, each as (start, end).
vlines (list[float]) – List of x values to draw vertical lines. (Eg. [10, 13.5])
hlines (list[float]) – List of y values to draw horizontal lines. (Eg. [10, 13.5])
show_grid (bool) – If true, shows grid.
stem (bool) – If True, use a stem plot instead of a continuous line. Autorejects if signal is too large.
legend_loc (str | None) – If provided, adds a legend at the specified location (e.g., “upper right” or “best”). Limits for the x-axis.

Returns:

The figure object containing the plot or None in case an axis is provided.

Return type:

matplotlib.figure.Figure | None

play(regions: list[tuple[float, float], ...] | None = None, title: str | None = None)[source]¶

Play the audio signal inside a Jupyter Notebook.

from modusa.generators import AudioSignalGenerator
audio = AudioSignalGenerator.generate_example()
audio.play(regions=[(0.0, 1.0), (2.0, 3.0)])

Parameters:

regions (list of tuple of float, optional) – List of (start_time, end_time) pairs in seconds specifying the regions to play. If None, the entire signal is played.
title (str or None, optional) – Optional title for the player interface. Defaults to the signal’s internal title.

Returns:

An interactive audio player widget for Jupyter environments.

Return type:

IPython.display.Audio