"""PySoundFile is an audio library based on libsndfile, CFFI and NumPy.
Sound files can be read or written directly using the functions
:func:`read` and :func:`write`.
To read a sound file in a block-wise fashion, use :func:`blocks`.
Alternatively, sound files can be opened as :class:`SoundFile` objects.
For further information, see http://pysoundfile.readthedocs.org/.
"""
__version__ = "0.9.0"
import os as _os
import sys as _sys
from cffi import FFI as _FFI
from os import SEEK_SET, SEEK_CUR, SEEK_END
try:
_unicode = unicode # doesn't exist in Python 3.x
except NameError:
_unicode = str
_ffi = _FFI()
_ffi.cdef("""
enum
{
SF_FORMAT_SUBMASK = 0x0000FFFF,
SF_FORMAT_TYPEMASK = 0x0FFF0000,
SF_FORMAT_ENDMASK = 0x30000000
} ;
enum
{
SFC_GET_LIB_VERSION = 0x1000,
SFC_GET_LOG_INFO = 0x1001,
SFC_GET_FORMAT_INFO = 0x1028,
SFC_GET_FORMAT_MAJOR_COUNT = 0x1030,
SFC_GET_FORMAT_MAJOR = 0x1031,
SFC_GET_FORMAT_SUBTYPE_COUNT = 0x1032,
SFC_GET_FORMAT_SUBTYPE = 0x1033,
SFC_FILE_TRUNCATE = 0x1080,
SFC_SET_CLIPPING = 0x10C0,
SFC_SET_SCALE_FLOAT_INT_READ = 0x1014,
SFC_SET_SCALE_INT_FLOAT_WRITE = 0x1015,
} ;
enum
{
SF_FALSE = 0,
SF_TRUE = 1,
/* Modes for opening files. */
SFM_READ = 0x10,
SFM_WRITE = 0x20,
SFM_RDWR = 0x30,
} ;
typedef int64_t sf_count_t ;
typedef struct SNDFILE_tag SNDFILE ;
typedef struct SF_INFO
{
sf_count_t frames ; /* Used to be called samples. Changed to avoid confusion. */
int samplerate ;
int channels ;
int format ;
int sections ;
int seekable ;
} SF_INFO ;
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ;
int sf_format_check (const SF_INFO *info) ;
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ;
int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
int sf_error (SNDFILE *sndfile) ;
const char* sf_strerror (SNDFILE *sndfile) ;
const char* sf_error_number (int errnum) ;
int sf_perror (SNDFILE *sndfile) ;
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ;
int sf_close (SNDFILE *sndfile) ;
void sf_write_sync (SNDFILE *sndfile) ;
sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
/* Note: Data ptr argument types are declared as void* here in order to
avoid an implicit cast warning. (gh183). */
sf_count_t sf_readf_short (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_readf_int (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_readf_float (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_readf_double (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
/* Note: The argument types were changed to void* in order to allow
writing bytes in SoundFile.buffer_write() */
sf_count_t sf_writef_short (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_writef_int (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_writef_float (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_writef_double (SNDFILE *sndfile, void *ptr, sf_count_t frames) ;
sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
const char* sf_get_string (SNDFILE *sndfile, int str_type) ;
int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ;
const char * sf_version_string (void) ;
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ;
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ;
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ;
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ;
typedef sf_count_t (*sf_vio_tell) (void *user_data) ;
typedef struct SF_VIRTUAL_IO
{ sf_count_t (*get_filelen) (void *user_data) ;
sf_count_t (*seek) (sf_count_t offset, int whence, void *user_data) ;
sf_count_t (*read) (void *ptr, sf_count_t count, void *user_data) ;
sf_count_t (*write) (const void *ptr, sf_count_t count, void *user_data) ;
sf_count_t (*tell) (void *user_data) ;
} SF_VIRTUAL_IO ;
SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ;
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ;
typedef struct SF_FORMAT_INFO
{
int format ;
const char* name ;
const char* extension ;
} SF_FORMAT_INFO ;
""")
if _sys.platform == 'win32':
_ffi.cdef("""
SNDFILE* sf_wchar_open (LPCWSTR wpath, int mode, SF_INFO *sfinfo) ;
""")
_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
}
_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
'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.
'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).
}
_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',
}
_ffi_types = {
'float64': 'double',
'float32': 'float',
'int32': 'int',
'int16': 'short'
}
try:
_snd = _ffi.dlopen('sndfile')
except OSError:
if _sys.platform == 'darwin':
_libname = 'libsndfile.dylib'
elif _sys.platform == 'win32':
from platform import architecture as _architecture
_libname = 'libsndfile' + _architecture()[0] + '.dll'
else:
raise
_snd = _ffi.dlopen(_os.path.join(
_os.path.dirname(_os.path.abspath(__file__)),
'_soundfile_data', _libname))
__libsndfile_version__ = _ffi.string(_snd.sf_version_string()).decode('utf-8', 'replace')
if __libsndfile_version__.startswith('libsndfile-'):
__libsndfile_version__ = __libsndfile_version__[len('libsndfile-'):]
[docs]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 :class:`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 NumPy array is returned, where the channels
are stored along the first dimension, i.e. as columns.
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 :class:`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
[docs]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 :class:`SoundFile` for details.
data : array_like
The data to write. Usually two-dimensional (channels x frames),
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 :func:`default_subtype` for the default value and
:func:`available_subtypes` for all possible values.
Other Parameters
----------------
format, endian, closefd
See :class:`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)
[docs]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 :class:`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 :func:`read`.
dtype : {'float64', 'float32', 'int32', 'int16'}, optional
See :func:`read`.
always_2d, fill_value, out
See :func:`read`.
samplerate, channels, format, subtype, endian, closefd
See :class:`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 = len(f)
self.duration = 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)
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)
[docs]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)
[docs]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))
[docs]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())
[docs]class SoundFile(object):
"""A sound file.
For more documentation see the __init__() docstring (which is also
used for the online documentation (http://pysoundfile.readthedocs.org/).
"""
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 :class:`SoundFile` object is a *context manager*, which means
if used in a "with" statement, :meth:`.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 :func:`default_subtype`).
See :func:`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 :func:`available_formats` for
all possible values.
closefd : bool, optional
Whether to close the file descriptor on :meth:`.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
"""
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."""
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):
return self._info.frames
[docs] def seekable(self):
"""Return True if the file supports seeking."""
return self._info.seekable == _snd.SF_TRUE
[docs] 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
[docs] def tell(self):
"""Return the current read/write position."""
return self.seek(0, SEEK_CUR)
[docs] 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 :meth:`.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 array is returned, where the
channels are stored along the first dimension, i.e. as
columns. 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. numpy.ndarray or
type(out)
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
[docs] def buffer_read(self, frames=-1, ctype=None, 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 :meth:`.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)
dtype = self._ctype_is_deprecated(ctype, dtype)
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)
[docs] def buffer_read_into(self, buffer, ctype=None, dtype=None):
"""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 :meth:`.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
"""
dtype = self._ctype_is_deprecated(ctype, dtype)
ctype = self._check_dtype(dtype)
cdata, frames = self._check_buffer(buffer, ctype)
frames = self._cdata_io('read', cdata, ctype, frames)
return frames
[docs] 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 (channels x
frames), 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_len(written)
[docs] def buffer_write(self, data, ctype=None, dtype=None):
"""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
"""
dtype = self._ctype_is_deprecated(ctype, dtype)
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_len(written)
[docs] 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 < 1``, the file is read until the end.
dtype : {'float64', 'float32', 'int32', 'int16'}, optional
See :meth:`.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 :meth:`.read`.
Examples
--------
>>> from soundfile import SoundFile
>>> with SoundFile('stereo_file.wav') as f:
>>> for block in f.blocks(blocksize=1024):
>>> pass # do something with 'block'
"""
if 'r' not in self.mode and '+' not in self.mode:
raise RuntimeError("blocks() is not allowed in write-only mode")
if overlap != 0 and not self.seekable():
raise ValueError("overlap is only allowed for seekable files")
if out is None:
if blocksize is None:
raise TypeError("One of {blocksize, out} must be specified")
else:
if blocksize is not None:
raise TypeError(
"Only one of {blocksize, out} may be specified")
blocksize = len(out)
frames = self._check_frames(frames, fill_value)
while frames > 0:
if frames < blocksize:
if fill_value is not None and out is None:
out = self._create_empty_array(blocksize, always_2d, dtype)
blocksize = frames
block = self.read(blocksize, dtype, always_2d, fill_value, out)
frames -= blocksize
if frames > 0 and self.seekable():
self.seek(-overlap, SEEK_CUR)
frames += overlap
yield block
[docs] 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:
raise RuntimeError("Error truncating the file")
self._info.frames = frames
[docs] def flush(self):
"""Write unwritten data to the file system.
Data written with :meth:`.write` is not immediately written to
the file system but buffered in memory to be written at a later
time. Calling :meth:`.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)
[docs] 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))
_error_check(_snd.sf_error(file_ptr),
"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 RuntimeError("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 = len(self) - 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}".format(
sorted(_ffi_types.keys())))
def _ctype_is_deprecated(self, ctype, dtype):
"""Show warning if ctype is used instead of dtype.
At some point, ctype arguments shall be removed and the
corresponding dtype arguments shall lose their default value.
"""
if ctype is not None:
from warnings import warn
warn('ctype is deprecated; use dtype instead', Warning)
if dtype is not None:
raise TypeError('Use dtype instead of ctype')
for k, v in _ffi_types.items():
if v == ctype:
return k
return 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_len(self, written):
"""Update len(self) 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(len(self))
if stop < start:
stop = start
if frames < 0:
frames = stop - start
if self.seekable():
self.seek(start, SEEK_SET)
return frames
def _error_check(err, prefix=""):
"""Pretty-print a numerical error code if there is an error."""
if err != 0:
err_str = _snd.sf_error_number(err)
raise RuntimeError(prefix + _ffi.string(err_str).decode('utf-8', 'replace'))
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,
])