libkate:

## Text movie subtitles

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.

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.

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 code for 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) can create Kate streams from SubRip files as well. These can then be merged with 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 which is 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 this to be possible out of the box, so patching them will be required).

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.

## Song lyrics

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.

        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 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:

        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 song with no lyrics, and just want to add the lyrics without reencoding.

## Changing a Kate stream embedded in an Ogg stream

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.

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