[xiph-commits] r3313 - liboggz/trunk

Mon Dec 10 22:45:14 PST 2007

Author: conrad
Date: 2007-12-10 22:45:14 -0800 (Mon, 10 Dec 2007)
New Revision: 3313

Modified:
   liboggz/trunk/README
Log:
update liboggz README


Modified: liboggz/trunk/README
===================================================================

--- liboggz/trunk/README	2007-12-11 06:38:50 UTC (rev 3312)
+++ liboggz/trunk/README	2007-12-11 06:45:14 UTC (rev 3313)
@@ -1,17 +1,48 @@
-liboggz is a library that provides simple parsing and seeking of files
-and streams based on the Ogg file format. liboggz requires libogg to
-work.
+About Oggz
+----------
 
-liboggz knows about Ogg speex, Ogg vorbis, Ogg theora, and the Ogg
-based Annodex formats, thus allows parsing (though not decoding) of
-these files. For getting decoding and encoding functionality you will
-require in addition libspeex, libvorbis, libtheora, and libannodex
-respectively.
+Oggz comprises liboggz and the command-line tools oggzinfo, oggzdump,
+oggzdiff, oggzmerge, oggzrip, oggz-comment, oggz-scan and oggz-validate.
 
+liboggz is a C library providing a simple programming interface for reading
+and writing Ogg files and streams. Ogg is an interleaving data container
+developed by Monty at Xiph.Org, originally to support the Ogg Vorbis audio
+format.
+
+Dependencies
+------------
+
+Oggz depends only on libogg, available in most free software
+distributions, or in source form at: http://xiph.org/downloads/
+
+Support is built-in for parsing the headers of and seeking to time
+positions in Ogg Speex, Vorbis, FLAC, Theora, PCM and CMML. Oggz is also
+compatible with Annodex streams, and supports seeking on all tracks
+described in an Ogg Skeleton track.
+
+Installation
+------------
+
+This library can be installed using the conventional commands:
+
+    $ ./configure
+    $ make check
+    $ sudo make install
+
+sequence. Full details in the file INSTALL.
+
+Read the file README.win32 for installing under MS Windows, and
+README.symbian for information about building for Symbian devices.
+
+Source layout
+-------------
+
 The src/ directory contains the source code.
 The src/liboggz/ directory has the library source code.
 The src/tools/ directory has some command line tools for analysing
-               ogg files.
+               Ogg files.
+The src/examples/ directory contains example programs using liboggz.
+The src/tests/ directory contains unit and functional tests.
 
 The include/ directory contains the oggz include files that will
 be installed into the system include directory.
@@ -21,9 +52,90 @@
 in the source code.
 
 The win32/ directory contains the files necessary to compile the
-library for MS Windows.
+library and tools for MS Windows.
 
-This library is installed using the standard configure, make, make
-install sequence. Full details in the file INSTALL.
+The symbian/ directory contains the files necessary to compile the
+library for Symbian.
 
-Read the file README.win32 for installing under MS Windows.
+
+Programming with liboggz
+------------------------
+
+liboggz supports the flexibility afforded by the Ogg file format while
+presenting the following API niceties:
+
+    * Full API documentation
+
+    * Comprehensive test suite of read, write and seeking behavior.
+    The entire test suite can be run under valgrind if available.
+
+    * Developed and tested on GNU/Linux, Darwin/MacOSX, Win32 and
+    Symbian OS. May work on other Unix-like systems via GNU autoconf.
+    For Win32: nmake Makefiles, Visual Studio .NET 2003 solution files
+    and Visual C++ 6.0 workspace files are provided in the source
+    distribution.
+
+    * Strict adherence to the formatting requirements of Ogg bitstreams,
+    to ensure that only valid bitstreams are generated; writes can fail
+    if you try to write illegally structured packets.
+
+    * A simple, callback based open/read/close or open/write/close
+    interface to raw Ogg files.
+
+    * Writing automatically interleaves with packet queuing, and provides
+    callback based notification when this queue is empty
+
+    * A customisable seeking abstraction for seeking on multitrack Ogg
+    data. Seeking works easily and reliably on multitrack and multi-codec
+    streams, and can transparently parse Theora, Speex, Vorbis, FLAC,
+    PCM, CMML and Ogg Skeleton headers  without requiring linking to those
+    libraries. This allows efficient use on servers and other devices
+    that need to parse and seek within Ogg files, but do not need to do
+    a full media decode.
+
+Full documentation of the liboggz API, customization and installation,
+and mux and demux examples can be read online at:
+
+    http://www.annodex.net/software/liboggz/html/
+
+Tools
+-----
+
+The Oggz source tarball also contains the following command-line tools,
+which are useful for debugging and testing Ogg bitstreams:
+
+    * oggzinfo: Display information about one or more Ogg files and
+    their bitstreams.
+
+    * oggzdump: Hexdump packets of an Ogg file, or revert an Ogg file
+    from such a hexdump.
+
+    * oggzdiff: Hexdump the packets of two Ogg files and output
+    differences.
+
+    * oggzmerge: Merge Ogg files together, interleaving pages in order
+    of presentation time.
+
+    * oggzrip: Extract one or more logical bitstreams from an Ogg file.
+
+    * oggz-comment: List or edit comments in an Ogg file.
+
+    * oggz-scan: Scan an Ogg file and output characteristic landmarks.
+
+    * oggz-validate: Validate the Ogg framing of one or more files.
+
+License
+-------
+
+Oggz is Free Software, available under a BSD style license.
+
+More information is available online at the Oggz homepage:
+
+    http://www.annodex.net/software/liboggz/
+
+enjoy :)
+
+--
+Conrad Parker
+Senior Software Engineer, Continuous Media Web, CSIRO Australia
+http://www.annodex.net/   http://www.ict.csiro.au/cmweb/

