Changes

Jump to: navigation, search

OggKate

8,086 bytes added, 04:24, 15 June 2012
m
Reverted edits by WikiCleaner (talk) to last revision by Ogg.k.ogg.k
== What is Kate? ==
Kate is a an overlay codec , originally designed for karaoke and text encapsulation for , that can bemultiplixed in Ogg. Text and images can becarried by a Kate stream, and animated. Most of the time, this would be multiplexedwith audio/video to carry subtitles, song lyrics (with or without karaoke data), etc,but doesn't have to be. A possible use of a lone Kate stream would be an e-book.Moreover, the motion feature gives Kate a powerful means to describe arbitrary curves, sohand drawing of shapes can be achieved. This was originally meant for karaoke use, butcan be used for any purpose. Motions can be attached to various semantics, like position,color, etc, so scrolling or fading text can be defined.
Simple Series of curves (splines, segments, etc) may be attached to various properties(text position, font size, etc) to create animated overlays. This allows scrollingor fading text to be defined. This can even be used to draw arbitrary shapes, sohand drawing can also be represented by a Kate stream. Example uses of Kate streams are movie subtitles for Theora videos, either text based,
as may be created by [http://www.v2v.cc/~j/ffmpeg2theora ffmpeg2theora], or image
based, such as created by [http://thoggen.net Thoggen] (patching needed), and lyrics,as created by oggenc, from vorbis-tools.
== Why a new codec? ==
*text data: text/image and optional motions, accompanied by optional overrides for style, region, language, etc
*keepalive: can be emitted at any time to help a demuxer know where we're at, but those packets are optional
*repeats: a verbatim repeat of a text packet's payload, in order to bound any backward seeking needed when starting to play a stream partway through. These are also optional.
*end data [EOS]: marks the end of the stream, it doesn't have any useful payload
::0x00 text data (including optional motions and overrides)
::0x01 keepalive
::0x02 repeat
::0x7f end packet (EOS)
This format described here is for bitstream version 0.x.
As or 19 december 2008, the latest bitstream version is 0.4.
For more detailed information, refer to the format documentation
*liboggz
*liboggplay
*Cortado (wikimedia version)
*vorbis-tools
I have patches for the following with Kate support:
*MPlayer (for multiplexed per-language subtitles - all region/style info is ignored)*xine (everything kate supports, as xine is my testbed)
*GStreamer
*Thoggen
*Audacious
*and more...
These may be found in the libkate source distribution (see [[#Downloading|Downloading]]
Please remember the 15 character limit if proposing other categories.
* Note that the list of categories is subject to change, and will likely be replaced by new, more "identifier like" ones. The three ones above, however, would be kept for backward compatibility as they're already used.
== Text to speech ==
== Reference encoder/decoder ==
A encoder (kateenc) and a decoder (katedec) are included in the tools directory. The encoder pulls its supports input from several different formats:* a customtext based file format (see [[#The Kate file format|The Kate file format]]),which is by no means meant to be part of the Kate bitstream specification itself,from an * SubRip (.srt) format file (, the most common subtitle format I found* LRC lyrics format. As an example for the widely used SRT subtitles format, and the following command linecreate a very basic one)Kate subtitles stream from an SRT file: kateenc -l en -c subtitles -t srt -o subtites.ogg subtitles.srt The reverse is possible,or to recover an SRT file from a lyrics (Kate stream, with katedec. Note that the subtitles.lrc) format ogg fileshould then be multiplexed into the A/V stream,using either ogg-tools or oggz-tools.
The Kate bitstreams encoded and decoded by those tools are (supposed to be) correct for this
And after all, some people might prefer editing the XML version.
 
=== Packaging ===
 
It would be really nice to have packages for libkate/libtiger for many distros.
 
If you're a packager for a distro which doesn't have yet packages for libkate
or libtiger, please consider helping :)
 
In particular, packages for Debian would be grand.
== Matroska mapping ==
A public git repository is available at [http://git.xiph.org/?p=users/oggk/tiger.git;a=summary http://git.xiph.org/?p=users/oggk/tiger.git;a=summary].
== Things I HOWTOs == These paragraphs describe a few ways to use Kate streams: === Text movie subtitles === Kate streams can carry Unicode text (that is, text that can representpretty much any existing language/script). If several Kate streams aremultiplexed along with a video, subtitles in various languages can bemade for that movie. An easy way to create such subtitles is to use ffmpeg2theora, whichcan create Kate streams from SubRip (.srt) format files, a simple butcommon text subtitles format. ffmpeg2theora 0.21 or later is needed. At its simplest:  ffmpeg2theora -o video-with-subtitles.ogg --subtitles subtitles.srt video-without-subtitles.avi Several languages may be created and tagged with their language codefor easy selection in a media player:  ffmpeg2theora -o video-with-subtitles.ogg video-without-subtitles.avi --subtitles japanese-subtitles.srt --subtitles-language ja --subtitles welsh-subtitles.srt --subtitles-language cy --subtitles english-subtitles.srt --subtitles-language en_GB Alternatively, kateenc (which comes with the libkate distribution) cancreate Kate streams from SubRip files as well. These can then be mergedwith a video with oggz-tools:  kateenc -t srt -c SUB -l it -o subtitles.ogg italian-subtitles.srt oggz merge -o movie-with-subtitles.ogg movie-without-subtitles.ogg subtitles.ogg This second method can also be used to add subtitles to a video whichis already encoded to Theora, as it will not transcode the video again.  === DVD subtitles === DVD subtitles are not text, but images. Thoggen, a DVD ripper program,can convert these subtitles to Kate streams (at the time of writing,Thoggen and GStreamer have not applied the necessary patches for thisto be possible out of the box, so patching them will be required). When configuring how to rip DVD tracks, any subtitles will be detectedby Thoggen, and selecting them in the GUI will cause them to be saved asKate tracks along with the movie.  === Song lyrics === Kate streams carrying song lyrics can be embedded in an Ogg file. Theoggenc Vorbis encoding tool from the Xiph.Org Vorbis tools allows lyricsto be loaded from a LRC or SRT text file and converted to a Kate streammultiplexed with the resulting Vorbis audio. At the time of writing,the patch to oggenc was not applied yet, so it will have to be patchedmanually with the patch found in the diffs directory.  oggenc -o song-with-lyrics.ogg --lyrics lyrics.lrc --lyrics-language en_US song.wav So called 'enhanced LRC' files (containing extra karaoke timing information)are supported, and a simple karaoke color change scheme will be savedout for these files. For more complex karaoke effects (such as more complex style changes, or sprite animation), kateenc should be used witha Kate description file to create a separate Kate stream, which can thenbe merged with a Vorbis only song with oggz-tools:  oggenc -o song.ogg song.wav kateenc -t kate -c LRC -l en_US -o lyrics.ogg lyrics-with-karaoke.kate oggz merge -o song-with-karaoke.ogg lyrics-with-karaoke.ogg song.ogg This latter method may also be used if you already have an encoded Vorbis songwith no lyrics, and just want to add the lyrics without reencoding.  === Metadata === Metadata can be attached to events, or to styles, bitmaps, regions, etc.Metadata are free form tag/value pairs, and can be used to enrich theirattached data with extra information. However, how this information isinterpreted is up to the application layer. It is worth noting that an event may not have attached text, so it ispossible to create an empty timed event with attached metadata. For instance, let's say we have a documentary, with footage from variousplaces, as well as short interviews, and we want two things:- tag footage with metadata about the location and date that footage was shot- subtitle the interviews and tag those subtitles with information about the speaker You can then create an empty Kate event for each footage part, synchronizedwith the footage, and attach a new metadata item called GEO_LOCATION, filledwith latitude and longitude of the place the footage was shot at.Similarly, for each subtitle event, a metadata item called SPEAKER can beattached. An empty event to tag a long 4:20 footage shot in Tokyo on 2011/08/12, andinserted at 18:30 in the documentary could look like:  event { 00:18:30,000 --> 00:22:50,000 meta "GEO_LOCATION" = "35.42; 139.42" meta "DATE" = "2011-08-12" } Here's a example for a line spoken by Dr Joe Bloggs at 18:30 into the documentary:  event { 00:18:30,000 --> 00:18:32,000 "Notice how the subtitles for my words have metadata attached to them" meta "SPEAKER" = "Dr Joe Bloggs" meta "URL" = "http://www.example.com/biography?name=Joe+Bloggs" } Notice how another metadata item, URL, is also present. The applicationwill have to be aware of those metadata in order to do something with itthough. Since those are free form, it is up to you to think of whatmetadata you want, and make use of it. Note that metadata may be attached to other objects, such as regions.This way, you can for example create a region tagged with a name, andtrack a person's movements with that region. Or you can tag a bitmapwith a copyright and a URL to a larger version of the image.   === Changing a Kate stream embedded in an Ogg stream === If you need to get feedback change a Kate stream already embedded in an Ogg stream (eg, you have a movie with subtitles, and you want to fix a spelling mistake, or want to bring one of the subtitles forward in time, etc), you can do this easily with KateDJ, a tool that will extract Kate streams, decode them to a temporary location, and rebuild the original stream after you've made whatever changes you want. KateDJ (included with the libkate distribution) is a GUI program using wxPython, a Python module for the wxWidgets GUI library, and the oggz tools (both needing installing separately if they are not already). The procedure consists of: * Run KateDJ* Click 'Load Ogg stream' and select the file to load* Click 'Demux file' to decode Kate streams in a temporary location* Edit the Kate streams (a message box tells you where they are placed)* When done, click 'Remux file from parts'* If any errors are reported, continue editing until the remux step succeeds == Frequently Asked Questions == === Does libkate work on other plaforms than Linux ? === Yes, libkate is not Linux specific in any way. It optionally relies on liboggand libpng, two libraries widely ported to various platforms.It has been reported to work on Windows and MacOS X as well as UNIX platforms. However, libtiger, a rendering library for Kate streams, relies on Pango and Cairo,which are not easy to build on Windows, though they can be.The Tiger renderer is however completely separate from libkate, and is not neededfor full encoding and decoding of Kate streams. === Where can I find some example files ? === The libkate distribution can generate various examples, but already built filescan be found there:[http://people.xiph.org/~oggk/elephants_dream/elephantsdream-with-subtitles.ogg][http://stallman.org/fry/Stephen_Fry-Happy_Birthday_GNU-nq_600px_425kbit.ogv] These files use raw text only. 
* is it a good idea to avoid floating point usage altogether ?
[[Category:Drafts]]
[[Category:Ogg Mappings]]

Navigation menu