AudioData

class osekit.core_api.audio_data.AudioData(items: list[AudioItem] | None = None, begin: Timestamp | None = None, end: Timestamp | None = None, name: str | None = None, sample_rate: int | None = None, instrument: Instrument | None = None, normalization: Normalization = <Normalization.RAW: 1>, normalization_values: dict | None = None)

AudioData represent audio data scattered through different AudioFiles.

The AudioData has a collection of AudioItem. The data is accessed via an AudioItem object per AudioFile.

Initialize an AudioData from a list of AudioItems.

Parameters

items: list[AudioItem]

List of the AudioItem constituting the AudioData.

sample_rate: int

The sample rate of the audio data.

begin: Timestamp | None

Only effective if items is None. Set the begin of the empty data.

end: Timestamp | None

Only effective if items is None. Set the end of the empty data.

name: str | None

Name of the exported files.

instrument: Instrument | None

Instrument that might be used to obtain acoustic pressure from the wav audio data.

normalization: Normalization

The type of normalization to apply to the audio data.

classmethod from_files(files: list[AudioFile], begin: Timestamp | None = None, end: Timestamp | None = None, name: str | None = None, **kwargs) → AudioData

Return an AudioData object from a list of AudioFiles.

Parameters

files: list[AudioFile]

List of AudioFiles containing the data.

begin: Timestamp | None

Begin of the data object. Defaulted to the begin of the first file.

end: Timestamp | None

End of the data object. Defaulted to the end of the last file.

name: str | None

Name of the exported files.

kwargs

Keyword arguments that are passed to the cls constructor.

sample_rate: int The sample rate of the audio data.

instrument: Instrument | None Instrument that might be used to obtain acoustic pressure from the wav audio data.

normalization: Normalization The type of normalization to apply to the audio data.

Returns

Self: The AudioData object.

get_normalization_values() → dict

Return the values used for normalizing the audio data.

Returns

dict:

“mean”: mean value to substract to center values on 0. “peak”: peak value for PEAK normalization “std”: standard deviation used for z-score normalization

get_raw_value() → ndarray

Return the raw value of the audio data before normalization.

The data from the audio file will be resampled if necessary.

Returns

np.ndarray:

The value of the audio data.

get_value() → ndarray

Return the value of the audio data.

The data from the audio file will be resampled if necessary.

Returns

np.ndarray:

The value of the audio data.

get_value_calibrated() → ndarray

Return the value of the audio data accounting for the calibration factor.

If the instrument parameter of the audio data is not None, the returned value is calibrated in units of Pa.

Returns

np.ndarray:

The calibrated value of the audio data.

item_cls

alias of AudioItem

property length: int

Number of data points in each channel.

link(folder: Path) → None

Link the AudioData to an AudioFile in the folder.

The given folder should contain a file named "str(self).wav". Linking is intended for AudioData objects that have already been written. After linking, the AudioData will have a single item with the same properties of the target AudioFile.

Parameters

folder: Path

Folder in which is located the AudioFile to which the AudioData instance should be linked.

property nb_channels: int

Number of channels of the audio data.

property normalization: Normalization

The type of normalization to apply to the audio data.

property normalization_values: dict

Mean, peak and std values used for normalization.

property shape: tuple[int, int]

Shape of the audio data.

First element is the number of data point in each channel, second element is the number of channels.

split(nb_subdata: int = 2, *, pass_normalization: bool = True) → list[Self]

Split the audio data object in the specified number of audio subdata.

Parameters

nb_subdata: int

Number of subdata in which to split the data.

pass_normalization: bool

If True, the normalization values (mean, std, peak) will be computed from the original audio data and passed to the split chunks. If the original AudioData is very long, this might lead to a RAM saturation.

Returns

list[AudioData]

The list of AudioData subdata objects.

split_frames(start_frame: int = 0, stop_frame: int = -1, *, pass_normalization: bool = True) → AudioData

Return a new AudioData from a subpart of this AudioData’s data.

Parameters

start_frame: int

First frame included in the new AudioData.

stop_frame: int

First frame after the last frame included in the new AudioData.

pass_normalization: bool

If True, the normalization values (mean, std, peak) will be computed from the original audio data and passed to the split chunks. If the original AudioData is very long, this might lead to a RAM saturation.

Returns

AudioData

A new AudioData which data is included between start_frame and stop_frame.

to_dict() → dict

Serialize an AudioData to a dictionary.

Returns

dict:

The serialized dictionary representing the AudioData.

write(folder: Path, *, subtype: str | None = None, link: bool = False) → None

Write the audio data to file.

Parameters

folder: pathlib.Path

Folder in which to write the audio file.

subtype: str | None

Subtype as provided by the soundfile module. Defaulted as the default 16-bit PCM for WAV audio files.

link: bool

If True, the AudioData will be bound to the written file. Its items will be replaced with a single item, which will match the whole new AudioFile.