[ogg-dev] HOgg 0.4.0 Release

[Conrad Parker]

HOgg 0.4.0 Released
-------------------

The HOgg package provides a commandline tool for manipulating Ogg files,
and a corresponding Haskell library. HOgg is in hackage, or on the web at:

  http://www.kfish.org/~conrad/software/hogg/

This is the third public release. The focus is on correctness of Ogg
parsing, production and editing. The capabilities of the hogg commandline
tool are roughly on par with those of the oggz* [0] tools.

HOgg supports chained and multiplexed Ogg bitstreams conformant with
RFC3533[1]. HOgg can parse headers for CELT, CMML, FLAC, OggPCM, Speex,
Theora and Vorbis media codecs, and can read and write Ogg Skeleton bitstreams.

[0] Oggz: http://www.annodex.net/software/liboggz/index.html
[1] RFC3533: http://www.ietf.org/rfc/rfc3533.txt


New in this release
-------------------

The hogg tool contains new subcommands: sort, selfcheck

Improved handling of Ogg Skeleton tracks in chop, merge and rip subcommands:

  * merge: Ensure that the output contains only one Skeleton track. Fisbones
    from Skeleton tracks of second and subsequent files are copied into the
    first Skeleton track.

  * chop: Handle rewriting of Skeleton when chopping files which already have
    a Skeleton track. Ensure to re-use the existing track serialno and
    metadata, but rewrite the presentation time and basegranules.

  * rip: also include the Skeleton track and fisbones for the track being
    ripped.

  * Added --no-skeleton option to hogg tool, to disable inclusion of
    Skeleton in output of rip, chop etc.

hogg dump: Fixed display of timestamps for keyframes, and when frame number
and framerate had a common divisor (by avoiding Rational simplification).

Codec-specific changes:
  * add support for parsing CELT headers and granulepos
  * read nheaders from bos pages for speex and flac
  * record Ogg FLAC's Ogg mapping version in hogg info

Documentation changes:
  * Add README to source tarball
  * Added long descriptions to help for each subcommand.
  * hogg selfcheck: checks that the help examples are valid, ie. that the
    commandlines given pass through getOpt without errors. This option is
    also run silently after printing out any help output so that such errors
    are more likely to be found and reported.
  * Added sections explaining handling of Theora, Skeleton and chains to all
    relevant subcommand help descriptions.
  * Use recommended file extensions in help examples (ie. .ogv, .oga etc.)


Installation
------------

I am very interested in hearing about problems with building or installing
the package, particularly from people who are not yet familiar with building
from Haskell source. You need ghc instead of gcc; it compiles to a binary:

    $ ./Setup.hs configure
    $ ./Setup.hs build
    $ sudo ./Setup.hs install

Building of this release has been tested with:
  * GHC versions 6.4, 6.6 and 6.8.1 [2]
  * The Haskell build system "Cabal" versions 1.1.3, 1.1.4, 1.1.6, and the
    current development trunk. [3]

The GHC and Cabal versions listed above span the packages available in most
current distributions. I've tested on Debian unstable and Ubuntu Feisty. I'm
particularly interested to hear reports of build success or failure on other
distributions or operating systems.

[2] GHC: http://www.haskell.org/ghc/
[3] Cabal: http://www.haskell.org/cabal/


Usage
-----

$ hogg help
Usage: hogg <subcommand> [options] filename ...

Commands:
  help          Display help for a specific subcommand (eg. "hogg help chop")

Reporting:
  info          Display information about the file and its bitstreams
  dump          Hexdump packets of an Ogg file
  pagedump      Display page structure of an Ogg file
  dumpraw       Dump raw (unparsed) page data

Extraction:
  rip           Rip selected logical bistreams from an Ogg file (default:
all)
  reconstruct   Reconstruct an Ogg file by doing a full packet demux

Editing:
  chop          Extract a section (specify start and/or end time)
  merge         Merge, interleaving pages in order of presentation time
  sort          Rewrite with correct page ordering
  addskel       Write a Skeleton logical bitstream

Miscellaneous:
  known-codecs  List codecs known by this version of hogg

Please report bugs to <ogg-dev at xiph.org>


New subcommand sort
-------------------

$ hogg help sort
sort: Rewrite with correct page ordering
Usage: hogg sort [options] filename ...

  This sorts an Ogg file, interleaving pages in order of presentation time.
  It correctly interprets the granulepos timestamps of CELT, CMML, FLAC, PCM,
  Speex, Theora and Vorbis bitstreams.

  Some encoders produce files with incorrect page ordering; for example, some
  audio and video pages may occur out of order. Although these files are
  usually playable, it can be difficult to accurately seek or scrub on them,
  increasing the likelihood of glitches during playback. Players may also
  need to use more memory in order to buffer the audio and video data for
  synchronized playback, which can be a problem when the files are viewed on
  low-memory devices.

  Theora handling: Theora BOS pages will be written before BOS pages of other
  codecs.

  Skeleton handling: If a Skeleton track is present in the input file, the
  first page of the output file will be the Skeleton BOS page, and the order
  of other Skeleton packets is preserved.

  Chain handling: Each chain is sorted separately, and chain ordering is
  preserved.

Examples:
  Correct the page ordering in broken.ogv:
    hogg sort -o fixed.ogv broken.ogv

Options:
  -h, -?       --help             Display this help and exit
  -V           --version          Output version information and exit
  -o filename  --output=filename  Specify output filename


Source
------

Source code is available from the darcs repository at:

  darcs get http://www.kfish.org/~conrad/software/hogg/

Tarballs are available from:

  http://www.kfish.org/~conrad/software/hogg/

cheers,

Conrad.