from_many_files(filenames, start_time_milliseconds=0, end_time_milliseconds=0, frame_rate_hz=0, num_channels=0, convert_to_mono=False, zero_pad_ending=False, resample_mode=0, decoding_backend=0, num_workers=0)¶
Uses multithreading in Rust to decode many audio files in parallel.
(Attempt to) decode three files.
In this example, we succesfully decode two MP3 files with the default decoding arguments. Then, we demonstrate how to catch an error when decoding the third file.
>>> from babycat import FloatWaveform >>> filenames = [ ... "audio-for-tests/andreas-theme/track.mp3", ... "audio-for-tests/blippy-trance/track.mp3", ... "does-not-exist", ... ] >>> >>> batch = FloatWaveform.from_many_files(filenames)
The first two files are decoded as expected, with the
waveformfield containing a
>>> batch.name 'audio-for-tests/andreas-theme/track.mp3' >>> print(batch.exception) None >>> batch.waveform <babycat.FloatWaveform: 9586944 frames, 2 channels, 44100 hz>
>>> batch.name 'audio-for-tests/blippy-trance/track.mp3' >>> print(batch.exception) None >>> batch.waveform <babycat.FloatWaveform: 5293440 frames, 2 channels, 44100 hz>
For the third file, the
exceptionfield contains a reference to a
namefield helps us identify which file is missing.
>>> batch.name 'does-not-exist' >>> type(batch.exception) <class 'FileNotFoundError'> >>> print(batch.waveform) None >>>
Remember to raise exceptions when needed
from_many_files()will return exceptions but will not raise them for you. It is your responsibility to check every
exceptionfield for a not-
Noneexception that you can raise or intentionally ignore.
start_time_milliseconds (int, optional) – We discard any audio before this millisecond offset. By default, this does nothing and the audio is decoded from the beginning. Negative offsets are invalid.
end_time_milliseconds (int, optional) – We discard any audio after this millisecond offset. By default, this does nothing and the audio is decoded all the way to the end. If
start_time_millisecondsis specified, then
end_time_millisecondsmust be greater. The resulting
frame_rate_hz (int, optional) – A destination frame rate to resample the audio to. Do not specify this parameter if you wish Babycat to preserve the audio’s original frame rate. This does nothing if
frame_rate_hzis equal to the audio’s original frame rate.
num_channels (int, optional) – Set this to a positive integer
nto select the first
nchannels stored in the audio file. By default, Babycat will return all of the channels in the original audio. This will raise an exception if you specify a
num_channelsgreater than the actual number of channels in the audio.
convert_to_mono (bool, optional) – Set to
Trueto average all channels into a single monophonic (mono) channel. If
num_channels = nis also specified, then only the first
nchannels will be averaged. Note that
convert_to_monocannot be set to
Truewhile also setting
num_channels = 1.
zero_pad_ending (bool, optional) – If you set this to
True, Babycat will zero-pad the ending of the decoded waveform to ensure that the output waveform’s duration is exactly
end_time_milliseconds - start_time_milliseconds. By default,
zero_pad_ending = False, in which case the output waveform will be shorter than
end_time_milliseconds - start_time_millisecondsif the input audio is shorter than
resample_mode (int, optional) – If you set
frame_rate_hzto resample the audio when decoding, you can also set
resample_modeto pick which resampling backend to use. The
babycat.resample_modesubmodule contains the various available resampling algorithms compiled into Babycat. By default, Babycat resamples audio using libsamplerate at its highest-quality setting.
decoding_backend (int, optional) – Sets the audio decoding backend to use. Defaults to the Symphonia backend.
num_workers (int, optional) – The number of threads–Rust threads, not Python threads–to use for parallel decoding of the audio files in
filenames. By default, Babycat creates the same number of threads as the number of logical CPU cores on your machine.
A list of objects that contain a
FloatWaveformfor every successful encoding and a Python exception for every failed encoding. Look at the
FloatWaveform.decode_from_filename()for a list of possible exceptions that can be returned by this method.
- Return type