mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-05 03:54:35 +00:00
194 lines
6.8 KiB
Plaintext
194 lines
6.8 KiB
Plaintext
Documentation files for Oggz
|
|
----------------------------
|
|
|
|
PATCHES: Instructions for generating patches
|
|
README: this file
|
|
README.symbian: Instructions for building for Symbian
|
|
README.win32: Instructions for building on Win32
|
|
|
|
Run:
|
|
----
|
|
|
|
$ oggz help
|
|
|
|
for documentation of the various oggz commands.
|
|
|
|
About Oggz
|
|
==========
|
|
|
|
Oggz comprises liboggz and the tool oggz, which provides commands to
|
|
inspect, edit and validate Ogg files. The oggz-chop tool can also be
|
|
used to serve time ranges of Ogg media over HTTP by any web server that
|
|
supports CGI.
|
|
|
|
liboggz is a C library for reading and writing Ogg files and streams.
|
|
It offers various improvements over the reference libogg, including
|
|
support for seeking, validation and timestamp interpretation. Ogg is
|
|
an interleaving data container developed by Monty at Xiph.Org,
|
|
originally to support the Ogg Vorbis audio format but now used for
|
|
many free codecs including Dirac, FLAC, Speex and Theora.
|
|
|
|
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 Dirac, FLAC, Speex, Theora and Vorbis. Oggz is also
|
|
compatible with Annodex streams, and supports seeking on all tracks
|
|
described in an Ogg Skeleton track.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Release archives can be installed using the conventional commands:
|
|
|
|
$ ./configure
|
|
$ make check
|
|
$ sudo make install
|
|
|
|
sequence. Configuration details are in the file INSTALL. If you obtained
|
|
this source by svn, first run "./autogen.sh" to create the configure script,
|
|
then run the above commands.
|
|
|
|
Read the file README.win32 for installing under MS Windows, and
|
|
README.symbian for information about building for Symbian devices.
|
|
|
|
Source layout
|
|
-------------
|
|
|
|
doc/
|
|
doc/liboggz autocreated by the doxygen tool from comments
|
|
contained in the public C header files
|
|
|
|
include/ public C header files
|
|
|
|
src/
|
|
src/liboggz/ library source code.
|
|
src/tools/ command line tools
|
|
src/examples/ example programs using liboggz
|
|
src/tests/ unit and functional tests
|
|
|
|
symbian/ files necessary to compile the library for Symbian
|
|
win32/ files necessary to compile the library and tools for
|
|
Microsoft 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.xiph.org/oggz/doc/
|
|
|
|
oggz tool
|
|
---------
|
|
|
|
Usage: oggz <subcommand> [options] filename ...
|
|
|
|
oggz is a commandline tool for manipulating Ogg files. It supports
|
|
multiplexed files conformant with RFC3533. Oggz can parse headers for CELT,
|
|
CMML, Dirac, FLAC, Kate, PCM, Speex, Theora and Vorbis, and can read and write
|
|
Ogg Skeleton logical bitstreams.
|
|
|
|
Commands:
|
|
help Display help for a specific subcommand (eg. "oggz help chop")
|
|
|
|
Reporting:
|
|
codecs Display the codecs present in an Ogg file
|
|
diff Hexdump the packets of two Ogg files and output differences.
|
|
dump Hexdump packets of an Ogg file, or revert an Ogg file from
|
|
such a hexdump.
|
|
info Display information about one or more Ogg files and their
|
|
bitstreams.
|
|
scan Scan an Ogg file and output characteristic landmarks.
|
|
validate Validate the Ogg framing of one or more files.
|
|
|
|
Extraction:
|
|
rip Extract one or more logical bitstreams from an Ogg file.
|
|
|
|
Editing:
|
|
chop Extract the part of an Ogg file between given start and/or
|
|
end times.
|
|
comment List or edit comments in an Ogg file.
|
|
merge Merge Ogg files together, interleaving pages in order of
|
|
presentation time.
|
|
sort Sort the pages of an Ogg file in order of presentation time.
|
|
|
|
Miscellaneous:
|
|
known-codecs List codecs known by this version of oggz
|
|
|
|
The script bash-completion/oggz enables completion of tool options and codec
|
|
names when using the bash shell. Source it from your .profile, or install it
|
|
in /etc/bash_completion.d to enable it system-wide.
|
|
|
|
|
|
oggz-chop: General usage and CGI installation
|
|
---------------------------------------------
|
|
|
|
oggz-chop extracts the part of an Ogg file between given start and/or end
|
|
times. The output file contains copies of the headers of the input file, and
|
|
all the codec data required to correctly decode the content between the start
|
|
and end times specified on the commandline. For codecs with data dependencies
|
|
like video keyframes, the keyframe prior to the starting time will be included
|
|
in the output.
|
|
|
|
An Apache server can be configured to use oggz-chop to handle all Ogg files
|
|
(or, all Ogg files in a particular directory). An example Apache configuration
|
|
is in the liboggz source tree, along with a script for installing it on a
|
|
Debian server.
|
|
|
|
The oggz-chop binary checks if it is being run as a CGI script (by checking
|
|
some environment variables), and if so acts based on the CGI query parameter
|
|
t=, much like mod_annodex. It accepts all the time specifications that
|
|
mod_annodex accepts (npt and various smpte framerates), and start and end
|
|
times separated by a /.
|
|
|
|
License
|
|
-------
|
|
|
|
Oggz is Free Software, available under a BSD style license.
|
|
|
|
More information is available online at the Oggz homepage:
|
|
|
|
http://xiph.org/oggz/
|
|
|
|
enjoy :)
|
|
|
|
--
|
|
Conrad Parker
|
|
http://www.annodex.net/
|