From c4ea028d11ca17ca02ac1a64b6f71df4a3e93e17 Mon Sep 17 00:00:00 2001
From: Jacob Trimble <modmaker@google.com>
Date: Thu, 21 Jan 2021 13:42:10 -0800
Subject: [PATCH] Update documentation for text support.

Change-Id: I43acad9ae62f89b06491a3b56fb846da1edd4002
---
 README.md                                  | 19 ++++++++-
 docs/source/options/stream_descriptors.rst |  3 ++
 docs/source/tutorials/dash.rst             |  2 +-
 docs/source/tutorials/text.rst             | 47 ++++++++++++++++++++++
 docs/source/tutorials/tutorials.rst        |  1 +
 5 files changed, 69 insertions(+), 3 deletions(-)
 create mode 100644 docs/source/tutorials/text.rst

diff --git a/README.md b/README.md
index a08350f731..4e6617442d 100644
--- a/README.md
+++ b/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
diff --git a/docs/source/options/stream_descriptors.rst b/docs/source/options/stream_descriptors.rst
index a942708337..7b5aaf1666 100644
--- a/docs/source/options/stream_descriptors.rst
+++ b/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
diff --git a/docs/source/tutorials/dash.rst b/docs/source/tutorials/dash.rst
index 9ec314bbf5..f379953369 100644
--- a/docs/source/tutorials/dash.rst
+++ b/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::
 
diff --git a/docs/source/tutorials/text.rst b/docs/source/tutorials/text.rst
new file mode 100644
index 0000000000..502c309336
--- /dev/null
+++ b/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
diff --git a/docs/source/tutorials/tutorials.rst b/docs/source/tutorials/tutorials.rst
index 4a62bea786..a6a7234496 100644
--- a/docs/source/tutorials/tutorials.rst
+++ b/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