clarity.utils.file_io module

File I/O functions.

clarity.utils.file_io.read_jsonl(filename: str) → list

Read a jsonl file into a list of dictionaries.

clarity.utils.file_io.read_signal(filename: str | Path, sample_rate: float = 0.0, offset: int | float = 0, n_samples: int = -1, n_channels: int = 0, offset_is_samples: bool = False, allow_resample: bool = True) → ndarray

Read a wav format audio file and return as numpy array of floats.

The returned value will be a numpy array of floats of shape (n_samples, n_channels) for n_channels >= 2, and shape (n_samples,) for n_channels = 1.

If n_samples is set to a value other than -1, the specified number of samples will be read, or until the end of the file. An ‘offset’ can be set to start reading from a specified sample or time (in seconds).

The expected number of channels can be specified. If the file has a different number of channels, an error will be raised.

The expected sample rate can be specified. If the file has a different sample the file will be resampled to the expected sample rate, unless ‘allow_resample’ is set to False, in which case an error will be raised.

Parameters:

• filename (str|Path) – Name of file to read

• sample_rate (float) – The expected sample rate (default: 0.0 = any rate OK)

• offset (int, optional) – Offset in samples or seconds (from start). Default is 0.

• n_samples (int) – Number of samples.

• n_channels (int) – expected number of channel (default: 0 = any number OK)

• offset_is_samples (bool) – is offset measured in samples, (True) or seconds (False) (default: False)

• allow_resample (bool) – allow resampling if sample rate is different from expected rate. Else raise error (default: True)

Returns:

audio signal

Return type:

np.ndarray

clarity.utils.file_io.write_jsonl(filename: str, records: list) → None

Write a list of dictionaries to a jsonl file.

clarity.utils.file_io.write_signal(filename: str | Path, signal: ndarray, sample_rate: float, floating_point: bool = True, strict: bool = False) → None

Write a signal as fixed or floating point wav file.

Signals are passed as numpy arrays of floats of shape (n_samples, n_channels) for n_channels >= 1 or (n_samples,) for n_channels = 1.

Signals are floating point in the range [-1.0 to 1.0) but can be written as wav file with either 16 bit integers or floating point. In the former, the signals are scaled to map to the range -32768 to 32767 and clipped if necessary.

NB: setting ‘strict’ to True will raise error on overflow. This would be a more natural default but it would break existing code that did not check for overflow.

Parameters:

• filename (str|Path) – name of file in to write to.

• signal (ndarray) – signal to write.

• sample_rate (float) – sampling frequency.

• floating_point (bool) – write as floating point else an ints (default: True).

• strict (bool) – raise error if signal out of range for int16 (default: False).