vorbis-python/README

   1 pyvorbis - a Python wrapper for the Ogg/Vorbis library
   2
   3 Ogg/Vorbis is available at http://www.xiph.org
   4
   5 This is the Vorbis module. You will need to download and install the
   6 Python ogg module (available wherever you got this) before you can
   7 build the vorbis module.
   8
   9 Access this module via "import ogg.vorbis" or "from ogg.vorbis import
  10 *". You can now write Python programs to encode and decode Ogg Vorbis
  11 files (encoding is quite a bit more involved). The module is
  12 self-documenting, though I need to update quite a bit of it. Look at
  13 test/ogg123.py, test/short.py, and test/enc.py for very simple
  14 demonstrations of the module interface.
  15
  16 And if anyone is wondering why I have things separated into a main
  17 module "ogg" and a submodule "ogg.vorbis", vorbis is the audio subset
  18 of the ogg bitstream. In the future there will likely be a video part
  19 of the ogg bistream, and nothing in the ogg modulue really has to know
  20 about anything specific in the vorbis module.
  21
  22 To build, you need the distutils package, availible from
  23 http://www.python.org/sigs/distutils-sig/download.html (it comes with
  24 Python 2.0). Run config_unix.py first to generate a Setup file. Then
  25 run "python setup.py build" to build and then as root run "python
  26 setup.py install".  You may need to run config_unix.py with a
  27 "--prefix" option if you installed your ogg or vorbis libraries in a
  28 weird place. You can also pass --with-ogg-dir and --with-vorbis-dir
  29 arguments if they're installed separately. If you have problems with
  30 the configure script, check the output of conifg.log for specific
  31 errors.
  32
  33 To decode, you'll basically want to create a VorbisFile object and
  34 read data from that.  You can then write the data to a sound
  35 device. I've used both the pyao wrapper (also by me) and the
  36 linuxsounddev module present in Python2.0.
  37
  38 To encode, you need to feed a VorbisDSPState object PCM data as one
  39 array of floating point values ranging from -1.0 ... 1.0 per
  40 channel. You can do this in pure Python, but it almost doubles the
  41 time it takes to encode. The other option is to read data using the
  42 python "wave" module and write it to the VorbisDSPState directly using
  43 the x.write_wav(mywave.readframes(n)) call. This will only work with
  44 16-bit Wave files.
  45
  46 Perhaps you are wondering how much of a performance hit you'll be
  47 taking using the Python bindings versus straight C. Well, I've tried
  48 to make things as fast as possible, but of course nothing's
  49 perfect. Decoding a file, top reports about the same CPU usage for my
  50 ogg123.py and the C implementation of ogg123. For encoding, it's about
  51 twice as slow as oggenc if you're using my test enc.py file (parsing
  52 the wave file somewhat by hand). If you use the write_wav function,
  53 it's only about 3% slower than oggenc.
  54
  55
  56
  57 Vorbis Comment
  58 --------------
  59
  60 A frequent question is how to edit and then write comments. This was
  61 not possible until recently. To implement this, I have taken the code
  62 from the vorbiscomment program, which is by Michael Smith and released
  63 under the LGPL. It has not been modified by me (Andrew).
  64
  65 There was an old way of dealing with VorbisComment objects, which
  66 sucked, so I won't tell you how to use it. It still works but is
  67 deprecated.
  68
  69 The current way of using VorbisComment objects is just to convert to
  70 and from Python dictionaries. Note that there can be multiple entries
  71 per key and that keys are case-insensitive 7-bit ASCII, because that's
  72 how vorbis comments work. So I might do:
  73
  74 >>> import ogg.vorbis
  75 >>> v = {'mykey' : ['myval1', 'myval2']}
  76 >>> v['artist'] = u'andrew' # Unicode string for Python >= 1.6
  77 >>> print v
  78 {'artist': 'andrew', 'mykey': ['myval1', 'myval2']}
  79 >>> comments = ogg.vorbis.VorbisComment(v)
  80
  81 There, we made a comment object from a dictionary. The values of the
  82 dictionary are either strings or lists or strings. We can also convert
  83 back to a dictionary, though it'll look a little different:
  84
  85 >>> print comments.as_dict()
  86 {'ARTIST': [u'andrew'], 'MYKEY': ['myval1', 'myval2']}
  87
  88 We could also have gotten a comment object from a vorbis file:
  89
  90 >>> import ogg.vorbis
  91 >>> f = ogg.vorbis.VorbisFile('test.ogg')
  92 >>> print f.comment().as_dict()
  93
  94 To write the comments to an existing ogg/vorbis file, call v.write_to
  95 or v.append_to. The former will add lots of keys, so if you already
  96 have an artist key, and you add another, you now have two arist keys
  97 in that file. Note that currently the VENDOR tag (which is special)
  98 doesn't get written to the file. I'll have to look into that.