Module `audioio.audioconverter`

Command line script for converting, downsampling, renaming and merging audio files.

audioconverter -o test.wav test.mp3

converts 'test.mp3' to 'test.wav'.

The script reads all input files with load_audio(), combines the audio and marker data and writes them along with the metadata to an output file using write_audio().

Thus, all formats supported by these functions and the installed python audio modules are available. This implies that MP3 files can be read via the audioread module, and they can be written via pydub. Many other input and output file formats are supported by the sndfile library, provided the SoundFile or wavefile python packages are installed.

Metadata and markers are preserved if possible.

Run

audioconverter -l

for a list of supported output file formats and

audioconverter -f wav -l

for a list of supported encodings for a given output format (-foption).

Running

audioconverter --help

prints

usage: audioconverter [-h] [--version] [-v] [-l] [-f FORMAT] [-e ENCODING] [-s SCALE] [-u [THRESH]] [-U [THRESH]]
                      [-d FAC] [-c CHANNELS] [-a KEY=VALUE] [-r KEY] [-n NUM] [-o OUTPATH]
                      [file ...]

Convert audio file formats.

positional arguments:
  file          one or more input files to be combined into a single output file

options:
  -h, --help    show this help message and exit
  --version     show program's version number and exit
  -v            print debug output
  -l            list supported file formats and encodings
  -f FORMAT     audio format of output file
  -e ENCODING   audio encoding of output file
  -s SCALE      scale the data by factor SCALE
  -u [THRESH]   unwrap clipped data with threshold relative to maximum of input range (default is 0.5) and divide by
                two
  -U [THRESH]   unwrap clipped data with threshold relative to maximum of input range (default is 0.5) and clip
  -d FAC        downsample by integer factor
  -c CHANNELS   comma and dash separated list of channels to be saved (first channel is 0)
  -a KEY=VALUE  add key-value pairs to metadata. Keys can have section names separated by "."
  -r KEY        remove keys from metadata. Keys can have section names separated by "."
  -n NUM        merge NUM input files into one output file
  -o OUTPATH    path or filename of output file. Metadata keys enclosed in curly braces will be replaced by their
                values from the input file

version 2.0.0 by Benda-Lab (2020-2024)

Functions

def add_arguments(parser)

Add command line arguments to parser.

Parameters

parser : argparse.ArgumentParser: The parser.

def parse_channels(cstr)

Parse channel selection string.

Parameters

cstr : str: String with comma separated channels and dash separated channel ranges.

Returns

channels : list of int: List of selected channels.

def check_format(format)

Check whether requested audio format is valid and supported.

If the format is not available print an error message on console.

Parameters

format : string: Audio format to be checked.

Returns

valid : bool: True if the requested audio format is valid.

def list_formats_encodings(data_format)

List available formats or encodings.

Parameters

data_format : None or str: If provided, list encodings for this data format. Otherwise, list available audio file formats.

def make_outfile(outpath, infile, data_format, blocks, format_from_ext)

Make name for output file.

Parameters

outpath : None or str: Requested output path.
infile : str: Name of the input file.
data_format : None or str: Requested output file format.
blocks : bool: If True, produce outputfile for group of input files.
format_from_ext : function: Function that inspects a filename for its extension and deduces a file format from it.

Returns

outfile : str: Name of output file.
data_format : str: Format of output file.

def modify_data(data, rate, metadata, channels, scale, unwrap_clip, unwrap_thresh, ampl_max, unit, decimate_fac)

Modify audio data and add modifications to metadata.

Parameters

data : 2-D array of float: The data to be written into the output file.
rate : float: Sampling rate of the data in Hertz.
metadata : nested dict: Metadata.
channels : list of int: List of channels to be selected from the data.
scale : float: Scaling factor to be applied to the data.
unwrap_clip : float: If larger than zero, unwrap the data using this as a threshold relative to ampl_max, and clip the data at +-ampl_max.
unwrap_thresh : float: If larger than zero, unwrap the data using this as a threshold relative to ampl_max, and downscale the data by a factor of two. Also update the gain in the metadata.
ampl_max : float: Maximum amplitude of the input range.
unit : str: Unit of the input range.
decimate_fac : int: Downsample the data by this factor.

Returns

def format_outfile(outfile, metadata)

Put metadata values into name of output file.

Parameters

outfile : str: Name of output file. May contain metadata keys enclosed in curly braces.
metadata : nested dict: Metadata.

Returns

outfile : str: Name of output file.

def main(*cargs)

Command line script for converting, downsampling, renaming and merging audio files.

Parameters

cargs : list of strings: Command line arguments as returned by sys.argv[1:].