Re: [PATCH] enable mplex to multiplex subtitle streams

README.subtitles 
- modifications by Roland Stadtmueller ([email protected]) . 2010/03/13

Intention:
==========

The intention of the adding subtitle support was to enable mplex to mux all streams
necessary for a DVD so that the mpeg2 stream created can be used directly for
further dvd creation. Please be aware that i do not use the term "authoring"

Limitations:
===========
mplex does NOT support the creation, editing or rendering of subtitles and menues yet.
It is still - and will probably always be - a muliplexer tool.
This means, that you need a handy binary subtitle stream at hand to be able to mplex
them into your target stream, text-based subtitle formats are not supported.

Palette handling
================
DVD's have their color palettes (color definitions for subtitles) in the PGC structure
(part of the IFO file). As mplex does not know about IFO there's no palette handling
within mplex. Fortunately enough, stand-alone players define a default palette for
subtitles. Within dvdauthor you can add a palette using the "-p" switch.

Supported formats:
==================
Currently only PS1 streams as generated by tcextract (from transcode > 0.6.x) are
supported. As tcextract extracts the ps1 stream from a program stream, all other
binary formats are supported indirectly whenever tcextract can extract them accordingly
(see format details)


What is it then all about?
==========================
For subtitle multiplexing, mplex takes a subtitle stream created by tcextract
(from the transcode package) and multiplexes it into the target stream.
The syntax is pretty much the same as you already know from mplex with following additions:

--subpicture-delay |-d <delay [suffix]>[:<stream-id>] [, [...]]

Specifies the offset between start of the subtitle and the video. This is necessary as in 
real life the subtitles do not begin exactly with the start of the video but some seconds
later. There's no automatic way to detect the correnct value, so you have to play around
a bit within your mplex'ed video.

You can specify following suffixes to the delay:
* ms <default>  : sync offset in milliseconds
*  s 		: sync offset in seconds
* mpt		: sync offset in 90KHz ticks
*  c		: sync offset in 90KHz*300 ticks

The optional subtitle stream-id overrides the subtitle stream id as provided in the source stream
(aka mappping).
Valid subtitle stream are in a range of 32-63 (including).

You may want to specify each stream you mplex, use "," to delimit each stream.

Example given:
If you want to mux one video, one audio and two subtitle streams having delays of 500 and 1000 ms,
the first shall have id 32, the second is 33 (Subtitle stream 0 and 1):

$ mplex -f 8 -o my_mpeg.mpeg -d 500:32,100:33 video_in.mpv audio_in.m2a subtitle_0.ps1 subtitle_1.ps1


Creating subtitle PS1 streams with transcode
============================================
This is a quite simple approach:

$ tcextract -i chapter_5.vob  -a 0x21 -x ps1 > chp5_1.ps1
extracts subtitle 1 (id 33) from chapter_5.vob into the chp5_1.ps1

If you have a VObSub file (these are the ones coming with "*.sub + *.idx" suffixes), you can do the same:
 
$ tcextract -i subtitle.sub  -a 0x20 -x ps1 > chp5_1.ps1
There's no need for the idx file here.

By the way, you can create a vobsub (*.sub + *.idx) file by using subtile2vobsub (included in the subtitleripper package)

The biggest drawback for now: as far as i know there's no (*NIX-) possibility to create ps1/vobsub streams directly from
text based subtitles. All the tools i know (mplayer, spumux) expect to have at least a program stream to cope with.
If you have (even a empty, useless ) stream, you can tcextract again.

PS 1 stream format (from tcextract)
===================================
(this should go to transcode, but anyway...)
Each subtitle entry starts with the tag "SUBTITLE", followed by a header entry:
typedef struct {

  unsigned int header_length;
  unsigned int header_version;
  unsigned int payload_length;

  unsigned int lpts;
  double rpts;
} subtitle_header_v3_t;

The header version is 0x00030000. The header_length specifies the length of the header w/o "SUBTITLE" and might
point behind the header struct (enclosing additional data). The header_data points to the beginning of the subtitle entry.
The subtitle entry length is specified by.payload_length. The "Subtitle entry" is the full subtile includung control
sequences and RLE-coded pictures as used in dvd subtitles (The "Subtitle entry" is a 1:1 copy of the source stream actually).
"lpts" and "rpts"  is the presentation time stamp of subtitle. LPTS seems to be the old fashioned way to do it and is not
in use anymore.