README.md
1pymad - a Python wrapper for the MPEG Audio Decoder library
2===========================================================
3
4[![Build Status](https://travis-ci.org/jaqx0r/pymad.svg?branch=master)](https://travis-ci.org/jaqx0r/pymad)
5
6pymad is a Python module that allows Python programs to use the MPEG Audio Decoder library. pymad provides a high-level API, similar to the pyogg module, which makes reading PCM data from MPEG audio streams a piece of cake.
7
8MAD is available at http://www.mars.org/home/rob/proj/mpeg/
9
10Access this module via `import mad`. To decode
11an mp3 stream, you'll want to create a `mad.MadFile` object and read data from
12that. You can then write the data to a sound device. See the example
13program in `test/` for a simple mp3 player that uses the `python-pyao` wrapper around libao for the sound
14device.
15
16pymad wrapper isn't as low level as the C MAD API is, for example, you don't
17have to concern yourself with fixed point conversion -- this was done to
18make pymad easy to use.
19
20```python
21import sys
22
23import ao
24import mad
25
26mf = mad.MadFile(sys.argv[1])
27dev = ao.AudioDevice(0, rate=mf.samplerate())
28while 1:
29 buf = mf.read()
30 if buf is None: # eof
31 break
32 dev.play(buf, len(buf))
33```
34
35
36To build, you need the distutils package, availible from
37http://www.python.org/sigs/distutils-sig/download.html (it comes with
38Python 2.0). Run `python setup.py build` to build and then as root run
39`python setup.py install`.
40
41if you've installed your mad stuff someplace weird you may need to run
42the config_unix.py script, passing it a `--prefix` value to create a
43`setup.cfg` file with the correct include and link dirs:
44
45```shell
46# python config_unix.py --prefix /usr/local
47# python setup.py build
48# python setup.py install --prefix /usr/local
49```
50
51Remember to make sure `/usr/local/python/site-packages/` is in your
52Python search path in that example.
53
54Alternately, you can write `setup.cfg` yourself. E.g.:
55
56 [build_ext]
57 library_dirs=/opt/mad/lib
58 include_dirs=/opt/mad/include
59 libraries=name_of_library_mad_might_depend_on
60