1602 lines
59 KiB
Python
1602 lines
59 KiB
Python
|
"""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
|