Module `audioio.audiowriter`

Write numpy arrays of floats to audio files.

write_audio(): write audio data to file.
available_formats(): audio file formats supported by any of the installed audio modules.
available_encodings(): encodings of an audio file format supported by any of the installed audio modules.
format_from_extension(): deduce audio file format from file extension.

The data to be written are 1-D or 2-D numpy arrays of floats ranging between -1 and 1 with first axis time and (optional) second axis channel.

For support of more audio formats, you might need to install additional packages. See installation for further instructions.

For a demo, run the script as:

python -m src.audioio.audiowriter

Global variables

var audio_formats_funcs: List of implemented formats() functions.

Each element of the list is a tuple with the module's name and the formats() function.
var audio_encodings_funcs: List of implemented encodings() functions.

Each element of the list is a tuple with the module's name and the encodings() function.
var audio_writer_funcs: List of implemented write() functions.

Each element of the list is a tuple with the module's name and the write() function.

Functions

def main(*args)

Call demo with command line arguments.

Parameters

args : list of strings: Command line arguments as provided by sys.argv[1:]

def format_from_extension(filepath)

Deduce audio file format from file extension.

Parameters

filepath : string: Name of the audio file.

Returns

format : string: Audio format deduced from file extension.

def formats_wave()

Audio file formats supported by the wave module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_wave(format)

Encodings of an audio file format supported by the wave module.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

def write_wave(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the wave module from pythons standard libray.

Documentation

https://docs.python.org/3.8/library/wave.html

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format, only 'WAV' is supported.

encoding : string or None

Encoding of the data: 'PCM_32', 'PCM_16', or 'PCM_U8'. If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The wave module is not installed.
*
Writing of the data failed.
ValueError: File format or encoding not supported.

def formats_ewave()

Audio file formats supported by the ewave module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_ewave(format)

Encodings of an audio file format supported by the ewave module.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

def write_ewave(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the ewave module from pythons standard libray.

Documentation

https://github.com/melizalab/py-ewave

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format, only 'WAV' and 'WAVEX' are supported.

encoding : string or None

Encoding of the data: 'PCM_64', 'PCM_32', PCM_16', 'FLOAT', 'DOUBLE' If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The ewave module is not installed.
*
Writing of the data failed.
ValueError: File format or encoding not supported.

def formats_wavfile()

Audio file formats supported by the scipy.io.wavfile module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_wavfile(format)

Encodings of an audio file format supported by the scipy.io.wavfile module.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

def write_wavfile(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the scipy.io.wavfile module.

Documentation

http://docs.scipy.org/doc/scipy/reference/io.html

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format, only 'WAV' is supported.

encoding : string or None

Encoding of the data: 'PCM_64', 'PCM_32', PCM_16', 'PCM_U8', 'FLOAT', 'DOUBLE' If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The wavfile module is not installed.
ValueError: File format or encoding not supported.

* Writing of the data failed.

def formats_soundfile()

Audio file formats supported by the SoundFile module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_soundfile(format)

Encodings of an audio file format supported by the SoundFile module.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

def write_soundfile(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the SoundFile module (based on libsndfile).

Documentation

http://pysoundfile.readthedocs.org

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format.

encoding : string or None

Encoding of the data. If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The SoundFile module is not installed.

* Writing of the data failed.

def formats_wavefile()

Audio file formats supported by the wavefile module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_wavefile(format)

Encodings supported by the wavefile module.

Parameters

format : str: The file format (ignored).

Returns

encodings : list of strings: List of supported encodings as strings.

def write_wavefile(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the wavefile module (based on libsndfile).

Documentation

https://github.com/vokimon/python-wavefile

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format as in wavefile.Format.

encoding : string or None

Encoding of the data as in wavefile.Format. If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The wavefile module is not installed.
ValueError: File format or encoding not supported.

* Writing of the data failed.

def formats_pydub()

Audio file formats supported by the Pydub module.

Returns

formats : list of strings: List of supported file formats as strings.

def encodings_pydub(format)

Encodings of an audio file format supported by the Pydub module.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

def write_pydub(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue')

Write audio data using the Pydub module.

Documentation

https://github.com/jiaaro/pydub

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format, everything ffmpeg or avtools are supporting.

encoding : string or None

Encoding of the data. If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

Raises

ImportError: The Pydub module is not installed.
*
Writing of the data failed.
ValueError: File format or encoding not supported.

def available_formats()

Audio file formats supported by any of the installed audio modules.

Returns

formats : list of strings: List of supported file formats as strings.

Examples

>>> from audioio import available_formats
>>> f = available_formats()
>>> printf(f)
['3G2', '3GP', 'A64', 'AC3', 'ADTS', 'ADX', 'AIFF', ...,  'WAV', 'WAVEX', 'WEBM', 'WEBM_CHUNK', 'WEBM_DASH_MANIFEST', 'WEBP', 'WEBVTT', 'WTV', 'WV', 'WVE', 'XI', 'XV', 'YUV4MPEGPIPE']

def available_encodings(format)

Encodings of an audio file format supported by any of the installed audio modules.

Parameters

format : str: The file format.

Returns

encodings : list of strings: List of supported encodings as strings.

Example

>>> from audioio import available_encodings
>>> e = available_encodings('WAV')
>>> printf(e)
['ALAW', 'DOUBLE', 'FLOAT', 'G721_32', 'GSM610', 'IMA_ADPCM', 'MS_ADPCM', 'PCM_16', 'PCM_24', 'PCM_32', 'PCM_U8', 'ULAW']

def write_audio(filepath, data, rate, metadata=None, locs=None, labels=None, format=None, encoding=None, marker_hint='cue', verbose=0)

Write audio data, metadata, and marker to file.

Parameters

filepath : string

Full path and name of the file to write.

data : 1-D or 2-D array of floats

Array with the data (first index time, second index channel, values within -1.0 and 1.0).

rate : float

Sampling rate of the data in Hertz.

metadata : None or nested dict

Metadata as key-value pairs. Values can be strings, integers, or dictionaries.

locs : None or 1-D or 2-D array of ints

Marker positions (first column) and spans (optional second column) for each marker (rows).

labels : None or 2-D array of string objects

Labels (first column) and texts (optional second column) for each marker (rows).

format : string or None

File format. If None deduce file format from filepath. See available_formats() for possible values.

encoding : string or None

Encoding of the data. See available_encodings() for possible values. If None or empty string use 'PCM_16'.

marker_hint : str

'cue': store markers in cue and and adtl chunks.
'lbl': store markers in avisoft lbl chunk.

verbose : int

If >0 show detailed error/warning messages.

Raises

ValueError: filepath is empty string.
IOError: Writing of the data failed.

Examples

import numpy as np
from audioio import write_audio

rate = 28000.0
freq = 800.0
time = np.arange(0.0, 1.0, 1/rate) # one second
data = np.sin(2.0*np.p*freq*time)        # 800Hz sine wave
md = dict(Artist='underscore_')          # metadata

write_audio('audio/file.wav', data, rate, md)

def demo(file_path, channels=2, encoding='')

Demo of the audiowriter functions.

Parameters

file_path : string: File path of an audio file.
encoding : string: Encoding to be used.