pyfar.io¶

Functions:

`audio_formats`()	Return a dictionary of available audio formats.
`audio_subtypes`([format])	Return a dictionary of available audio subtypes.
`default_audio_subtype`(format)	Return the default subtype for a given format.
`read`(filename)	Read any compatible pyfar object or numpy array (.far file) from disk.
`read_audio`(filename[, dtype])	Import an audio file as `Signal` object.
`read_sofa`(filename[, verify])	Import a SOFA file as pyfar object.
`read_wav`(filename)	Import a WAV file as `Signal` object.
`write`(filename[, compress])	Write any compatible pyfar object or numpy array and often used builtin types as .far file to disk.
`write_audio`(signal, filename[, subtype, ...])	Write a `Signal` object as a audio file to disk.
`write_wav`(signal, filename[, subtype, overwrite])	Write a `Signal` object as a WAV file to disk.

pyfar.io.audio_formats()[source]¶

Return a dictionary of available audio formats.

Notes

This function is a wrapper of soundfile.available_formats.

Examples

>>> import pyfar as pf
>>> pf.io.audio_formats()
{'FLAC': 'FLAC (FLAC Lossless Audio Codec)',
 'OGG': 'OGG (OGG Container format)',
 'WAV': 'WAV (Microsoft)',
 'AIFF': 'AIFF (Apple/SGI)',
 ...
 'WAVEX': 'WAVEX (Microsoft)',
 'RAW': 'RAW (header-less)',
 'MAT5': 'MAT5 (GNU Octave 2.1 / Matlab 5.0)'}

pyfar.io.audio_subtypes(format=None)[source]¶

Return a dictionary of available audio subtypes.

Parameters: format (str) – If given, only compatible subtypes are returned.

Notes

This function is a wrapper of soundfile.available_subtypes.

Examples

>>> import pyfar as pf
>>> pf.io.audio_subtypes('FLAC')
{'PCM_24': 'Signed 24 bit PCM',
 'PCM_16': 'Signed 16 bit PCM',
 'PCM_S8': 'Signed 8 bit PCM'}

pyfar.io.default_audio_subtype(format)[source]¶

Return the default subtype for a given format.

Notes

This function is a wrapper of soundfile.default_audio_subtype.

Examples

>>> import pyfar as pf
>>> pf.io.default_audio_subtype('WAV')
'PCM_16'
>>> pf.io.default_audio_subtype('MAT5')
'DOUBLE'

pyfar.io.read(filename)[source]¶

Read any compatible pyfar object or numpy array (.far file) from disk.

Parameters: filename (string, Path) – Input file. If no extension is provided, .far-suffix is added.
Returns: collection – Contains pyfar objects like { 'name1': 'obj1', 'name2': 'obj2' ... }.
Return type: dict

Examples

Read signal and orientations objects stored in a .far file.

>>> collection = pyfar.read('my_objs.far')
>>> my_signal = collection['my_signal']
>>> my_orientations = collection['my_orientations']

pyfar.io.read_audio(filename, dtype='float64', **kwargs)[source]¶

Import an audio file as Signal object.

Reads ‘wav’, ‘aiff’, ‘ogg’, and ‘flac’ files among others. For a complete list see audio_formats.

Parameters

filename (string, Path) – Input file.
dtype ({'float64', 'float32', 'int32', 'int16'}, optional) – Data type of the returned signal, by default 'float64'. Floating point audio data is typically in the range from -1.0 to 1.0. Note that 'int16' and 'int32' should only be used if the data was written in the same format. Integer data is in the range from -2**15 to 2**15-1 for 'int16' and from -2**31 to 2**31-1 for 'int32'.
**kwargs – Other keyword arguments to be passed to soundfile.read. This is needed, e.g, to read RAW audio files.

Returns

signal – Signal object containing the audio data.

Return type

Signal

Notes

This function is based on soundfile.read.
Reading int values from a float file will not scale the data to [-1.0, 1.0). If the file contains np.array([42.6], dtype='float32'), you will read np.array([43], dtype='int32') for dtype='int32'.

pyfar.io.read_sofa(filename, verify=True)[source]¶

Import a SOFA file as pyfar object.

Parameters

filename (string, Path) – Input SOFA file (cf. 1, 2).
verify (bool, optional) – Verify if the data contained in the SOFA file agrees with the AES69 standard (see references). If the verification fails, the SOFA file can be loaded by setting verify=False. The default is True

Returns

audio (pyfar audio object) – The audio object that is returned depends on the DataType of the SOFA object:
- Signal
  A Signal object is returned is the DataType is 'FIR', 'FIR-E', or 'FIRE'.
- FrequencyData
  A FrequencyData object is returned is the DataType is 'TF', 'TF-E', or 'TFE'.
The cshape of the object is is (M, R) with M being the number of measurements and R being the number of receivers from the SOFA file.
source_coordinates (Coordinates) – Coordinates object containing the data stored in SOFA_object.SourcePosition. The domain, convention and unit are automatically matched.
receiver_coordinates (Coordinates) – Coordinates object containing the data stored in SOFA_object.RecevierPosition. The domain, convention and unit are automatically matched.

Notes

This function uses the sofar package to read SOFA files 3.

References

1: https://www.sofaconventions.org
2: “AES69-2020: AES Standard for File Exchange-Spatial Acoustic Data File Format.”, 2020.
3: https://pyfar.org

pyfar.io.read_wav(filename)[source]¶

Import a WAV file as Signal object.

Parameters: filename (string, Path) – Input file.
Returns: signal – Signal object containing the audio data from the WAV file.
Return type: Signal

Notes

This function is based on read_audio.

pyfar.io.write(filename, compress=False, **objs)[source]¶

Write any compatible pyfar object or numpy array and often used builtin types as .far file to disk.

Parameters

filename (string) – Full path or filename. If now extension is provided, .far-suffix will be add to filename.
compress (bool) – Default is False (uncompressed). Compressed files take less disk space but need more time for writing and reading.
**objs – Objects to be saved as key-value arguments, e.g., name1=object1, name2=object2.

Examples

Save Signal object, Orientations objects and numpy array to disk.

>>> s = pyfar.Signal([1, 2, 3], 44100)
>>> o = pyfar.Orientations.from_view_up([1, 0, 0], [0, 1, 0])
>>> a = np.array([1,2,3])
>>> pyfar.io.write('my_objs.far', signal=s, orientations=o, array=a)

Notes

Supported builtin types are: bool, bytes, complex, float, frozenset, int, list, set, str and tuple

pyfar.io.write_audio(signal, filename, subtype=None, overwrite=True, **kwargs)[source]¶

Write a Signal object as a audio file to disk.

Writes ‘wav’, ‘aiff’, ‘ogg’, and ‘flac’ files among others. For a complete list see audio_formats.

Parameters

signal (Signal) – Object to be written.
filename (string, Path) – Output file. The format is determined from the file extension. See audio_formats for all possible formats.
subtype (str, optional) – The subtype of the sound file, the default value depends on the selected format (see default_audio_subtype). See audio_subtypes for all possible subtypes for a given format.
overwrite (bool) – Select wether to overwrite the audio file, if it already exists. The default is True.
**kwargs – Other keyword arguments to be passed to soundfile.write.

Notes

Signals are flattened before writing to disk (e.g. a signal with cshape = (3, 2) will be written to disk as a six channel audio file).
This function is based on soundfile.write.
Except for the subtypes 'FLOAT', 'DOUBLE' and 'VORBIS' ´ amplitudes larger than +/- 1 are clipped.

pyfar.io.write_wav(signal, filename, subtype=None, overwrite=True)[source]¶

Write a Signal object as a WAV file to disk.

Parameters

signal (Signal) – Object to be written.
filename (string, Path) – Output file.
overwrite (bool) – Select wether to overwrite the WAV file, if it already exists. The default is True.

Notes

Signals are flattened before writing to disk (e.g. a signal with cshape = (3, 2) will be written to disk as a six channel wav file).
This function is based on write_audio.
Except for the subtypes 'FLOAT' and 'DOUBLE', amplitudes larger than +/- 1 are clipped.