Update documentation for text support.

Change-Id: I43acad9ae62f89b06491a3b56fb846da1edd4002

README.md

@@ -54,8 +54,23 @@ Shaka Packager supports:
   - ²: https://tools.ietf.org/html/draft-pantos-http-live-streaming-23#section-3.4
   - ³: Opus support in ISO-BMFF is experimental.
 - Subtitles
-  - WebVTT in both text form and embedded in MP4
-  - TTML in text form (DASH only)
+
+  |     Format    |  Input   | Output |
+  |:-------------:|:--------:|:------:|
+  |  Text WebVTT  |    Y     |    Y   |
+  | WebVTT in MP4 | [#405][] |    Y   |
+  |   Text TTML   |    ⁴     |    Y   |
+  |  TTML in MP4  |    -     |    Y   |
+  |    DVB-SUB    |    Y     |    -   |
+  |   Teletext    | [#272][] |    -   |
+
+  - ⁴: TTML input is only supported with TTML output (pass-through, DASH only),
+    see also [#584][].
+
+[#272]: https://github.com/google/shaka-packager/issues/272
+[#405]: https://github.com/google/shaka-packager/issues/405
+[#584]: https://github.com/google/shaka-packager/issues/584
+
 - Platforms
   - Linux
   - Mac

docs/source/options/stream_descriptors.rst

@@ -57,6 +57,9 @@ These are the available fields:
     If not specified, it will be derived from the file extension of the output
     file.
 
+    For subtitles in MP4, you can specify 'vtt+mp4' or 'ttml+mp4' to control
+    which text format is used.
+
 :trick_play_factor (tpf):
 
     Optional value which specifies the trick play, a.k.a. trick mode, stream

docs/source/tutorials/dash.rst

@@ -60,7 +60,7 @@ The above packaging command creates five single track fragmented mp4 streams
       --mpd_output h264.mpd
 
 The above packaging command creates two extra trick play tracks, besides the files
-genereated with the previous command.
+generated with the previous command.
 
 * static-live::
 

docs/source/tutorials/text.rst

@@ -0,0 +1,47 @@
+Text output formats
+===================
+
+Shaka Packager supports several text/subtitle formats for both input and output.
+We only support certain formats for output, other formats are converted to the
+specified output format.  With the exception of TTML pass-through, there are no
+restrictions of input vs output formats.
+
+
+Examples
+--------
+
+* TTML pass-through::
+
+    $ packager in=input.ttml,stream=text,output=output.ttml
+
+* Convert WebVTT to TTML::
+
+    $ packager in=input.vtt,stream=text,output=output.ttml
+
+* Embed WebVTT in MP4 (single-file)::
+
+    $ packager in=input.vtt,stream=text,output=output.mp4
+
+* Embed WebVTT in MP4 (segmented)::
+
+    $ packager 'in=input.vtt,stream=text,init_segment=init.mp4,segment_template=text_$Number$.mp4'
+
+* Convert WebVTT to TTML in MP4::
+
+    $ packager in=input.vtt,stream=text,format=ttml+mp4,output=output.mp4
+
+* Convert DVB-SUB to TTML in MP4::
+
+    $ packager in=input.ts,stream=text,format=ttml+mp4,output=output.mp4
+    $ packager 'in=input.ts,stream=text,format=ttml+mp4,init_segment=init.mp4,segment_template=text_$Number$.mp4'
+
+* Get a single page from DVB-SUB and set language::
+
+    $ packager in=input.ts,stream=text,cc_index=3,lang=en,format=ttml+mp4,output=output.mp4
+
+* Multiple languages::
+
+    $ packager \
+      in=in_en.vtt,stream=text,language=en,output=out_en.mp4 \
+      in=in_sp.vtt,stream=text,language=sp,output=out_sp.mp4 \
+      in=in_fr.vtt,stream=text,language=fr,output=out_fr.mp4

docs/source/tutorials/tutorials.rst

@@ -9,6 +9,7 @@ Tutorials
    hls.rst
    live.rst
    drm.rst
+   text.rst
    ads.rst
    ffmpeg_piping.rst
    http_upload.rst