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

signalSignal 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

signalSignal object containing the audio data from the WAV file.

Return type

Signal

Notes

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.