AudioData

class osekit.core_api.audio_data.AudioData(items: list[AudioItem] | None = None, begin: Timestamp | None = None, end: Timestamp | None = None, sample_rate: int | None = None, instrument: Instrument | 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.

instrument: Instrument | None

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

classmethod from_base_data(data: BaseData, sample_rate: float | None = None, instrument: Instrument | None = None) → AudioData

Return an AudioData object from a BaseData object.

Parameters

data: BaseData

BaseData object to convert to AudioData.

sample_rate: float | None

Sample rate of the AudioData.

instrument: Instrument | None

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

Returns

AudioData:

The AudioData object.

classmethod from_dict(dictionary: dict) → AudioData

Deserialize an AudioData from a dictionary.

Parameters

dictionary: dict

The serialized dictionary representing the AudioData.

Returns

AudioData

The deserialized AudioData.

classmethod from_files(files: list[AudioFile], begin: Timestamp | None = None, end: Timestamp | None = None, sample_rate: float | None = None, instrument: Instrument | None = None) → 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.

sample_rate: float | None

Sample rate of the AudioData.

instrument: Instrument | None

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

Returns

AudioData:

The AudioData object.

get_value(reject_dc: bool = False) → ndarray

Return the value of the audio data.

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

Parameters

reject_dc: bool

If True, the values will be centered on 0.

Returns

np.ndarray:

The value of the audio data.

get_value_calibrated(reject_dc: bool = False) → 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.

Parameters

reject_dc: bool

If True, the values will be centered on 0.

Returns

np.ndarray:

The calibrated value of the audio data.

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 shape: tuple[int, ...] | int

Shape of the audio data.

split(nb_subdata: int = 2) → list[AudioData]

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.

Returns

list[AudioData]

The list of AudioData subdata objects.

split_frames(start_frame: int = 0, stop_frame: int = -1) → 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.

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.