"""python-soundfile is an audio library based on libsndfile, CFFI and NumPy. Sound files can be read or written directly using the functions `read()` and `write()`. To read a sound file in a block-wise fashion, use `blocks()`. Alternatively, sound files can be opened as `SoundFile` objects. For further information, see https://python-soundfile.readthedocs.io/. """ __version__ = "0.12.1" import os as _os import sys as _sys from os import SEEK_SET, SEEK_CUR, SEEK_END from ctypes.util import find_library as _find_library from _soundfile import ffi as _ffi try: _unicode = unicode # doesn't exist in Python 3.x except NameError: _unicode = str _str_types = { 'title': 0x01, 'copyright': 0x02, 'software': 0x03, 'artist': 0x04, 'comment': 0x05, 'date': 0x06, 'album': 0x07, 'license': 0x08, 'tracknumber': 0x09, 'genre': 0x10, } _formats = { 'WAV': 0x010000, # Microsoft WAV format (little endian default). 'AIFF': 0x020000, # Apple/SGI AIFF format (big endian). 'AU': 0x030000, # Sun/NeXT AU format (big endian). 'RAW': 0x040000, # RAW PCM data. 'PAF': 0x050000, # Ensoniq PARIS file format. 'SVX': 0x060000, # Amiga IFF / SVX8 / SV16 format. 'NIST': 0x070000, # Sphere NIST format. 'VOC': 0x080000, # VOC files. 'IRCAM': 0x0A0000, # Berkeley/IRCAM/CARL 'W64': 0x0B0000, # Sonic Foundry's 64 bit RIFF/WAV 'MAT4': 0x0C0000, # Matlab (tm) V4.2 / GNU Octave 2.0 'MAT5': 0x0D0000, # Matlab (tm) V5.0 / GNU Octave 2.1 'PVF': 0x0E0000, # Portable Voice Format 'XI': 0x0F0000, # Fasttracker 2 Extended Instrument 'HTK': 0x100000, # HMM Tool Kit format 'SDS': 0x110000, # Midi Sample Dump Standard 'AVR': 0x120000, # Audio Visual Research 'WAVEX': 0x130000, # MS WAVE with WAVEFORMATEX 'SD2': 0x160000, # Sound Designer 2 'FLAC': 0x170000, # FLAC lossless file format 'CAF': 0x180000, # Core Audio File format 'WVE': 0x190000, # Psion WVE format 'OGG': 0x200000, # Xiph OGG container 'MPC2K': 0x210000, # Akai MPC 2000 sampler 'RF64': 0x220000, # RF64 WAV file 'MP3': 0x230000, # MPEG-1/2 audio stream } _subtypes = { 'PCM_S8': 0x0001, # Signed 8 bit data 'PCM_16': 0x0002, # Signed 16 bit data 'PCM_24': 0x0003, # Signed 24 bit data 'PCM_32': 0x0004, # Signed 32 bit data 'PCM_U8': 0x0005, # Unsigned 8 bit data (WAV and RAW only) 'FLOAT': 0x0006, # 32 bit float data 'DOUBLE': 0x0007, # 64 bit float data 'ULAW': 0x0010, # U-Law encoded. 'ALAW': 0x0011, # A-Law encoded. 'IMA_ADPCM': 0x0012, # IMA ADPCM. 'MS_ADPCM': 0x0013, # Microsoft ADPCM. 'GSM610': 0x0020, # GSM 6.10 encoding. 'VOX_ADPCM': 0x0021, # OKI / Dialogix ADPCM 'NMS_ADPCM_16': 0x0022, # 16kbs NMS G721-variant encoding. 'NMS_ADPCM_24': 0x0023, # 24kbs NMS G721-variant encoding. 'NMS_ADPCM_32': 0x0024, # 32kbs NMS G721-variant encoding. 'G721_32': 0x0030, # 32kbs G721 ADPCM encoding. 'G723_24': 0x0031, # 24kbs G723 ADPCM encoding. 'G723_40': 0x0032, # 40kbs G723 ADPCM encoding. 'DWVW_12': 0x0040, # 12 bit Delta Width Variable Word encoding. 'DWVW_16': 0x0041, # 16 bit Delta Width Variable Word encoding. 'DWVW_24': 0x0042, # 24 bit Delta Width Variable Word encoding. 'DWVW_N': 0x0043, # N bit Delta Width Variable Word encoding. 'DPCM_8': 0x0050, # 8 bit differential PCM (XI only) 'DPCM_16': 0x0051, # 16 bit differential PCM (XI only) 'VORBIS': 0x0060, # Xiph Vorbis encoding. 'OPUS': 0x0064, # Xiph/Skype Opus encoding. 'ALAC_16': 0x0070, # Apple Lossless Audio Codec (16 bit). 'ALAC_20': 0x0071, # Apple Lossless Audio Codec (20 bit). 'ALAC_24': 0x0072, # Apple Lossless Audio Codec (24 bit). 'ALAC_32': 0x0073, # Apple Lossless Audio Codec (32 bit). 'MPEG_LAYER_I': 0x0080, # MPEG-1 Audio Layer I. 'MPEG_LAYER_II': 0x0081, # MPEG-1 Audio Layer II. 'MPEG_LAYER_III': 0x0082, # MPEG-2 Audio Layer III. } _endians = { 'FILE': 0x00000000, # Default file endian-ness. 'LITTLE': 0x10000000, # Force little endian-ness. 'BIG': 0x20000000, # Force big endian-ness. 'CPU': 0x30000000, # Force CPU endian-ness. } # libsndfile doesn't specify default subtypes, these are somehow arbitrary: _default_subtypes = { 'WAV': 'PCM_16', 'AIFF': 'PCM_16', 'AU': 'PCM_16', # 'RAW': # subtype must be explicit! 'PAF': 'PCM_16', 'SVX': 'PCM_16', 'NIST': 'PCM_16', 'VOC': 'PCM_16', 'IRCAM': 'PCM_16', 'W64': 'PCM_16', 'MAT4': 'DOUBLE', 'MAT5': 'DOUBLE', 'PVF': 'PCM_16', 'XI': 'DPCM_16', 'HTK': 'PCM_16', 'SDS': 'PCM_16', 'AVR': 'PCM_16', 'WAVEX': 'PCM_16', 'SD2': 'PCM_16', 'FLAC': 'PCM_16', 'CAF': 'PCM_16', 'WVE': 'ALAW', 'OGG': 'VORBIS', 'MPC2K': 'PCM_16', 'RF64': 'PCM_16', 'MP3': 'MPEG_LAYER_III', } _ffi_types = { 'float64': 'double', 'float32': 'float', 'int32': 'int', 'int16': 'short' } try: # packaged lib (in _soundfile_data which should be on python path) if _sys.platform == 'darwin': from platform import machine as _machine _packaged_libname = 'libsndfile_' + _machine() + '.dylib' elif _sys.platform == 'win32': from platform import architecture as _architecture _packaged_libname = 'libsndfile_' + _architecture()[0] + '.dll' elif _sys.platform == 'linux': from platform import machine as _machine _packaged_libname = 'libsndfile_' + _machine() + '.so' else: raise OSError('no packaged library for this platform') import _soundfile_data # ImportError if this doesn't exist _path = _os.path.dirname(_soundfile_data.__file__) # TypeError if __file__ is None _full_path = _os.path.join(_path, _packaged_libname) _snd = _ffi.dlopen(_full_path) # OSError if file doesn't exist or can't be loaded except (OSError, ImportError, TypeError): try: # system-wide libsndfile: _libname = _find_library('sndfile') if _libname is None: raise OSError('sndfile library not found using ctypes.util.find_library') _snd = _ffi.dlopen(_libname) except OSError: # Try explicit file name, if the general does not work (e.g. on nixos) if _sys.platform == 'darwin': _explicit_libname = 'libsndfile.dylib' elif _sys.platform == 'win32': _explicit_libname = 'libsndfile.dll' elif _sys.platform == 'linux': _explicit_libname = 'libsndfile.so' else: raise # Homebrew on Apple M1 uses a `/opt/homebrew/lib` instead of # `/usr/local/lib`. We are making sure we pick that up. from platform import machine as _machine if _sys.platform == 'darwin' and _machine() == 'arm64': _hbrew_path = '/opt/homebrew/lib/' if _os.path.isdir('/opt/homebrew/lib/') \ else '/usr/local/lib/' _snd = _ffi.dlopen(_os.path.join(_hbrew_path, _explicit_libname)) else: _snd = _ffi.dlopen(_explicit_libname) __libsndfile_version__ = _ffi.string(_snd.sf_version_string()).decode('utf-8', 'replace') if __libsndfile_version__.startswith('libsndfile-'): __libsndfile_version__ = __libsndfile_version__[len('libsndfile-'):] def read(file, frames=-1, start=0, stop=None, dtype='float64', always_2d=False, fill_value=None, out=None, samplerate=None, channels=None, format=None, subtype=None, endian=None, closefd=True): """Provide audio data from a sound file as NumPy array. By default, the whole file is read from the beginning, but the position to start reading can be specified with *start* and the number of frames to read can be specified with *frames*. Alternatively, a range can be specified with *start* and *stop*. If there is less data left in the file than requested, the rest of the frames are filled with *fill_value*. If no *fill_value* is specified, a smaller array is returned. Parameters ---------- file : str or int or file-like object The file to read from. See `SoundFile` for details. frames : int, optional The number of frames to read. If *frames* is negative, the whole rest of the file is read. Not allowed if *stop* is given. start : int, optional Where to start reading. A negative value counts from the end. stop : int, optional The index after the last frame to be read. A negative value counts from the end. Not allowed if *frames* is given. dtype : {'float64', 'float32', 'int32', 'int16'}, optional Data type of the returned array, by default ``'float64'``. Floating point audio data is typically in the range from ``-1.0`` to ``1.0``. 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'``. .. note:: 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'``. Returns ------- audiodata : `numpy.ndarray` or type(out) A two-dimensional (frames x channels) NumPy array is returned. If the sound file has only one channel, a one-dimensional array is returned. Use ``always_2d=True`` to return a two-dimensional array anyway. If *out* was specified, it is returned. If *out* has more frames than available in the file (or if *frames* is smaller than the length of *out*) and no *fill_value* is given, then only a part of *out* is overwritten and a view containing all valid frames is returned. samplerate : int The sample rate of the audio file. Other Parameters ---------------- always_2d : bool, optional By default, reading a mono sound file will return a one-dimensional array. With ``always_2d=True``, audio data is always returned as a two-dimensional array, even if the audio file has only one channel. fill_value : float, optional If more frames are requested than available in the file, the rest of the output is be filled with *fill_value*. If *fill_value* is not specified, a smaller array is returned. out : `numpy.ndarray` or subclass, optional If *out* is specified, the data is written into the given array instead of creating a new array. In this case, the arguments *dtype* and *always_2d* are silently ignored! If *frames* is not given, it is obtained from the length of *out*. samplerate, channels, format, subtype, endian, closefd See `SoundFile`. Examples -------- >>> import soundfile as sf >>> data, samplerate = sf.read('stereo_file.wav') >>> data array([[ 0.71329652, 0.06294799], [-0.26450912, -0.38874483], ... [ 0.67398441, -0.11516333]]) >>> samplerate 44100 """ with SoundFile(file, 'r', samplerate, channels, subtype, endian, format, closefd) as f: frames = f._prepare_read(start, stop, frames) data = f.read(frames, dtype, always_2d, fill_value, out) return data, f.samplerate def write(file, data, samplerate, subtype=None, endian=None, format=None, closefd=True): """Write data to a sound file. .. note:: If *file* exists, it will be truncated and overwritten! Parameters ---------- file : str or int or file-like object The file to write to. See `SoundFile` for details. data : array_like The data to write. Usually two-dimensional (frames x channels), but one-dimensional *data* can be used for mono files. Only the data types ``'float64'``, ``'float32'``, ``'int32'`` and ``'int16'`` are supported. .. note:: The data type of *data* does **not** select the data type of the written file. Audio data will be converted to the given *subtype*. Writing int values to a float file will *not* scale the values to [-1.0, 1.0). If you write the value ``np.array([42], dtype='int32')``, to a ``subtype='FLOAT'`` file, the file will then contain ``np.array([42.], dtype='float32')``. samplerate : int The sample rate of the audio data. subtype : str, optional See `default_subtype()` for the default value and `available_subtypes()` for all possible values. Other Parameters ---------------- format, endian, closefd See `SoundFile`. Examples -------- Write 10 frames of random data to a new file: >>> import numpy as np >>> import soundfile as sf >>> sf.write('stereo_file.wav', np.random.randn(10, 2), 44100, 'PCM_24') """ import numpy as np data = np.asarray(data) if data.ndim == 1: channels = 1 else: channels = data.shape[1] with SoundFile(file, 'w', samplerate, channels, subtype, endian, format, closefd) as f: f.write(data) def blocks(file, blocksize=None, overlap=0, frames=-1, start=0, stop=None, dtype='float64', always_2d=False, fill_value=None, out=None, samplerate=None, channels=None, format=None, subtype=None, endian=None, closefd=True): """Return a generator for block-wise reading. By default, iteration starts at the beginning and stops at the end of the file. Use *start* to start at a later position and *frames* or *stop* to stop earlier. If you stop iterating over the generator before it's exhausted, the sound file is not closed. This is normally not a problem because the file is opened in read-only mode. To close the file properly, the generator's ``close()`` method can be called. Parameters ---------- file : str or int or file-like object The file to read from. See `SoundFile` for details. blocksize : int The number of frames to read per block. Either this or *out* must be given. overlap : int, optional The number of frames to rewind between each block. Yields ------ `numpy.ndarray` or type(out) Blocks of audio data. If *out* was given, and the requested frames are not an integer multiple of the length of *out*, and no *fill_value* was given, the last block will be a smaller view into *out*. Other Parameters ---------------- frames, start, stop See `read()`. dtype : {'float64', 'float32', 'int32', 'int16'}, optional See `read()`. always_2d, fill_value, out See `read()`. samplerate, channels, format, subtype, endian, closefd See `SoundFile`. Examples -------- >>> import soundfile as sf >>> for block in sf.blocks('stereo_file.wav', blocksize=1024): >>> pass # do something with 'block' """ with SoundFile(file, 'r', samplerate, channels, subtype, endian, format, closefd) as f: frames = f._prepare_read(start, stop, frames) for block in f.blocks(blocksize, overlap, frames, dtype, always_2d, fill_value, out): yield block class _SoundFileInfo(object): """Information about a SoundFile""" def __init__(self, file, verbose): self.verbose = verbose with SoundFile(file) as f: self.name = f.name self.samplerate = f.samplerate self.channels = f.channels self.frames = f.frames self.duration = float(self.frames)/f.samplerate self.format = f.format self.subtype = f.subtype self.endian = f.endian self.format_info = f.format_info self.subtype_info = f.subtype_info self.sections = f.sections self.extra_info = f.extra_info @property def _duration_str(self): hours, rest = divmod(self.duration, 3600) minutes, seconds = divmod(rest, 60) if hours >= 1: duration = "{0:.0g}:{1:02.0g}:{2:05.3f} h".format(hours, minutes, seconds) elif minutes >= 1: duration = "{0:02.0g}:{1:05.3f} min".format(minutes, seconds) elif seconds <= 1: duration = "{0:d} samples".format(self.frames) else: duration = "{0:.3f} s".format(seconds) return duration def __repr__(self): info = "\n".join( ["{0.name}", "samplerate: {0.samplerate} Hz", "channels: {0.channels}", "duration: {0._duration_str}", "format: {0.format_info} [{0.format}]", "subtype: {0.subtype_info} [{0.subtype}]"]) if self.verbose: info += "\n".join( ["\nendian: {0.endian}", "sections: {0.sections}", "frames: {0.frames}", 'extra_info: """', ' {1}"""']) indented_extra_info = ("\n"+" "*4).join(self.extra_info.split("\n")) return info.format(self, indented_extra_info) def info(file, verbose=False): """Returns an object with information about a `SoundFile`. Parameters ---------- verbose : bool Whether to print additional information. """ return _SoundFileInfo(file, verbose) def available_formats(): """Return a dictionary of available major formats. Examples -------- >>> import soundfile as sf >>> sf.available_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)'} """ return dict(_available_formats_helper(_snd.SFC_GET_FORMAT_MAJOR_COUNT, _snd.SFC_GET_FORMAT_MAJOR)) def available_subtypes(format=None): """Return a dictionary of available subtypes. Parameters ---------- format : str If given, only compatible subtypes are returned. Examples -------- >>> import soundfile as sf >>> sf.available_subtypes('FLAC') {'PCM_24': 'Signed 24 bit PCM', 'PCM_16': 'Signed 16 bit PCM', 'PCM_S8': 'Signed 8 bit PCM'} """ subtypes = _available_formats_helper(_snd.SFC_GET_FORMAT_SUBTYPE_COUNT, _snd.SFC_GET_FORMAT_SUBTYPE) return dict((subtype, name) for subtype, name in subtypes if format is None or check_format(format, subtype)) def check_format(format, subtype=None, endian=None): """Check if the combination of format/subtype/endian is valid. Examples -------- >>> import soundfile as sf >>> sf.check_format('WAV', 'PCM_24') True >>> sf.check_format('FLAC', 'VORBIS') False """ try: return bool(_format_int(format, subtype, endian)) except (ValueError, TypeError): return False def default_subtype(format): """Return the default subtype for a given format. Examples -------- >>> import soundfile as sf >>> sf.default_subtype('WAV') 'PCM_16' >>> sf.default_subtype('MAT5') 'DOUBLE' """ _check_format(format) return _default_subtypes.get(format.upper()) class SoundFile(object): """A sound file. For more documentation see the __init__() docstring (which is also used for the online documentation (https://python-soundfile.readthedocs.io/). """ def __init__(self, file, mode='r', samplerate=None, channels=None, subtype=None, endian=None, format=None, closefd=True): """Open a sound file. If a file is opened with `mode` ``'r'`` (the default) or ``'r+'``, no sample rate, channels or file format need to be given because the information is obtained from the file. An exception is the ``'RAW'`` data format, which always requires these data points. File formats consist of three case-insensitive strings: * a *major format* which is by default obtained from the extension of the file name (if known) and which can be forced with the format argument (e.g. ``format='WAVEX'``). * a *subtype*, e.g. ``'PCM_24'``. Most major formats have a default subtype which is used if no subtype is specified. * an *endian-ness*, which doesn't have to be specified at all in most cases. A `SoundFile` object is a *context manager*, which means if used in a "with" statement, `close()` is automatically called when reaching the end of the code block inside the "with" statement. Parameters ---------- file : str or int or file-like object The file to open. This can be a file name, a file descriptor or a Python file object (or a similar object with the methods ``read()``/``readinto()``, ``write()``, ``seek()`` and ``tell()``). mode : {'r', 'r+', 'w', 'w+', 'x', 'x+'}, optional Open mode. Has to begin with one of these three characters: ``'r'`` for reading, ``'w'`` for writing (truncates *file*) or ``'x'`` for writing (raises an error if *file* already exists). Additionally, it may contain ``'+'`` to open *file* for both reading and writing. The character ``'b'`` for *binary mode* is implied because all sound files have to be opened in this mode. If *file* is a file descriptor or a file-like object, ``'w'`` doesn't truncate and ``'x'`` doesn't raise an error. samplerate : int The sample rate of the file. If `mode` contains ``'r'``, this is obtained from the file (except for ``'RAW'`` files). channels : int The number of channels of the file. If `mode` contains ``'r'``, this is obtained from the file (except for ``'RAW'`` files). subtype : str, sometimes optional The subtype of the sound file. If `mode` contains ``'r'``, this is obtained from the file (except for ``'RAW'`` files), if not, the default value depends on the selected `format` (see `default_subtype()`). See `available_subtypes()` for all possible subtypes for a given `format`. endian : {'FILE', 'LITTLE', 'BIG', 'CPU'}, sometimes optional The endian-ness of the sound file. If `mode` contains ``'r'``, this is obtained from the file (except for ``'RAW'`` files), if not, the default value is ``'FILE'``, which is correct in most cases. format : str, sometimes optional The major format of the sound file. If `mode` contains ``'r'``, this is obtained from the file (except for ``'RAW'`` files), if not, the default value is determined from the file extension. See `available_formats()` for all possible values. closefd : bool, optional Whether to close the file descriptor on `close()`. Only applicable if the *file* argument is a file descriptor. Examples -------- >>> from soundfile import SoundFile Open an existing file for reading: >>> myfile = SoundFile('existing_file.wav') >>> # do something with myfile >>> myfile.close() Create a new sound file for reading and writing using a with statement: >>> with SoundFile('new_file.wav', 'x+', 44100, 2) as myfile: >>> # do something with myfile >>> # ... >>> assert not myfile.closed >>> # myfile.close() is called automatically at the end >>> assert myfile.closed """ # resolve PathLike objects (see PEP519 for details): # can be replaced with _os.fspath(file) for Python >= 3.6 file = file.__fspath__() if hasattr(file, '__fspath__') else file self._name = file if mode is None: mode = getattr(file, 'mode', None) mode_int = _check_mode(mode) self._mode = mode self._info = _create_info_struct(file, mode, samplerate, channels, format, subtype, endian) self._file = self._open(file, mode_int, closefd) if set(mode).issuperset('r+') and self.seekable(): # Move write position to 0 (like in Python file objects) self.seek(0) _snd.sf_command(self._file, _snd.SFC_SET_CLIPPING, _ffi.NULL, _snd.SF_TRUE) name = property(lambda self: self._name) """The file name of the sound file.""" mode = property(lambda self: self._mode) """The open mode the sound file was opened with.""" samplerate = property(lambda self: self._info.samplerate) """The sample rate of the sound file.""" frames = property(lambda self: self._info.frames) """The number of frames in the sound file.""" channels = property(lambda self: self._info.channels) """The number of channels in the sound file.""" format = property( lambda self: _format_str(self._info.format & _snd.SF_FORMAT_TYPEMASK)) """The major format of the sound file.""" subtype = property( lambda self: _format_str(self._info.format & _snd.SF_FORMAT_SUBMASK)) """The subtype of data in the the sound file.""" endian = property( lambda self: _format_str(self._info.format & _snd.SF_FORMAT_ENDMASK)) """The endian-ness of the data in the sound file.""" format_info = property( lambda self: _format_info(self._info.format & _snd.SF_FORMAT_TYPEMASK)[1]) """A description of the major format of the sound file.""" subtype_info = property( lambda self: _format_info(self._info.format & _snd.SF_FORMAT_SUBMASK)[1]) """A description of the subtype of the sound file.""" sections = property(lambda self: self._info.sections) """The number of sections of the sound file.""" closed = property(lambda self: self._file is None) """Whether the sound file is closed or not.""" _errorcode = property(lambda self: _snd.sf_error(self._file)) """A pending sndfile error code.""" @property def extra_info(self): """Retrieve the log string generated when opening the file.""" info = _ffi.new("char[]", 2**14) _snd.sf_command(self._file, _snd.SFC_GET_LOG_INFO, info, _ffi.sizeof(info)) return _ffi.string(info).decode('utf-8', 'replace') # avoid confusion if something goes wrong before assigning self._file: _file = None def __repr__(self): return ("SoundFile({0.name!r}, mode={0.mode!r}, " "samplerate={0.samplerate}, channels={0.channels}, " "format={0.format!r}, subtype={0.subtype!r}, " "endian={0.endian!r})".format(self)) def __del__(self): self.close() def __enter__(self): return self def __exit__(self, *args): self.close() def __setattr__(self, name, value): """Write text meta-data in the sound file through properties.""" if name in _str_types: self._check_if_closed() err = _snd.sf_set_string(self._file, _str_types[name], value.encode()) _error_check(err) else: object.__setattr__(self, name, value) def __getattr__(self, name): """Read text meta-data in the sound file through properties.""" if name in _str_types: self._check_if_closed() data = _snd.sf_get_string(self._file, _str_types[name]) return _ffi.string(data).decode('utf-8', 'replace') if data else "" else: raise AttributeError( "'SoundFile' object has no attribute {0!r}".format(name)) def __len__(self): # Note: This is deprecated and will be removed at some point, # see https://github.com/bastibe/python-soundfile/issues/199 return self._info.frames def __bool__(self): # Note: This is temporary until __len__ is removed, afterwards it # can (and should) be removed without change of behavior return True def __nonzero__(self): # Note: This is only for compatibility with Python 2 and it shall be # removed at the same time as __bool__(). return self.__bool__() def seekable(self): """Return True if the file supports seeking.""" return self._info.seekable == _snd.SF_TRUE def seek(self, frames, whence=SEEK_SET): """Set the read/write position. Parameters ---------- frames : int The frame index or offset to seek. whence : {SEEK_SET, SEEK_CUR, SEEK_END}, optional By default (``whence=SEEK_SET``), *frames* are counted from the beginning of the file. ``whence=SEEK_CUR`` seeks from the current position (positive and negative values are allowed for *frames*). ``whence=SEEK_END`` seeks from the end (use negative value for *frames*). Returns ------- int The new absolute read/write position in frames. Examples -------- >>> from soundfile import SoundFile, SEEK_END >>> myfile = SoundFile('stereo_file.wav') Seek to the beginning of the file: >>> myfile.seek(0) 0 Seek to the end of the file: >>> myfile.seek(0, SEEK_END) 44100 # this is the file length """ self._check_if_closed() position = _snd.sf_seek(self._file, frames, whence) _error_check(self._errorcode) return position def tell(self): """Return the current read/write position.""" return self.seek(0, SEEK_CUR) def read(self, frames=-1, dtype='float64', always_2d=False, fill_value=None, out=None): """Read from the file and return data as NumPy array. Reads the given number of frames in the given data format starting at the current read/write position. This advances the read/write position by the same number of frames. By default, all frames from the current read/write position to the end of the file are returned. Use `seek()` to move the current read/write position. Parameters ---------- frames : int, optional The number of frames to read. If ``frames < 0``, the whole rest of the file is read. dtype : {'float64', 'float32', 'int32', 'int16'}, optional Data type of the returned array, by default ``'float64'``. Floating point audio data is typically in the range from ``-1.0`` to ``1.0``. 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'``. .. note:: 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'``. Returns ------- audiodata : `numpy.ndarray` or type(out) A two-dimensional NumPy (frames x channels) array is returned. If the sound file has only one channel, a one-dimensional array is returned. Use ``always_2d=True`` to return a two-dimensional array anyway. If *out* was specified, it is returned. If *out* has more frames than available in the file (or if *frames* is smaller than the length of *out*) and no *fill_value* is given, then only a part of *out* is overwritten and a view containing all valid frames is returned. Other Parameters ---------------- always_2d : bool, optional By default, reading a mono sound file will return a one-dimensional array. With ``always_2d=True``, audio data is always returned as a two-dimensional array, even if the audio file has only one channel. fill_value : float, optional If more frames are requested than available in the file, the rest of the output is be filled with *fill_value*. If *fill_value* is not specified, a smaller array is returned. out : `numpy.ndarray` or subclass, optional If *out* is specified, the data is written into the given array instead of creating a new array. In this case, the arguments *dtype* and *always_2d* are silently ignored! If *frames* is not given, it is obtained from the length of *out*. Examples -------- >>> from soundfile import SoundFile >>> myfile = SoundFile('stereo_file.wav') Reading 3 frames from a stereo file: >>> myfile.read(3) array([[ 0.71329652, 0.06294799], [-0.26450912, -0.38874483], [ 0.67398441, -0.11516333]]) >>> myfile.close() See Also -------- buffer_read, .write """ if out is None: frames = self._check_frames(frames, fill_value) out = self._create_empty_array(frames, always_2d, dtype) else: if frames < 0 or frames > len(out): frames = len(out) frames = self._array_io('read', out, frames) if len(out) > frames: if fill_value is None: out = out[:frames] else: out[frames:] = fill_value return out def buffer_read(self, frames=-1, dtype=None): """Read from the file and return data as buffer object. Reads the given number of *frames* in the given data format starting at the current read/write position. This advances the read/write position by the same number of frames. By default, all frames from the current read/write position to the end of the file are returned. Use `seek()` to move the current read/write position. Parameters ---------- frames : int, optional The number of frames to read. If ``frames < 0``, the whole rest of the file is read. dtype : {'float64', 'float32', 'int32', 'int16'} Audio data will be converted to the given data type. Returns ------- buffer A buffer containing the read data. See Also -------- buffer_read_into, .read, buffer_write """ frames = self._check_frames(frames, fill_value=None) ctype = self._check_dtype(dtype) cdata = _ffi.new(ctype + '[]', frames * self.channels) read_frames = self._cdata_io('read', cdata, ctype, frames) assert read_frames == frames return _ffi.buffer(cdata) def buffer_read_into(self, buffer, dtype): """Read from the file into a given buffer object. Fills the given *buffer* with frames in the given data format starting at the current read/write position (which can be changed with `seek()`) until the buffer is full or the end of the file is reached. This advances the read/write position by the number of frames that were read. Parameters ---------- buffer : writable buffer Audio frames from the file are written to this buffer. dtype : {'float64', 'float32', 'int32', 'int16'} The data type of *buffer*. Returns ------- int The number of frames that were read from the file. This can be less than the size of *buffer*. The rest of the buffer is not filled with meaningful data. See Also -------- buffer_read, .read """ ctype = self._check_dtype(dtype) cdata, frames = self._check_buffer(buffer, ctype) frames = self._cdata_io('read', cdata, ctype, frames) return frames def write(self, data): """Write audio data from a NumPy array to the file. Writes a number of frames at the read/write position to the file. This also advances the read/write position by the same number of frames and enlarges the file if necessary. Note that writing int values to a float file will *not* scale the values to [-1.0, 1.0). If you write the value ``np.array([42], dtype='int32')``, to a ``subtype='FLOAT'`` file, the file will then contain ``np.array([42.], dtype='float32')``. Parameters ---------- data : array_like The data to write. Usually two-dimensional (frames x channels), but one-dimensional *data* can be used for mono files. Only the data types ``'float64'``, ``'float32'``, ``'int32'`` and ``'int16'`` are supported. .. note:: The data type of *data* does **not** select the data type of the written file. Audio data will be converted to the given *subtype*. Writing int values to a float file will *not* scale the values to [-1.0, 1.0). If you write the value ``np.array([42], dtype='int32')``, to a ``subtype='FLOAT'`` file, the file will then contain ``np.array([42.], dtype='float32')``. Examples -------- >>> import numpy as np >>> from soundfile import SoundFile >>> myfile = SoundFile('stereo_file.wav') Write 10 frames of random data to a new file: >>> with SoundFile('stereo_file.wav', 'w', 44100, 2, 'PCM_24') as f: >>> f.write(np.random.randn(10, 2)) See Also -------- buffer_write, .read """ import numpy as np # no copy is made if data has already the correct memory layout: data = np.ascontiguousarray(data) written = self._array_io('write', data, len(data)) assert written == len(data) self._update_frames(written) def buffer_write(self, data, dtype): """Write audio data from a buffer/bytes object to the file. Writes the contents of *data* to the file at the current read/write position. This also advances the read/write position by the number of frames that were written and enlarges the file if necessary. Parameters ---------- data : buffer or bytes A buffer or bytes object containing the audio data to be written. dtype : {'float64', 'float32', 'int32', 'int16'} The data type of the audio data stored in *data*. See Also -------- .write, buffer_read """ ctype = self._check_dtype(dtype) cdata, frames = self._check_buffer(data, ctype) written = self._cdata_io('write', cdata, ctype, frames) assert written == frames self._update_frames(written) def blocks(self, blocksize=None, overlap=0, frames=-1, dtype='float64', always_2d=False, fill_value=None, out=None): """Return a generator for block-wise reading. By default, the generator yields blocks of the given *blocksize* (using a given *overlap*) until the end of the file is reached; *frames* can be used to stop earlier. Parameters ---------- blocksize : int The number of frames to read per block. Either this or *out* must be given. overlap : int, optional The number of frames to rewind between each block. frames : int, optional The number of frames to read. If ``frames < 0``, the file is read until the end. dtype : {'float64', 'float32', 'int32', 'int16'}, optional See `read()`. Yields ------ `numpy.ndarray` or type(out) Blocks of audio data. If *out* was given, and the requested frames are not an integer multiple of the length of *out*, and no *fill_value* was given, the last block will be a smaller view into *out*. Other Parameters ---------------- always_2d, fill_value, out See `read()`. fill_value : float, optional See `read()`. out : `numpy.ndarray` or subclass, optional If *out* is specified, the data is written into the given array instead of creating a new array. In this case, the arguments *dtype* and *always_2d* are silently ignored! Examples -------- >>> from soundfile import SoundFile >>> with SoundFile('stereo_file.wav') as f: >>> for block in f.blocks(blocksize=1024): >>> pass # do something with 'block' """ import numpy as np if 'r' not in self.mode and '+' not in self.mode: raise SoundFileRuntimeError("blocks() is not allowed in write-only mode") if out is None: if blocksize is None: raise TypeError("One of {blocksize, out} must be specified") out = self._create_empty_array(blocksize, always_2d, dtype) copy_out = True else: if blocksize is not None: raise TypeError( "Only one of {blocksize, out} may be specified") blocksize = len(out) copy_out = False overlap_memory = None frames = self._check_frames(frames, fill_value) while frames > 0: if overlap_memory is None: output_offset = 0 else: output_offset = len(overlap_memory) out[:output_offset] = overlap_memory toread = min(blocksize - output_offset, frames) self.read(toread, dtype, always_2d, fill_value, out[output_offset:]) if overlap: if overlap_memory is None: overlap_memory = np.copy(out[-overlap:]) else: overlap_memory[:] = out[-overlap:] if blocksize > frames + overlap and fill_value is None: block = out[:frames + overlap] else: block = out yield np.copy(block) if copy_out else block frames -= toread def truncate(self, frames=None): """Truncate the file to a given number of frames. After this command, the read/write position will be at the new end of the file. Parameters ---------- frames : int, optional Only the data before *frames* is kept, the rest is deleted. If not specified, the current read/write position is used. """ if frames is None: frames = self.tell() err = _snd.sf_command(self._file, _snd.SFC_FILE_TRUNCATE, _ffi.new("sf_count_t*", frames), _ffi.sizeof("sf_count_t")) if err: # get the actual error code err = _snd.sf_error(self._file) raise LibsndfileError(err, "Error truncating the file") self._info.frames = frames def flush(self): """Write unwritten data to the file system. Data written with `write()` is not immediately written to the file system but buffered in memory to be written at a later time. Calling `flush()` makes sure that all changes are actually written to the file system. This has no effect on files opened in read-only mode. """ self._check_if_closed() _snd.sf_write_sync(self._file) def close(self): """Close the file. Can be called multiple times.""" if not self.closed: # be sure to flush data to disk before closing the file self.flush() err = _snd.sf_close(self._file) self._file = None _error_check(err) def _open(self, file, mode_int, closefd): """Call the appropriate sf_open*() function from libsndfile.""" if isinstance(file, (_unicode, bytes)): if _os.path.isfile(file): if 'x' in self.mode: raise OSError("File exists: {0!r}".format(self.name)) elif set(self.mode).issuperset('w+'): # truncate the file, because SFM_RDWR doesn't: _os.close(_os.open(file, _os.O_WRONLY | _os.O_TRUNC)) openfunction = _snd.sf_open if isinstance(file, _unicode): if _sys.platform == 'win32': openfunction = _snd.sf_wchar_open else: file = file.encode(_sys.getfilesystemencoding()) file_ptr = openfunction(file, mode_int, self._info) elif isinstance(file, int): file_ptr = _snd.sf_open_fd(file, mode_int, self._info, closefd) elif _has_virtual_io_attrs(file, mode_int): file_ptr = _snd.sf_open_virtual(self._init_virtual_io(file), mode_int, self._info, _ffi.NULL) else: raise TypeError("Invalid file: {0!r}".format(self.name)) if file_ptr == _ffi.NULL: # get the actual error code err = _snd.sf_error(file_ptr) raise LibsndfileError(err, prefix="Error opening {0!r}: ".format(self.name)) if mode_int == _snd.SFM_WRITE: # Due to a bug in libsndfile version <= 1.0.25, frames != 0 # when opening a named pipe in SFM_WRITE mode. # See http://github.com/erikd/libsndfile/issues/77. self._info.frames = 0 # This is not necessary for "normal" files (because # frames == 0 in this case), but it doesn't hurt, either. return file_ptr def _init_virtual_io(self, file): """Initialize callback functions for sf_open_virtual().""" @_ffi.callback("sf_vio_get_filelen") def vio_get_filelen(user_data): curr = file.tell() file.seek(0, SEEK_END) size = file.tell() file.seek(curr, SEEK_SET) return size @_ffi.callback("sf_vio_seek") def vio_seek(offset, whence, user_data): file.seek(offset, whence) return file.tell() @_ffi.callback("sf_vio_read") def vio_read(ptr, count, user_data): # first try readinto(), if not available fall back to read() try: buf = _ffi.buffer(ptr, count) data_read = file.readinto(buf) except AttributeError: data = file.read(count) data_read = len(data) buf = _ffi.buffer(ptr, data_read) buf[0:data_read] = data return data_read @_ffi.callback("sf_vio_write") def vio_write(ptr, count, user_data): buf = _ffi.buffer(ptr, count) data = buf[:] written = file.write(data) # write() returns None for file objects in Python <= 2.7: if written is None: written = count return written @_ffi.callback("sf_vio_tell") def vio_tell(user_data): return file.tell() # Note: the callback functions must be kept alive! self._virtual_io = {'get_filelen': vio_get_filelen, 'seek': vio_seek, 'read': vio_read, 'write': vio_write, 'tell': vio_tell} return _ffi.new("SF_VIRTUAL_IO*", self._virtual_io) def _getAttributeNames(self): """Return all attributes used in __setattr__ and __getattr__. This is useful for auto-completion (e.g. IPython). """ return _str_types def _check_if_closed(self): """Check if the file is closed and raise an error if it is. This should be used in every method that uses self._file. """ if self.closed: raise SoundFileRuntimeError("I/O operation on closed file") def _check_frames(self, frames, fill_value): """Reduce frames to no more than are available in the file.""" if self.seekable(): remaining_frames = self.frames - self.tell() if frames < 0 or (frames > remaining_frames and fill_value is None): frames = remaining_frames elif frames < 0: raise ValueError("frames must be specified for non-seekable files") return frames def _check_buffer(self, data, ctype): """Convert buffer to cdata and check for valid size.""" assert ctype in _ffi_types.values() if not isinstance(data, bytes): data = _ffi.from_buffer(data) frames, remainder = divmod(len(data), self.channels * _ffi.sizeof(ctype)) if remainder: raise ValueError("Data size must be a multiple of frame size") return data, frames def _create_empty_array(self, frames, always_2d, dtype): """Create an empty array with appropriate shape.""" import numpy as np if always_2d or self.channels > 1: shape = frames, self.channels else: shape = frames, return np.empty(shape, dtype, order='C') def _check_dtype(self, dtype): """Check if dtype string is valid and return ctype string.""" try: return _ffi_types[dtype] except KeyError: raise ValueError("dtype must be one of {0!r} and not {1!r}".format( sorted(_ffi_types.keys()), dtype)) def _array_io(self, action, array, frames): """Check array and call low-level IO function.""" if (array.ndim not in (1, 2) or array.ndim == 1 and self.channels != 1 or array.ndim == 2 and array.shape[1] != self.channels): raise ValueError("Invalid shape: {0!r}".format(array.shape)) if not array.flags.c_contiguous: raise ValueError("Data must be C-contiguous") ctype = self._check_dtype(array.dtype.name) assert array.dtype.itemsize == _ffi.sizeof(ctype) cdata = _ffi.cast(ctype + '*', array.__array_interface__['data'][0]) return self._cdata_io(action, cdata, ctype, frames) def _cdata_io(self, action, data, ctype, frames): """Call one of libsndfile's read/write functions.""" assert ctype in _ffi_types.values() self._check_if_closed() if self.seekable(): curr = self.tell() func = getattr(_snd, 'sf_' + action + 'f_' + ctype) frames = func(self._file, data, frames) _error_check(self._errorcode) if self.seekable(): self.seek(curr + frames, SEEK_SET) # Update read & write position return frames def _update_frames(self, written): """Update self.frames after writing.""" if self.seekable(): curr = self.tell() self._info.frames = self.seek(0, SEEK_END) self.seek(curr, SEEK_SET) else: self._info.frames += written def _prepare_read(self, start, stop, frames): """Seek to start frame and calculate length.""" if start != 0 and not self.seekable(): raise ValueError("start is only allowed for seekable files") if frames >= 0 and stop is not None: raise TypeError("Only one of {frames, stop} may be used") start, stop, _ = slice(start, stop).indices(self.frames) if stop < start: stop = start if frames < 0: frames = stop - start if self.seekable(): self.seek(start, SEEK_SET) return frames def copy_metadata(self): """Get all metadata present in this SoundFile Returns ------- metadata: dict[str, str] A dict with all metadata. Possible keys are: 'title', 'copyright', 'software', 'artist', 'comment', 'date', 'album', 'license', 'tracknumber' and 'genre'. """ strs = {} for strtype, strid in _str_types.items(): data = _snd.sf_get_string(self._file, strid) if data: strs[strtype] = _ffi.string(data).decode('utf-8', 'replace') return strs def _error_check(err, prefix=""): """Raise LibsndfileError if there is an error.""" if err != 0: raise LibsndfileError(err, prefix=prefix) def _format_int(format, subtype, endian): """Return numeric ID for given format|subtype|endian combo.""" result = _check_format(format) if subtype is None: subtype = default_subtype(format) if subtype is None: raise TypeError( "No default subtype for major format {0!r}".format(format)) elif not isinstance(subtype, (_unicode, str)): raise TypeError("Invalid subtype: {0!r}".format(subtype)) try: result |= _subtypes[subtype.upper()] except KeyError: raise ValueError("Unknown subtype: {0!r}".format(subtype)) if endian is None: endian = 'FILE' elif not isinstance(endian, (_unicode, str)): raise TypeError("Invalid endian-ness: {0!r}".format(endian)) try: result |= _endians[endian.upper()] except KeyError: raise ValueError("Unknown endian-ness: {0!r}".format(endian)) info = _ffi.new("SF_INFO*") info.format = result info.channels = 1 if _snd.sf_format_check(info) == _snd.SF_FALSE: raise ValueError( "Invalid combination of format, subtype and endian") return result def _check_mode(mode): """Check if mode is valid and return its integer representation.""" if not isinstance(mode, (_unicode, str)): raise TypeError("Invalid mode: {0!r}".format(mode)) mode_set = set(mode) if mode_set.difference('xrwb+') or len(mode) > len(mode_set): raise ValueError("Invalid mode: {0!r}".format(mode)) if len(mode_set.intersection('xrw')) != 1: raise ValueError("mode must contain exactly one of 'xrw'") if '+' in mode_set: mode_int = _snd.SFM_RDWR elif 'r' in mode_set: mode_int = _snd.SFM_READ else: mode_int = _snd.SFM_WRITE return mode_int def _create_info_struct(file, mode, samplerate, channels, format, subtype, endian): """Check arguments and create SF_INFO struct.""" original_format = format if format is None: format = _get_format_from_filename(file, mode) assert isinstance(format, (_unicode, str)) else: _check_format(format) info = _ffi.new("SF_INFO*") if 'r' not in mode or format.upper() == 'RAW': if samplerate is None: raise TypeError("samplerate must be specified") info.samplerate = samplerate if channels is None: raise TypeError("channels must be specified") info.channels = channels info.format = _format_int(format, subtype, endian) else: if any(arg is not None for arg in ( samplerate, channels, original_format, subtype, endian)): raise TypeError("Not allowed for existing files (except 'RAW'): " "samplerate, channels, format, subtype, endian") return info def _get_format_from_filename(file, mode): """Return a format string obtained from file (or file.name). If file already exists (= read mode), an empty string is returned on error. If not, an exception is raised. The return type will always be str or unicode (even if file/file.name is a bytes object). """ format = '' file = getattr(file, 'name', file) try: # This raises an exception if file is not a (Unicode/byte) string: format = _os.path.splitext(file)[-1][1:] # Convert bytes to unicode (raises AttributeError on Python 3 str): format = format.decode('utf-8', 'replace') except Exception: pass if format.upper() not in _formats and 'r' not in mode: raise TypeError("No format specified and unable to get format from " "file extension: {0!r}".format(file)) return format def _format_str(format_int): """Return the string representation of a given numeric format.""" for dictionary in _formats, _subtypes, _endians: for k, v in dictionary.items(): if v == format_int: return k else: return 'n/a' def _format_info(format_int, format_flag=_snd.SFC_GET_FORMAT_INFO): """Return the ID and short description of a given format.""" format_info = _ffi.new("SF_FORMAT_INFO*") format_info.format = format_int _snd.sf_command(_ffi.NULL, format_flag, format_info, _ffi.sizeof("SF_FORMAT_INFO")) name = format_info.name return (_format_str(format_info.format), _ffi.string(name).decode('utf-8', 'replace') if name else "") def _available_formats_helper(count_flag, format_flag): """Helper for available_formats() and available_subtypes().""" count = _ffi.new("int*") _snd.sf_command(_ffi.NULL, count_flag, count, _ffi.sizeof("int")) for format_int in range(count[0]): yield _format_info(format_int, format_flag) def _check_format(format_str): """Check if `format_str` is valid and return format ID.""" if not isinstance(format_str, (_unicode, str)): raise TypeError("Invalid format: {0!r}".format(format_str)) try: format_int = _formats[format_str.upper()] except KeyError: raise ValueError("Unknown format: {0!r}".format(format_str)) return format_int def _has_virtual_io_attrs(file, mode_int): """Check if file has all the necessary attributes for virtual IO.""" readonly = mode_int == _snd.SFM_READ writeonly = mode_int == _snd.SFM_WRITE return all([ hasattr(file, 'seek'), hasattr(file, 'tell'), hasattr(file, 'write') or readonly, hasattr(file, 'read') or hasattr(file, 'readinto') or writeonly, ]) class SoundFileError(Exception): """Base class for all soundfile-specific errors.""" pass class SoundFileRuntimeError(SoundFileError, RuntimeError): """soundfile module runtime error. Errors that used to be `RuntimeError`.""" pass class LibsndfileError(SoundFileRuntimeError): """libsndfile errors. Attributes ---------- code libsndfile internal error number. """ def __init__(self, code, prefix=""): SoundFileRuntimeError.__init__(self, code, prefix) self.code = code self.prefix = prefix @property def error_string(self): """Raw libsndfile error message.""" if self.code: err_str = _snd.sf_error_number(self.code) return _ffi.string(err_str).decode('utf-8', 'replace') else: # Due to race conditions, if used concurrently, sf_error() may # return 0 (= no error) even if an error has happened. # See https://github.com/erikd/libsndfile/issues/610 for details. return "(Garbled error message from libsndfile)" def __str__(self): return self.prefix + self.error_string