<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libkate: </title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h2><a class="anchor" id="HOWTO-text-subtitles">
Text movie subtitles</a></h2>
<p>Kate streams can carry Unicode text (that is, text that can represent pretty much any existing language/script). If several Kate streams are multiplexed along with a video, subtitles in various languages can be made for that movie.</p>
<p>An easy way to create such subtitles is to use ffmpeg2theora, which can create Kate streams from SubRip (.srt) format files, a simple but common text subtitles format. ffmpeg2theora 0.21 or later is needed.</p>
<p>At its simplest:</p>
<div class="fragment"><pre class="fragment">
ffmpeg2theora -o video-with-subtitles.ogg --subtitles subtitles.srt
video-without-subtitles.avi
</pre></div><p>Several languages may be created and tagged with their language code for easy selection in a media player:</p>
<div class="fragment"><pre class="fragment">
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
</pre></div><p>Alternatively, kateenc (which comes with the libkate distribution) can create Kate streams from SubRip files as well. These can then be merged with a video with oggz-tools:</p>
<div class="fragment"><pre class="fragment">
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
</pre></div><p>This second method can also be used to add subtitles to a video which is already encoded to Theora, as it will not transcode the video again.</p>
<h2><a class="anchor" id="HOWTO-DVD-subtitles">
DVD subtitles</a></h2>
<p>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 this to be possible out of the box, so patching them will be required).</p>
<p>When configuring how to rip DVD tracks, any subtitles will be detected by Thoggen, and selecting them in the GUI will cause them to be saved as Kate tracks along with the movie.</p>
<h2><a class="anchor" id="HOWTO-lyrics">
Song lyrics</a></h2>
<p>Kate streams carrying song lyrics can be embedded in an Ogg file. The oggenc Vorbis encoding tool from the Xiph.Org Vorbis tools allows lyrics to be loaded from a LRC or SRT text file and converted to a Kate stream multiplexed with the resulting Vorbis audio. At the time of writing, the patch to oggenc was not applied yet, so it will have to be patched manually with the patch found in the diffs directory.</p>
<div class="fragment"><pre class="fragment">
oggenc -o song-with-lyrics.ogg --lyrics lyrics.lrc --lyrics-language en_US song.wav
</pre></div><p>So called 'enhanced LRC' files (containing extra karaoke timing information) are supported, and a simple karaoke color change scheme will be saved out for these files. For more complex karaoke effects (such as more complex style changes, or sprite animation), kateenc should be used with a Kate description file to create a separate Kate stream, which can then be merged with a Vorbis only song with oggz-tools:</p>
<div class="fragment"><pre class="fragment">
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
</pre></div><p>This latter method may also be used if you already have an encoded Vorbis song with no lyrics, and just want to add the lyrics without reencoding.</p>
<h2><a class="anchor" id="HOWTO-remuxing">
Changing a Kate stream embedded in an Ogg stream</a></h2>
<p>If you need to 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.</p>
<p>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).</p>
<p>The procedure consists of:</p>
<ul>
<li>Run KateDJ</li>
<li>Click 'Load Ogg stream' and select the file to load</li>
<li>Click 'Demux file' to decode Kate streams in a temporary location</li>
<li>Edit the Kate streams - you can also double click on the language you want to change</li>
<li>When done, click 'Remux file from parts'</li>
<li>If any errors are reported, continue editing until the remux step succeeds </li>
</ul>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on Wed Dec 23 04:05:07 2009 for libkate by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
