ffmpeg2theora/subtitles.txt

   1 Text subtitles can be embedded in an Ogg stream alongside a Theora video.
   2
   3  * Overview
   4  * Subtitles related options
   5  * Converting non-utf-8 files to utf-8
   6  * Examples
   7  * Playing subtitles
   8
   9
  10
  11  * Overview
  12
  13 Subtitles are read from SubRip (.srt) format files and converted to
  14 Kate streams. Those SubRip files must be encoded in utf-8 (7 bit ASCII
  15 is a subset of utf-8 so are valid input as well). See below for more
  16 information on converting SubRip files with other encodings to utf-8.
  17
  18 Subtitles support requires libkate, available from:
  19 http://code.google.com/p/libkate
  20
  21 A subtitles input file is given with the --subtitles option.
  22 The language of subtitles in a file is given by the --subtitles-language
  23 option. See below for a list of subtitles related options. At the most
  24 simple, supplying a single input file:
  25
  26   ./ffmpeg2theora -o output.ogv --subtitles input.srt input.avi
  27
  28 Any number of subtitles streams can be multiplexed, presumably with
  29 different languages and/or categories. See below for examples of this.
  30
  31
  32
  33  * Subtitles related options
  34
  35 --subtitles <file>
  36    Loads subtitles from a file, which must be an utf-8 encoded SubRip
  37    (.srt) file
  38
  39 --subtitles-language <language>
  40   Sets the language of the relevant subtitles stream. Language must be
  41   a language tag according to RFC 3066 (usually a two letter language
  42   code, optionally followed by a dash (or underscore) and a region code.
  43   Examples include en, it, ja, en_GB, de_DE, etc.
  44   If unspecified, the default is to not set a language.
  45
  46 --subtitles-category <category>
  47   Sets the category of the relevant subtitles stream. Category must be
  48   a free text string describing the type of the subtitles streams. This
  49   is meant to be parsable automatically, so should be ASCII only, and
  50   preferably among a list of predefined well known categories, such as
  51   subtitles, commentary, transcript, lyrics.
  52   If unspecified, the default is subtitles.
  53
  54 --subtitles-encoding <encoding>
  55   Sets the encoding of the relevant input file. Allowed encodings are
  56   utf-8, utf8, iso-8859-1, and latin1. The first two are synonymous and
  57   yield no conversion. The latter two are synonymous and convert from
  58   iso-8859-1 to utf-8.
  59   If the input file is in another encoding, a separate step is needed
  60   to convert the input file to utf-8. See below for more information on
  61   converting other encoding to utf-8.
  62   If unspecified, the default is utf-8.
  63
  64 --subtitles-ignore-non-utf8
  65   Any invalid sequence in utf-8 text will be ignored. This may be useful
  66   when using an utf-8 file with stray non utf-8 characters. This is not
  67   a substitute for converting a non utf-8 file to utf-8, however, as the
  68   non utf-8 sequence will be missing from the output stream.
  69
  70
  71
  72  * Converting non-utf-8 files to utf-8
  73
  74 If you have SubRip files in another format than utf-8, you can use the
  75 iconv or recode programs to convert them to utf-8 so ffmpeg2theora can
  76 read them.
  77
  78    * iconv
  79       If you have a file called subtitles.srt which is not in utf-8,
  80       you can convert it to utf-8 with the command:
  81
  82          iconv -t utf-8 -f ENCODING subtitles.srt > subtitles.utf8.srt
  83
  84       Substitute ENCODING with the actual encoding of the input file.
  85       For instance, if your input file is in Shift-JIS encoding, replace
  86       ENCODING with SHIFT-JIS. If your input file is in big endian UCS2
  87       encoding, replace ENCODING with UCS-2BE.
  88
  89       This will create a new file called subtitles.utf8.srt, which will
  90       be the equivalent of the input file, but in utf-8 format, so it
  91       can be used as input to ffmpeg2theora.
  92
  93       To view a list of all the encodings iconv can convert to utf-8,
  94       see the output of `iconv -l'.
  95
  96    * recode
  97
  98       If you have a file called subtitles.srt which is not in utf-8,
  99       you can convert it to utf-8 with the command:
 100
 101          recode ENCODING..utf-8 < subtitles.srt > subtitles.utf8.srt
 102
 103       Substitute ENCODING with the actual encoding of the input file.
 104       For instance, if your input file is in Shift-JIS encoding, replace
 105       ENCODING with SHIFT-JIS. If your input file is in BIG5 encoding,
 106       replace ENCODING with BIG5.
 107
 108       This will create a new file called subtitles.utf8.srt, which will
 109       be the equivalent of the input file, but in utf-8 format, so it
 110       can be used as input to ffmpeg2theora.
 111
 112       To view a list of all the encodings recode can convert to utf-8,
 113       see the output of `recode -l'.
 114
 115
 116  * Examples
 117
 118     Add a single English subtitles stream:
 119
 120       ./ffmpeg2theora --subtitles-language en --subtitles input.srt input.avi
 121
 122     Add German and Italian commentary:
 123
 124       ./ffmpeg2theora --subtitles comm.german.srt --subtitles-language de \
 125                       --subtitles-category commentary \
 126                       --subtitles comm.italian.srt --subtitles-language it \
 127                       --subtitles-category commentary \
 128                       input.avi
 129
 130     Add English subtitles and commentary:
 131
 132       ./ffmpeg2theora --subtitles subs.srt --subtitles-language en \
 133                       --subtitles-category subtitles \
 134                       --subtitles commentary.srt --subtitles-language en \
 135                       --subtitles-category commentary \
 136                       input.avi
 137
 138
 139  * Playing subtitles
 140
 141 At the moment, only VLC has playback support for Kate streams. However, the
 142 libkate distribution includes patches for other players and media frameworks
 143 (MPlayer, GStreamer).
 144