Waveform.from_file()

static Waveform.from_file(filename, start_time_milliseconds=0, end_time_milliseconds=0, frame_rate_hz=0, num_channels=0, convert_to_mono=False, zero_pad_ending=False, repeat_pad_ending=False, resample_mode=0, decoding_backend=0)

Decodes audio stored in a local file.

Example

Decode an entire audio file with default arguments.

>>> from babycat import Waveform
>>> waveform = Waveform.from_file(
...     "audio-for-tests/andreas-theme/track.flac",
... )
>>> waveform
<babycat.Waveform: 9586415 frames, 2 channels, 44100 hz>
>>> waveform.num_frames
9586415
>>> waveform.num_channels
2
>>> waveform.frame_rate_hz
44100
>>> waveform.to_numpy().shape
(9586415, 2)

Example

Decode the first 30 seconds of the audio file.

>>> waveform = Waveform.from_file(
...     "audio-for-tests/andreas-theme/track.flac",
...     end_time_milliseconds=30_000,
... )
>>> waveform
<babycat.Waveform: 1323000 frames, 2 channels, 44100 hz>

Example

Decode the entire audio file and resampling up to 48,000hz.

>>> waveform = Waveform.from_file(
...     "audio-for-tests/andreas-theme/track.flac",
...     frame_rate_hz=48000,
... )
>>> waveform
<babycat.Waveform: 10434194 frames, 2 channels, 48000 hz>

Example

Decode the first 30 seconds and resample up to 48,000hz.

>>> waveform = Waveform.from_file(
...     "audio-for-tests/andreas-theme/track.flac",
...     end_time_milliseconds=30_000,
...     frame_rate_hz=48000,
... )
>>> waveform
<babycat.Waveform: 1440000 frames, 2 channels, 48000 hz>
Parameters

  • filename (str) – The path to an audio file on the local filesystem.

  • 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_milliseconds is specified, then end_time_milliseconds must 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_hz is equal to the audio’s original frame rate.

  • num_channels (int, optional) – Set this to a positive integer n to select the first n channels 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_channels greater than the actual number of channels in the audio.

  • convert_to_mono (bool, optional) – Set to True to average all channels into a single monophonic (mono) channel. If num_channels = n is also specified, then only the first n channels will be averaged. Note that convert_to_mono cannot be set to True while 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_milliseconds if the input audio is shorter than end_time_milliseconds. Note that setting zero_pad_ending = True is mutually exclusive with setting repeat_pad_ending = True.

  • repeat_pad_ending (bool, optional) – If you set this to True, Babycat will repeat the audio waveform to ensure that the output waveform’s duration is exactly end_time_milliseconds - start_time_milliseconds. By default, repeat_pad_ending = False, in which case the output waveform will be shorter than end_time_milliseconds - start_time_milliseconds. Note that setting repeat_pad_ending = True is mutually exclusive with setting zero_pad_ending = True.

  • resample_mode (int, optional) – If you set frame_rate_hz to resample the audio when decoding, you can also set resample_mode to pick which resampling backend to use. The babycat.resample_mode submodule 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.

Returns

A waveform decoded from filename.

Return type

Waveform

Raises