audiofile¶

This module contains the following classes:

AudioFile, representing an audio file;
AudioFileConverterError,
AudioFileNotInitializedError,
AudioFileProbeError, and
AudioFileUnsupportedFormatError, representing errors generated by audio files.

class aeneas.audiofile.AudioFile(file_path=None, file_format=None, rconf=None, logger=None)[source]¶

A class representing an audio file.

This class can be used either to extract properties from an audio file on disk, or to load/edit/save a monoaural (single channel) audio file, represented as an array of audio samples.

The properties of the audio file (length, format, etc.) can set by invoking the read_properties() function, which calls an audio file probe. (Currently, the probe is FFPROBEWrapper)

Moreover, this class can read the audio data, by converting the original file format into a temporary PCM16 Mono WAVE (RIFF) file, which is deleted as soon as audio data is read in memory. (Currently, the converter is FFMPEGWrapper)

The internal representation of the wave is a a NumPy 1D array of float64 values in [-1.0, 1.0]. It supports append, reverse, and trim operations. Audio samples can be written to file. Memory can be pre-allocated to speed append operations up. Allocated memory is doubled when an append operation requires more memory than what is available; this leads to an amortized linear complexity (in the number of audio samples) for append operations.

Note

Support for stereo WAVE files might be implemented in a future version

Parameters:	file_path (string) – the path of the audio file file_format (tuple) – the format of the audio file, if known in advance: `(codec, channels, rate)` or `None` rconf (`RuntimeConfiguration`) – a runtime configuration logger (`Logger`) – the logger object

FILE_EXTENSIONS = ['3g2', '3gp', 'aa', 'aa3', 'aac', 'aax', 'aiff', 'alac', 'amr', 'ape', 'asf', 'at3', 'at9', 'au', 'avi', 'awb', 'celt', 'dct', 'dss', 'dvf', 'eac', 'flac', 'flv', 'gsm', 'm4a', 'm4b', 'm4p', 'm4v', 'mid', 'midi', 'mkv', 'mmf', 'mov', 'mp2', 'mp3', 'mp4', 'mpc', 'mpeg', 'mpg', 'mpv', 'msv', 'oga', 'ogg', 'ogv', 'oma', 'opus', 'pcm', 'qt', 'ra', 'ram', 'raw', 'riff', 'rm', 'rmvb', 'shn', 'sln', 'theora', 'tta', 'vob', 'vorbis', 'vox', 'wav', 'webm', 'wma', 'wmv', 'wv', 'yuv']¶: Extensions of common formats for audio (and video) files.

add_samples(samples, reverse=False)[source]¶

Concatenate the given new samples to the current audio data.

This function initializes the memory if no audio data is present already.

If reverse is True, the new samples will be reversed and then concatenated.

Parameters:	samples (`numpy.ndarray` (1D)) – the new samples to be concatenated reverse (bool) – if `True`, concatenate new samples after reversing them

New in version 1.2.1.

audio_channels¶

The number of channels of the audio file.

Return type:	int

audio_format¶

The format of the audio file.

Return type:	string

audio_length¶

The length of the audio file, in seconds.

Return type:	`TimeValue`

audio_sample_rate¶

The sample rate of the audio file, in samples per second.

Return type:	int

audio_samples¶

The audio audio_samples, that is, an array of float64 values, each representing an audio sample in [-1.0, 1.0].

Note that this function returns a view into the first self.__samples_length elements of self.__samples. If you want to clone the values, you must use e.g. numpy.array(audiofile.audio_samples).

Return type:	`numpy.ndarray` (1D, view)
Raises:	`AudioFileNotInitializedError`: if the audio file is not initialized yet

clear_data()[source]¶: Clear the audio data, freeing memory.

file_path¶

The path of the audio file.

Return type:	string

file_size¶

The size of the audio file, in bytes.

Return type:	int

minimize_memory()[source]¶

Reduce the allocated memory to the minimum required to store the current audio samples.

This function is meant to be called when building a wave incrementally, after the last append operation.

New in version 1.5.0.

preallocate_memory(capacity)[source]¶

Preallocate memory to store audio samples, to avoid repeated new allocations and copies while performing several consecutive append operations.

If self.__samples is not initialized, it will become an array of capacity zeros.

If capacity is larger than the current capacity, the current self.__samples will be extended with zeros.

If capacity is smaller than the current capacity, the first capacity values of self.__samples will be retained.

Parameters:	capacity (int) – the new capacity, in number of samples
Raises:	ValueError: if `capacity` is negative

New in version 1.5.0.

read_properties()[source]¶

Populate this object by reading the audio properties of the file at the given path.

Currently this function uses FFPROBEWrapper to get the audio file properties.

Raises:	`AudioFileProbeError`: if the path to the `ffprobe` executable cannot be called
Raises:	`AudioFileUnsupportedFormatError`: if the audio file has a format not supported
Raises:	OSError: if the audio file cannot be read

read_samples_from_file()[source]¶

Load the audio samples from file into memory.

If self.file_format is None or it is not ("pcm_s16le", 1, self.rconf.sample_rate), the file will be first converted to a temporary PCM16 mono WAVE file. Audio data will be read from this temporary file, which will be then deleted from disk immediately.

Otherwise, the audio data will be read directly from the given file, which will not be deleted from disk.

Raises:	`AudioFileConverterError`: if the path to the `ffmpeg` executable cannot be called
Raises:	`AudioFileUnsupportedFormatError`: if the audio file has a format not supported
Raises:	OSError: if the audio file cannot be read

reverse()[source]¶

Reverse the audio data.

Raises:	`AudioFileNotInitializedError`: if the audio file is not initialized yet

New in version 1.2.0.

trim(begin=None, length=None)[source]¶

Get a slice of the audio data of length seconds, starting from begin seconds.

If audio data is not loaded, load it and then slice it.

Parameters:	begin (`TimeValue`) – the start position, in seconds length (`TimeValue`) – the position, in seconds
Raises:	TypeError: if one of the arguments is not `None` or `TimeValue`

New in version 1.2.0.

write(file_path)[source]¶

Write the audio data to file. Return True on success, or False otherwise.

Parameters:	file_path (string) – the path of the output file to be written
Raises:	`AudioFileNotInitializedError`: if the audio file is not initialized yet

New in version 1.2.0.

exception aeneas.audiofile.AudioFileConverterError[source]¶: Error raised when the audio converter executable cannot be executed.

exception aeneas.audiofile.AudioFileNotInitializedError[source]¶: Error raised when trying to access audio samples from an AudioFile object which has not been initialized yet.

exception aeneas.audiofile.AudioFileProbeError[source]¶: Error raised when the audio probe executable cannot be executed.

exception aeneas.audiofile.AudioFileUnsupportedFormatError[source]¶: Error raised when the format of the given file cannot be decoded.