clarity.utils.flac_encoder module

Class for encoding and decoding audio signals

using flac compression.

class clarity.utils.flac_encoder.FileDecoder(input_file: Path, output_file: Path | None = None)

Bases: FileDecoder

process() → tuple[ndarray, int]

Overwritten version of the process method from the pyflac decoder. Original process returns stereo signals in float64 format.

In this version, the data is returned using the original number of channels and in in16 format.

Returns:

A tuple of the decoded numpy audio array, and the sample rate

of the audio data.

Return type:

(tuple)

Raises:

DecoderProcessException – if any fatal read, write, or memory allocation error occurred (meaning decoding must stop)

class clarity.utils.flac_encoder.FlacEncoder(compression_level: int = 5)

Bases: object

Class for encoding and decoding audio signals using FLAC

It uses the pyflac library to encode and decode the audio data. And offers convenient methods for encoding and decoding audio data.

static decode(input_filename: Path | str) → tuple[np.ndarray, float]

Method to decode a flac file to wav audio data.

It uses the pyflac library to decode the flac file.

Parameters:

input_filename (pathlib.Path | str) – Path to the input FLAC file.

Returns:

The raw audio data.

Return type:

(np.ndarray)

Raises:

FileNotFoundError – If the flac file to decode does not exist.

encode(signal: np.ndarray, sample_rate: int, output_file: str | Path | None = None) → bytes

Method to encode the audio data using FLAC compressor.

It creates a WavEncoder object and uses it to encode the audio data.

Parameters:

• signal (np.ndarray) – The raw audio data to be compressed.

• sample_rate (int) – The sample rate of the audio data.

• output_file (str | Path) – Path to where to save the output FLAC file. If not specified, a temporary file will be created.

Returns:

The FLAC encoded audio signal.

Return type:

(bytes)

Raises:

ValueError – If the audio signal is not in np.int16 format.

class clarity.utils.flac_encoder.WavEncoder(signal: np.ndarray, sample_rate: int, output_file: str | Path | None = None, compression_level: int = 5, blocksize: int = 0, streamable_subset: bool = True, verify: bool = False)

Bases: _Encoder

Class offers an adaptation of the pyflac.encoder.FileEncoder to work directly with WAV signals as input.

process() → bytes

Process the audio data from the WAV file.

Returns:

The FLAC encoded bytes.

Return type:

(bytes)

Raises:

EncoderProcessException – if an error occurs when processing the samples

clarity.utils.flac_encoder.read_flac_signal(filename: Path) → tuple[ndarray, float]

Read a FLAC signal and return it as a numpy array

Parameters:

filename (Path) – The path to the FLAC file to read.

Returns:

The decoded signal. sample_rate (float): The sample rate of the signal.

Return type:

signal (np.ndarray)

clarity.utils.flac_encoder.save_flac_signal(signal: np.ndarray, filename: Path, signal_sample_rate: int, output_sample_rate: int | None = None, do_clip_signal: bool = False, do_soft_clip: bool = False, do_scale_signal: bool = False) → None

Function to save output signals.

• The output signal will be resample to output_sample_rate.

  If output_sample_rate is None, the output signal will have the same sample rate as the input signal.

• The output signal will be clipped to [-1, 1] if do_clip_signal is True

  and use soft clipped if do_soft_clip is True. Note that if do_clip_signal is False, do_soft_clip will be ignored. Note that if do_clip_signal is True, do_scale_signal will be ignored.

• The output signal will be scaled to [-1, 1] if do_scale_signal is True.

  If signal is scale, the scale factor will be saved in a TXT file. Note that if do_clip_signal is True, do_scale_signal will be ignored.

• The output signal will be saved as a FLAC file.

Parameters:

• signal (np.ndarray) – Signal to save

• filename (Path) – Path to save signal

• signal_sample_rate (int) – Sample rate of the input signal

• output_sample_rate (int) – Sample rate of the output signal

• do_clip_signal (bool) – Whether to clip signal

• do_soft_clip (bool) – Whether to apply soft clipping

• do_scale_signal (bool) – Whether to scale signal