README

libkate
=======

a library for encoding and decoding Kate streams

This is libkate, the reference implementation of a codec for the Kate
bitstream format.

Kate is a karaoke and text codec meant for encapsulation in an Ogg
container.  It can carry Unicode text, images, and animate them.
Arbitrary timed metadata can be included as well.

Kate is meant to be used for karaoke alongside audio/video streams
(typically Vorbis and Theora), movie subtitles, song lyrics, and
anything that needs text data at arbitrary time intervals.

The latest version of libkate can be found at:

https://gitlab.xiph.org/xiph/kate/

More information can be found at the xiph wiki:

https://wiki.xiph.org/index.php/OggKate

A Git repository can be found at:

https://gitlab.xiph.org/xiph/kate/

libtiger, a rendering library for Kate streams using Pango and Cairo,
is at:

https://code.google.com/archive/p/libtiger/downloads

For build instructions, see INSTALL.

A sample encoder and decoder are included in this distribution, in the
tools directory.

To encode a Kate stream from a kate text file:

  $ kateenc -t kate -o output.kate.ogg input.kate


To encode a Kate stream from a SubRip (.srt) format file:

  $ katedec -t srt -o output.kate.ogg input.srt

To decode a Kate stream:

  $ katedec -o output.kate input.kate.ogg

In addition, two more tools are available:

 * katalyzer displays various information about Kate streams.

 * KateDJ is a GUI remixing program for Kate streams in Ogg. It uses
   wxPython, a set of Python bindings for wxWidgets, which might not
   be universally available.  KateDJ also depends on the oggz tools,
   available from www.annodex.net.

For more info on those tools, see the man pages in the doc/man
directory.

VLC 1.0 can decode and display basic text and SPU based Kate streams,
and can display any Kate stream if compiled with libtiger.  I have
preliminary support for Kate streams for MPlayer, xine, and GStreamer
(and thus all players that rely on them for decoding), which will be
contributed to those projects once the Kate bitstream format is
stable. The current diffs for those can be found in the diffs
directory. See the README in the diffs directory for more information
on those patches.  NOTE: the diffs tree is not shipped in the tarballs
anymore, it is now only available in the git tree.


This distribution is Copyright (C) 2008 Vincent Penquerc'h.

   Use, distribution and reproduction of this library is governed
   by a BSD style source license included with this source in the
   file 'COPYING'. Please read these terms before distributing.