pysndfile package


pysndfile.sndio module

sndio is a simple interface for reading and writing arbitrary sound files. The module contains 3 functions.

functions:
pysndfile.sndio.get_info():: retrieve information from a sound file.
pysndfile.sndio.get_markers():: retrieve markers from aiff/ or wav files.
pysndfile.sndio.read():: read data and meta data from sound file.
pysndfile.sndio.write():: create a sound file from a given numpy array.
pysndfile.sndio.get_info(name, extended_info=False)[source]

retrieve information from a sound file

Parameters:
  • name (str) – sndfile name
  • extended_info (bool) –
Returns:

3 or 5 tuple with meta information read from the soundfile in case extended_info is False a 3-tuple comprising samplerate, encoding (str), major format is returned in case extended_info is True a 5-tuple comprising additionally the number of frames and the number of channels is returned.

pysndfile.sndio.get_markers(name)[source]

retrieve markers from sound file

Parameters:name (str) – sound file name
Returns:list of marker tuples containing the marker time and marker label.
Return type:List

Note: following the implementation of libsndfile marker labels will be empty strings for all but aiff files.

pysndfile.sndio.read(name, end=None, start=0, dtype=<class 'numpy.float64'>, return_format=False, sf_strings=None, force_2d=False)[source]

read samples from arbitrary sound files into a numpy array. May return subsets of samples as specified by start and end arguments (Def all samples) normalizes samples to [-1,1] if the datatype is a floating point type

The returned array is 1D for mono sound files and 2D with the channels in the columns for higher number of channels. If force_2d is given mono sound files will be returned in an array with shape (num_frames, 1)

Parameters

Parameters:
  • name (str) – sound file name
  • end (Union[int, None]) – end sample frame position (not included into the segment to be returned) default=None -> read all samples
  • start (int) – first sample frame to read default=0
  • dtype (numpy.dtype) – data type of the numpy array that will be returned.
  • return_format (bool) – if set then the return tuple will contain an additional element containing the sound file major format
  • sf_strings (Union[None,dict]) – if a dict is given the dict elements will be set to the strings that are available in the sound file.
  • force_2d (bool) – forces the returned array to have 2 dimensions with
Returns:

3 or 4 -tuple containing data (1d for mon sounds 2d for multi channel sounds, where channels are in the columns), samplerate (int) and encoding (str), in case return_format is True then the next element contains the major format of the sound file (can be used to recreate a sound file with an identical format).

Return type:

Union[Tuple(numpy.array, int, str),Tuple(numpy.array, int, str, str)]

pysndfile.sndio.write(name, data, rate=44100, format='aiff', enc='pcm16', sf_strings=None)[source]

Write datavector to sndfile using samplerate, format and encoding as specified valid format strings are all the keys in the dict pysndfile.fileformat_name_to_id valid encodings are those that are supported by the selected format from the list of keys in pysndfile.encoding_name_to_id.

Parameters:
  • name (str) – sndfile name
  • data (numpy.array) – array containing sound data. For mono files an 1d array can be given, for multi channel sound files sound frames are in the rows and data channels in the columns.
  • rate (int) – sample rate default s to 44100
  • format (str) – sndfile major format default=aiff
  • enc (str) – sndfile encoding default=pcm16
  • sf_strings (Union[dict, None]) – dictionary containing bytes in ascii encoding to be written as meta data into the sound file. dictionary keys are limited to the keys available in stringtype_name_to_id` sf_strings arguments are only supported when the file format supports it. This are currently only the [aiff, wav, wavex, caf] formats. Note that each format imposes a particular limit to the length of individual strings. These lengths are stored in the dict max_supported_string_length. If any of your strings exceeds the limit given in that dict a RuntimeError will be produced
Returns:

number of sample frames written.

Return type:

int


PySndfile wrapper class and methods

Mappings from libsndfile enums to pysndfile strings

pysndfile.stringtype_name_to_id
dict mapping of pysndfile's stringtype nams to libsndfile's stringtype ids.
pysndfile.stringtype_id_to_name
dict mapping of libsndfile's stringtype ids to pysndfile's stringtype names.
pysndfile.commands_name_to_id
dict mapping of pysndfile's commandtype names to libsndfile's commandtype ids.
pysndfile.commands_id_to_name
dict mapping of libsndfile's commandtype ids to pysndfile's commandtype names.
pysndfile.endian_name_to_id
dict mapping of pysndfile's endian names to libsndfile's endian ids.
pysndfile.endian_id_to_name
dict mapping of libsndfile's endian ids to pysndfile's endian names.
pysndfile.fileformat_name_to_id
dict mapping of pysndfile's fileformat names to libsndfile's major fileformat ids.
pysndfile.fileformat_id_to_name
dict mapping of libsndfile's major fileformat ids to pysndfile's major fileformat names.

Support functions

pysndfile.construct_format(major, encoding)

construct a format specification for libsndfile from major format string and encoding string

pysndfile.get_pysndfile_version()

return tuple describing the version of pysndfile

pysndfile.get_sndfile_version()

return a tuple of ints representing the version of libsndfile that is used

pysndfile.get_sndfile_formats()

Return lists of available file formats supported by libsndfile and pysndfile.

Returns:list of strings representing all major sound formats that can be handled by the libsndfile library and the pysndfile interface.
pysndfile.get_sndfile_encodings(major)

Return lists of available encoding for the given sndfile format.

Parameters

Parameters:major – (str) sndfile format for that the list of available encodings should be returned. format should be specified as a string, using one of the strings returned by get_sndfile_formats()
pysndfile.get_sf_log()

retrieve internal log from libsndfile, notably useful in case of errors.

Returns:string representing the internal error log managed by libsndfile

PySndfile class

class pysndfile.PySndfile

Bases: object

PySndfile is a python class for reading/writing audio files.

PySndfile is proxy for the SndfileHandle class in sndfile.hh Once an instance is created, it can be used to read and/or write data from/to numpy arrays, query the audio file meta-data, etc…

Parameters:
  • filename – <string or int> name of the file to open (string), or file descriptor (integer)
  • mode – <string> ‘r’ for read, ‘w’ for write, or ‘rw’ for read and write.
  • format – <int> Required when opening a new file for writing, or to read raw audio files (without header). See function construct_format().
  • channels – <int> number of channels.
  • samplerate – <int> sampling rate.
Returns:

valid PySndfile instance. An IOError exception is thrown if any error is encountered in libsndfile. A ValueError exception is raised if the arguments are invalid.

Notes

  • the files will be opened with auto clipping set to True see the member set_autoclipping for more information.
  • the soundfile will be closed when the class is destroyed
  • format, channels and samplerate need to be given only in the write modes and for raw files.
channels(self)
Returns:<int> number of channels of sndfile
close(self)

Closes file and deallocates internal structures

command(self, command, arg=0)

interface for passing commands via sf_command to underlying soundfile using sf_command(this_sndfile, command_id, NULL, arg)

param command:

<string or int> libsndfile command macro to be used. They can be specified either as string using the command macros name, or the command id.

Supported commands are:

SFC_SET_NORM_FLOAT
SFC_SET_NORM_DOUBLE
SFC_GET_NORM_FLOAT
SFC_GET_NORM_DOUBLE
SFC_SET_SCALE_FLOAT_INT_READ
SFC_SET_SCALE_INT_FLOAT_WRITE
SFC_SET_ADD_PEAK_CHUNK
SFC_UPDATE_HEADER_NOW
SFC_SET_UPDATE_HEADER_AUTO
SFC_WAVEX_GET_AMBISONIC
SFC_WAVEX_SET_AMBISONIC
SFC_RAW_NEEDS_ENDSWAP
param arg:<int> additional argument of the command
return:<int> 1 for success or True, 0 for failure or False
encoding_str(self)
Returns:string representation of encoding (e.g. pcm16)

see pysndfile.get_sndfile_encodings() for a list of available encoding strings that are supported by a given sndfile format

error(self)

report error numbers related to the current sound file

format(self)
Returns:<int> raw format specification that was used to create the present PySndfile instance.
frames(self)
Returns:<int> number for frames (number of samples per channel)
get_cue_count(self)

get number of cue markers.

get_cue_mrks(self)

get all cue markers.

Gets list of tuple of positions and related names of embedded markers for aiff and wav files, due to a limited support of cue names in libsndfile cue names are not retrieved for wav files.

get_name(self)
Returns:<str> filename that was used to open the underlying sndfile
get_strings(self)

get all stringtypes from the sound file.

see stringtype_name_to_id for the list of strings that are supported by the libsndfile version you use.

major_format_str(self)
Returns:short string representation of major format (e.g. aiff)

see pysndfile.get_sndfile_formats() for a complete lst of fileformats

read_frames(self, sf_count_t nframes=-1, dtype=np.float64, force_2d=False, fill_value=None, min_read=0)

Read the given number of frames and put the data into a numpy array of the requested dtype.

Parameters:
  • nframes (int) – number of frames to read (default = -1 -> read all).
  • dtype (numpy.dtype) – data type of the returned array containing read data (see note).
  • force_2d (bool) – always return 2D arrays even if file is mono
  • fill_value (any tye that can be assigned to an array containing dtype) – value to use for filling frames in case nframes is larger than the file
  • min_read – when fill_value is not None and EOFError will be thrown when the number of read sample frames is equal to or lower than this value
Returns:

np.array<dtype> with sound data

Notes

  • One column per channel.
rewind(self, mode='rw')

rewind read/write/read and write position given by mode to start of file

samplerate(self)
Returns:<int> samplerate
seek(self, sf_count_t offset, int whence=C_SEEK_SET, mode='rw')

Seek into audio file: similar to python seek function, taking only in account audio data.

Parameters:
  • offset – <int> the number of frames (eg two samples for stereo files) to move relatively to position set by whence.
  • whence – <int> only 0 (beginning), 1 (current) and 2 (end of the file) are valid.
  • mode – <string> If set to ‘rw’, both read and write pointers are updated. If ‘r’ is given, only read pointer is updated, if ‘w’, only the write one is (this may of course make sense only if you open the file in a certain mode).
Returns:

<int> the number of frames from the beginning of the file

Notes

  • Offset relative to audio data: meta-data are ignored.
  • if an invalid seek is given (beyond or before the file), an IOError is raised; note that this is different from the seek method of a File object.
seekable(self)
Returns:<bool> true for soundfiles that support seeking
set_auto_clipping(self, arg=True)

enable auto clipping when reading/writing samples from/to sndfile.

auto clipping is enabled by default. auto clipping is required by libsndfile to properly handle scaling between sndfiles with pcm encoding and float representation of the samples in numpy. When auto clipping is set to on reading pcm data into a float vector and writing it back with libsndfile will reproduce the original samples. If auto clipping is off, samples will be changed slightly as soon as the amplitude is close to the sample range because libsndfile applies slightly different scaling factors during read and write.

Parameters:arg – <bool> indicator of the desired clipping state
Returns:<int> 1 for success, 0 for failure
set_string(self, stringtype_name, string)

set one of the stringtype to the string given as argument. If you try to write a stringtype that is not supported by the library a RuntimeError will be raised If you try to write a string with length exceeding the length that can be read by libsndfile version 1.0.28 a RuntimeError will be raised as well these limits are stored in the dict max_supported_string_length.

set_strings(self, sf_strings_dict)

set all strings provided as key value pairs in sf_strings_dict. If you try to write a stringtype that is not supported by the library a RuntimeError will be raised. If you try to write a string with length exceeding the length that can be read by libsndfile version 1.0.28 a RuntimeError will be raised as well these limits are stored in the dict max_supported_string_length.

strError(self)

report error strings related to the current sound file

writeSync(self)

call the operating system’s function to force the writing of all file cache buffers to disk the file.

No effect if file is open as read

write_frames(self, ndarray input)

write 1 or 2 dimensional array into sndfile.

Parameters:input – <numpy array> containing data to write.
Returns:int representing the number of frames that have been written
Notes
  • One column per channel.
  • updates the write pointer.
  • if the input type is float, and the file encoding is an integer type, you should make sure the input data are normalized normalized data (that is in the range [-1..1] - which will corresponds to the maximum range allowed by the integer bitwidth).