|
Packit |
a38265 |
Documentation files for Oggz
|
|
Packit |
a38265 |
----------------------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
PATCHES: Instructions for generating patches
|
|
Packit |
a38265 |
README: this file
|
|
Packit |
a38265 |
README.symbian: Instructions for building for Symbian
|
|
Packit |
a38265 |
README.win32: Instructions for building on Win32
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Run:
|
|
Packit |
a38265 |
----
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
$ oggz help
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
for documentation of the various oggz commands.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
About Oggz
|
|
Packit |
a38265 |
==========
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Oggz comprises liboggz and the tool oggz, which provides commands to
|
|
Packit |
a38265 |
inspect, edit and validate Ogg files. The oggz-chop tool can also be
|
|
Packit |
a38265 |
used to serve time ranges of Ogg media over HTTP by any web server that
|
|
Packit |
a38265 |
supports CGI.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
liboggz is a C library for reading and writing Ogg files and streams.
|
|
Packit |
a38265 |
It offers various improvements over the reference libogg, including
|
|
Packit |
a38265 |
support for seeking, validation and timestamp interpretation. Ogg is
|
|
Packit |
a38265 |
an interleaving data container developed by Monty at Xiph.Org,
|
|
Packit |
a38265 |
originally to support the Ogg Vorbis audio format but now used for
|
|
Packit |
a38265 |
many free codecs including Dirac, FLAC, Speex and Theora.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Dependencies
|
|
Packit |
a38265 |
------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Oggz depends only on libogg, available in most free software
|
|
Packit |
a38265 |
distributions, or in source form at: http://xiph.org/downloads/
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Support is built-in for parsing the headers of and seeking to time
|
|
Packit |
a38265 |
positions in Ogg Dirac, FLAC, Speex, Theora and Vorbis. Oggz is also
|
|
Packit |
a38265 |
compatible with Annodex streams, and supports seeking on all tracks
|
|
Packit |
a38265 |
described in an Ogg Skeleton track.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Installation
|
|
Packit |
a38265 |
------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Release archives can be installed using the conventional commands:
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
$ ./configure
|
|
Packit |
a38265 |
$ make check
|
|
Packit |
a38265 |
$ sudo make install
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
sequence. Configuration details are in the file INSTALL. If you obtained
|
|
Packit |
a38265 |
this source by svn, first run "./autogen.sh" to create the configure script,
|
|
Packit |
a38265 |
then run the above commands.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Read the file README.win32 for installing under MS Windows, and
|
|
Packit |
a38265 |
README.symbian for information about building for Symbian devices.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Source layout
|
|
Packit |
a38265 |
-------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
doc/
|
|
Packit |
a38265 |
doc/liboggz autocreated by the doxygen tool from comments
|
|
Packit |
a38265 |
contained in the public C header files
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
include/ public C header files
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
src/
|
|
Packit |
a38265 |
src/liboggz/ library source code.
|
|
Packit |
a38265 |
src/tools/ command line tools
|
|
Packit |
a38265 |
src/examples/ example programs using liboggz
|
|
Packit |
a38265 |
src/tests/ unit and functional tests
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
symbian/ files necessary to compile the library for Symbian
|
|
Packit |
a38265 |
win32/ files necessary to compile the library and tools for
|
|
Packit |
a38265 |
Microsoft Windows
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Developers
|
|
Packit |
a38265 |
----------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
liboggz is maintained in git at git://git.xiph.org/liboggz.git
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
A list of outstanding tasks is maintained in the TODO file of this source
|
|
Packit |
a38265 |
distribution. When implementing anything listed in this file, please update
|
|
Packit |
a38265 |
it by deleting that entry, and include that as part of the patch or commit
|
|
Packit |
a38265 |
that implements the fix.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Please send patches to ogg-dev@xiph.org
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Programming with liboggz
|
|
Packit |
a38265 |
------------------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
liboggz supports the flexibility afforded by the Ogg file format while
|
|
Packit |
a38265 |
presenting the following API niceties:
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* Full API documentation
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* Comprehensive test suite of read, write and seeking behavior.
|
|
Packit |
a38265 |
The entire test suite can be run under valgrind if available.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* Developed and tested on GNU/Linux, Darwin/MacOSX, Win32 and
|
|
Packit |
a38265 |
Symbian OS. May work on other Unix-like systems via GNU autoconf.
|
|
Packit |
a38265 |
For Win32: nmake Makefiles, Visual Studio .NET 2003, 2005 and 2008
|
|
Packit |
a38265 |
solution files are provided in the source distribution.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* Strict adherence to the formatting requirements of Ogg bitstreams,
|
|
Packit |
a38265 |
to ensure that only valid bitstreams are generated; writes can fail
|
|
Packit |
a38265 |
if you try to write illegally structured packets.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* A simple, callback based open/read/close or open/write/close
|
|
Packit |
a38265 |
interface to raw Ogg files.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* Writing automatically interleaves with packet queuing, and provides
|
|
Packit |
a38265 |
callback based notification when this queue is empty
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
* A customisable seeking abstraction for seeking on multitrack Ogg
|
|
Packit |
a38265 |
data. Seeking works easily and reliably on multitrack and multi-codec
|
|
Packit |
a38265 |
streams, and can transparently parse Theora, Speex, Vorbis, FLAC,
|
|
Packit |
a38265 |
PCM, CMML and Ogg Skeleton headers without requiring linking to those
|
|
Packit |
a38265 |
libraries. This allows efficient use on servers and other devices
|
|
Packit |
a38265 |
that need to parse and seek within Ogg files, but do not need to do
|
|
Packit |
a38265 |
a full media decode.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Full documentation of the liboggz API, customization and installation,
|
|
Packit |
a38265 |
and mux and demux examples can be read online at:
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
http://www.xiph.org/oggz/doc/
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
oggz tool
|
|
Packit |
a38265 |
---------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Usage: oggz <subcommand> [options] filename ...
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
oggz is a commandline tool for manipulating Ogg files. It supports
|
|
Packit |
a38265 |
multiplexed files conformant with RFC3533. Oggz can parse headers for CELT,
|
|
Packit |
a38265 |
CMML, Dirac, FLAC, Kate, PCM, Speex, Theora and Vorbis, and can read and write
|
|
Packit |
a38265 |
Ogg Skeleton logical bitstreams.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Commands:
|
|
Packit |
a38265 |
help Display help for a specific subcommand (eg. "oggz help chop")
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Reporting:
|
|
Packit |
a38265 |
codecs Display the codecs present in an Ogg file
|
|
Packit |
a38265 |
diff Hexdump the packets of two Ogg files and output differences.
|
|
Packit |
a38265 |
dump Hexdump packets of an Ogg file, or revert an Ogg file from
|
|
Packit |
a38265 |
such a hexdump.
|
|
Packit |
a38265 |
info Display information about one or more Ogg files and their
|
|
Packit |
a38265 |
bitstreams.
|
|
Packit |
a38265 |
scan Scan an Ogg file and output characteristic landmarks.
|
|
Packit |
a38265 |
validate Validate the Ogg framing of one or more files.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Extraction:
|
|
Packit |
a38265 |
rip Extract one or more logical bitstreams from an Ogg file.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Editing:
|
|
Packit |
a38265 |
chop Extract the part of an Ogg file between given start and/or
|
|
Packit |
a38265 |
end times.
|
|
Packit |
a38265 |
comment List or edit comments in an Ogg file.
|
|
Packit |
a38265 |
merge Merge Ogg files together, interleaving pages in order of
|
|
Packit |
a38265 |
presentation time.
|
|
Packit |
a38265 |
sort Sort the pages of an Ogg file in order of presentation time.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Miscellaneous:
|
|
Packit |
a38265 |
known-codecs List codecs known by this version of oggz
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
The script bash-completion/oggz enables completion of tool options and codec
|
|
Packit |
a38265 |
names when using the bash shell. Source it from your .profile, or install it
|
|
Packit |
a38265 |
in /etc/bash_completion.d to enable it system-wide.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
oggz-chop: General usage and CGI installation
|
|
Packit |
a38265 |
---------------------------------------------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
oggz-chop extracts the part of an Ogg file between given start and/or end
|
|
Packit |
a38265 |
times. The output file contains copies of the headers of the input file, and
|
|
Packit |
a38265 |
all the codec data required to correctly decode the content between the start
|
|
Packit |
a38265 |
and end times specified on the commandline. For codecs with data dependencies
|
|
Packit |
a38265 |
like video keyframes, the keyframe prior to the starting time will be included
|
|
Packit |
a38265 |
in the output.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
An Apache server can be configured to use oggz-chop to handle all Ogg files
|
|
Packit |
a38265 |
(or, all Ogg files in a particular directory). An example Apache configuration
|
|
Packit |
a38265 |
is in the liboggz source tree, along with a script for installing it on a
|
|
Packit |
a38265 |
Debian server.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
The oggz-chop binary checks if it is being run as a CGI script (by checking
|
|
Packit |
a38265 |
some environment variables), and if so acts based on the CGI query parameter
|
|
Packit |
a38265 |
t=, much like mod_annodex. It accepts all the time specifications that
|
|
Packit |
a38265 |
mod_annodex accepts (npt and various smpte framerates), and start and end
|
|
Packit |
a38265 |
times separated by a /.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
License
|
|
Packit |
a38265 |
-------
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
Oggz is Free Software, available under a BSD style license.
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
More information is available online at the Oggz homepage:
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
http://xiph.org/oggz/
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
enjoy :)
|
|
Packit |
a38265 |
|
|
Packit |
a38265 |
--
|
|
Packit |
a38265 |
Conrad Parker
|
|
Packit |
a38265 |
http://www.annodex.net/
|