README.rst
1audioread
2=========
3
4.. image:: https://secure.travis-ci.org/beetbox/audioread.png
5 :target: https://travis-ci.org/beetbox/audioread/
6
7Decode audio files using whichever backend is available. The library
8currently supports:
9
10- `Gstreamer`_ via `PyGObject`_.
11- `Core Audio`_ on Mac OS X via `ctypes`_. (PyObjC not required.)
12- `MAD`_ via the `pymad`_ bindings.
13- `FFmpeg`_ or `Libav`_ via its command-line interface.
14- The standard library `wave`_, `aifc`_, and `sunau`_ modules (for
15 uncompressed audio formats).
16
17.. _Gstreamer: http://gstreamer.freedesktop.org/
18.. _gst-python: http://gstreamer.freedesktop.org/modules/gst-python.html
19.. _Core Audio: http://developer.apple.com/technologies/mac/audio-and-video.html
20.. _ctypes: http://docs.python.org/library/ctypes.html
21.. _MAD: http://www.underbit.com/products/mad/
22.. _pymad: http://spacepants.org/src/pymad/
23.. _FFmpeg: http://ffmpeg.org/
24.. _Libav: https://www.libav.org/
25.. _wave: http://docs.python.org/library/wave.html
26.. _aifc: http://docs.python.org/library/aifc.html
27.. _sunau: http://docs.python.org/library/sunau.html
28.. _PyGObject: https://pygobject.readthedocs.io/
29
30Use the library like so::
31
32 with audioread.audio_open(filename) as f:
33 print(f.channels, f.samplerate, f.duration)
34 for buf in f:
35 do_something(buf)
36
37Buffers in the file can be accessed by iterating over the object returned from
38``audio_open``. Each buffer is a bytes-like object (``buffer``, ``bytes``, or
39``bytearray``) containing raw **16-bit little-endian signed integer PCM
40data**. (Currently, these PCM format parameters are not configurable, but this
41could be added to most of the backends.)
42
43Additional values are available as fields on the audio file object:
44
45- ``channels`` is the number of audio channels (an integer).
46- ``samplerate`` is given in Hz (an integer).
47- ``duration`` is the length of the audio in seconds (a float).
48
49The ``audio_open`` function transparently selects a backend that can read the
50file. (Each backend is implemented in a module inside the ``audioread``
51package.) If no backends succeed in opening the file, a ``DecodeError``
52exception is raised. This exception is only used when the file type is
53unsupported by the backends; if the file doesn't exist, a standard ``IOError``
54will be raised.
55
56A second optional parameter to ``audio_open`` specifies which backends to try
57(instead of trying them all, which is the default). You can use the
58``available_backends`` function to get a list backends that are usable on the
59current system.
60
61Audioread is "universal" and supports both Python 2 (2.6+) and Python 3
62(3.2+).
63
64Example
65-------
66
67The included ``decode.py`` script demonstrates using this package to
68convert compressed audio files to WAV files.
69
70Version History
71---------------
72
732.1.9
74 Work correctly with GStreamer 1.18 and later (thanks to @ssssam)
75
762.1.8
77 Fix an unhandled ``OSError`` when FFmpeg is not installed.
78
792.1.7
80 Properly close some filehandles in the FFmpeg backend (thanks to
81 @RyanMarcus and @ssssam).
82 The maddec backend now always produces bytes objects, like the other
83 backends (thanks to @ssssam).
84 Resolve an audio data memory leak in the GStreamer backend (thanks again to
85 @ssssam).
86 You can now optionally specify which specific backends ``audio_open`` should
87 try (thanks once again to @ssssam).
88 On Windows, avoid opening a console window to run FFmpeg (thanks to @flokX).
89
902.1.6
91 Fix a "no such process" crash in the FFmpeg backend on Windows Subsystem for
92 Linux (thanks to @llamasoft).
93 Avoid suppressing SIGINT in the GStreamer backend on older versions of
94 PyGObject (thanks to @lazka).
95
962.1.5
97 Properly clean up the file handle when a backend fails to decode a file.
98 Fix parsing of "N.M" channel counts in the FFmpeg backend (thanks to @piem).
99 Avoid a crash in the raw backend when a file uses an unsupported number of
100 bits per sample (namely, 24-bit samples in Python < 3.4).
101 Add a ``__version__`` value to the package.
102
1032.1.4
104 Fix a bug in the FFmpeg backend where, after closing a file, the program's
105 standard input stream would be "broken" and wouldn't receive any input.
106
1072.1.3
108 Avoid some warnings in the GStreamer backend when using modern versions of
109 GLib. We now require at least GLib 2.32.
110
1112.1.2
112 Fix a file descriptor leak when opening and closing many files using
113 GStreamer.
114
1152.1.1
116 Just fix ReST formatting in the README.
117
1182.1.0
119 The FFmpeg backend can now also use Libav's ``avconv`` command.
120 Fix a warning by requiring GStreamer >= 1.0.
121 Fix some Python 3 crashes with the new GStreamer backend (thanks to
122 @xix-xeaon).
123
1242.0.0
125 The GStreamer backend now uses GStreamer 1.x via the new
126 gobject-introspection API (and is compatible with Python 3).
127
1281.2.2
129 When running FFmpeg on Windows, disable its crash dialog. Thanks to
130 jcsaaddupuy.
131
1321.2.1
133 Fix an unhandled exception when opening non-raw audio files (thanks to
134 aostanin).
135 Fix Python 3 compatibility for the raw-file backend.
136
1371.2.0
138 Add support for FFmpeg on Windows (thanks to Jean-Christophe Saad-Dupuy).
139
1401.1.0
141 Add support for Sun/NeXT `Au files`_ via the standard-library ``sunau``
142 module (thanks to Dan Ellis).
143
1441.0.3
145 Use the rawread (standard-library) backend for .wav files.
146
1471.0.2
148 Send SIGKILL, not SIGTERM, to ffmpeg processes to avoid occasional hangs.
149
1501.0.1
151 When GStreamer fails to report a duration, raise an exception instead of
152 silently setting the duration field to None.
153
1541.0.0
155 Catch GStreamer's exception when necessary components, such as
156 ``uridecodebin``, are missing.
157 The GStreamer backend now accepts relative paths.
158 Fix a hang in GStreamer when the stream finishes before it begins (when
159 reading broken files).
160 Initial support for Python 3.
161
1620.8
163 All decoding errors are now subclasses of ``DecodeError``.
164
1650.7
166 Fix opening WAV and AIFF files via Unicode filenames.
167
1680.6
169 Make FFmpeg timeout more robust.
170 Dump FFmpeg output on timeout.
171 Fix a nondeterministic hang in the Gstreamer backend.
172 Fix a file descriptor leak in the MAD backend.
173
1740.5
175 Fix crash when FFmpeg fails to report a duration.
176 Fix a hang when FFmpeg fills up its stderr output buffer.
177 Add a timeout to ``ffmpeg`` tool execution (currently 10 seconds for each
178 4096-byte read); a ``ReadTimeoutError`` exception is raised if the tool times
179 out.
180
1810.4
182 Fix channel count detection for FFmpeg backend.
183
1840.3
185 Fix a problem with the Gstreamer backend where audio files could be left open
186 even after the ``GstAudioFile`` was "closed".
187
1880.2
189 Fix a hang in the GStreamer backend that occurs occasionally on some
190 platforms.
191
1920.1
193 Initial release.
194
195.. _Au files: http://en.wikipedia.org/wiki/Au_file_format
196
197Et Cetera
198---------
199
200``audioread`` is by Adrian Sampson. It is made available under `the MIT
201license`_. An alternative to this module is `decoder.py`_.
202
203.. _the MIT license: http://www.opensource.org/licenses/mit-license.php
204.. _decoder.py: http://www.brailleweb.com/cgi-bin/python.py
205
