Provided by: dvdauthor_0.7.0-1.2ubuntu1_amd64 bug

NAME

       spumux - generates and multiplexes subtitles into an existing mpeg2 program stream

SYNOPSIS

       spumux  [  -m  dvd  |  -m  cvd | -m svcd ] [ -s stream ] [ -v level ] [ -P ] [ --nomux ] [
       --nodvdauthor-data ] file < mpeg > mpeg-with-subtitles

DESCRIPTION

       spumux encodes the subtitles and multiplexes it into the mpeg2 program stream.

       -m mode
              Sets the encoding for the subtitles.  Can be dvd, cvd, or svcd.  Default is dvd.

       -s stream
              Sets the subtitle stream id.  Default is 0.

       -v level
              Sets the verbosity level.

       -P     Enables a progress bar.

       --nomux
              Disables reading of an MPEG stream from standard input. Instead,  the  output  will
              contain only the subpicture stream.

       --nodvdauthor-data
              Disables passing of color and button info to dvdauthor.

       Here's a sample configuration file:

       <subpictures>
          <stream>
             <spu start="start-time" [ end="end-time" ] [ image="picture.png" ]
                  [ highlight="picture.png" ] [ select="picture.png" ]
                  [ transparent="color-spec" ] [ force="yes" ]
                  [ autooutline="infer" [ outlinewidth="width" ]
                    [ autoorder="rows" | autoorder="columns" ] ]
                  [ xoffset="x-coord" yoffset="y-coord" ] >
                <button [ name="name" ] [ x0="x0" ] [ y0="y0" ] [ x1="x1" ]
                        [ y1="y1" ] [ up="name" ] [ down="name" ]
                        [ left="name" ] [ right="name" ] />
                <action [ name="name" ] [ x0="x0" ] [ y0="y0" ] [ x1="x1" ]
                        [ y1="y1" ] />
             </spu>
          </stream>
       </subpictures>

       Each  subtitle  image is described by an <spu> tag.  The start and optional end attributes
       describe when the subtitle will be displayed on the screen, in "HR:MM:SS.HU".   The  image
       attribute  describes  the  main subtitle image, which can either be a PNG or BMP file.  If
       your image is not a full screen image, you can use xoffset and yoffset to move the picture
       around.   In  the  advent that the author is unable to use a graphics format with an alpha
       channel, then the transparent attribute can be used to describe which color should  become
       fully transparent.  For the valid formats for color-spec, see SPECIFYING COLORS below.  If
       you want to force the display of the subtitle, regardless of whether the user has  enabled
       subtitles  or not, you can use the force tag.  When you are making menus, the force tag is
       required.

       The remaining attributes and tags are related to menu creation.  The  highlight  attribute
       shows  what  all  the buttons look like when they are highlighted (i.e. when you are using
       the arrows in the menu), and the select attribute shows what all  the  buttons  look  like
       when  the  are  selected (i.e. for the 1-2 seconds after you press enter in the menu).  If
       either of these (or the image attribute) are omitted, then spumux creates a blank (totally
       transparent) image.  Obviously at least one tag should be specified.

       To  aid  in button creation, the autooutline attribute instructs spumux to infer where the
       buttons are located.  It does this by attempting to draw rectangles around  a  composition
       of  the  highlight  and  select  images  which  do not intersect any opaque or semi-opaque
       pixels.  In order to support textual buttons, the attribute  outlinewidth  allows  you  to
       specify  the  width  of  the rectangle which is tested.  Wider rectangles won't be able to
       squeeze between the  letters.   Finally,  autoorder  describes  which  way  to  order  the
       automatically  detected  buttons,  which is important for numerically selected buttons and
       for mapping buttons to button names or to the implied names.

       The button and action tags describe the buttons (visibly selectable objects on the screen)
       and  actions  (commands  that are executed as soon as the associated key is pressed on the
       remote).  If you are using the autooutline feature, just designing buttons, are happy with
       the  inferred  button navigation, and can deal with the simplistic naming system, then you
       actually do not even need to specify any buttons or actions.  Otherwise, read on.

       The name attribute is used to give a button or action  an  easy  to  refer  to  name.   By
       default  they  are numbered sequentially starting with "1".  The up, down, left, and right
       names describe which button or action should be tied to the  corresponding  key  when  the
       current  button is highlighted, though if omitted spumux will use a reasonably intelligent
       algorithm to determine which buttons to move to.

       The (x0,y0) coordinates describe the upper left hand corner inclusively, while the (x1,y1)
       coordinates  describe  the  lower right hand corner EXclusively.  The coordinates start at
       0,0 for the upper left hand corner.  Ideally, the y0 and y1  coordinates  should  both  be
       even,  so  the  button  edges fully empasses two interlaced scanlines, even if there is no
       data in the extra scanline.  Some DVD players will fill in the extra scanline if it is not
       specified;  spumux  makes  an  effort  to  ensure that will be transparent but there is no
       guarantee.

HANDLING TEXT-BASED SUBTITLES

       Spumux is also able to handle text subtitles,  which  will  be  rendered  to  graphics  by
       spumux.  A  lot of different text (must be non-graphic) formats are supported (.sub, .srt,
       .ssa, .smi, .rt , .txt, .aqt, .jss, .js, ass).  Spumux will try to  determine  the  format
       automatically.

       If processing text-based subtitles no other streams can be defined, buttons or others need
       to be processed in another pass with spumux, using another xml file.

       Following .xml file shows the available tags and their default settings.  Only the textsub
       tag is mandatory, defaults are used if the specific tag is not specified.

       <subpictures [format="NTSC|PAL"]>
          <stream>
             <textsub filename="demo1.srt" characterset="UTF-8"
                fontsize="28.0" font="arial" fill-color="color-spec"
                outline-color="color-spec" outline-thickness="3.0"
                shadow-offset="0, 0" shadow-color="color-spec"
                horizontal-alignment="left"  vertical-alignment="bottom"
                left-margin="60" right-margin="60"
                top-margin="20" bottom-margin="30" subtitle-fps="fps"
                movie-fps="fps"
                movie-width="720" movie-height="height" aspect="4:3"
                force="yes"
             />
          </stream>
       </subpictures>

       The textsub tag defines the settings for the text to graphics rendering.

       The  filename attribute defines the path and name of the input text subtitle file, this is
       the only attribute that is mandatory.

       The characterset attribute defines the characterset to be  used,  available  charactersets
       can be found at http://www.gnu.org/software/libiconv.

       The  fontsize  attribute  defines  the size of the font in font units.  The font attribute
       defines the font used. Spumux will match the font name using Fontconfig if available, else
       it  will  use  it  as a filename on linux systems and will look into the windows/fonts and
       subdirectory spumux of the cygwin/mingw home directory and into  the  execution  directory
       for windows-based execution for the specified font. Looking for free fonts? One listing is
       here http://www.microsoft.com/typography/links/links.asp?type=free&part=1  (this  is  only
       about fonts, not about operating systems).

       The  fill-color  attribute  specifies the color to be used for filling the interior of the
       text, while outline-color specifies the color for the outline border to draw  around  each
       character,  to  set  it  off  from  the video background.  The outline-thickness attribute
       specifies the thickness of this  outline.  For  the  valid  formats  for  color-spec,  see
       SPECIFYING COLORS below.  The default fill color is white and the default outline color is
       black.

       The shadow-offset and shadow-color attributes specify a shadow effect to be applied to the
       text.  The  shadow-offset  is  specified  as  2  signed integers, being the horizontal and
       vertical offset respectively, with positive values being to the right and  down.  For  the
       valid  formats  for  color-spec, see SPECIFYING COLORS below.  The default shadow color is
       black.

       The horizontal-alignment attribute defines the  horizontal  alignment  of  the  subtitles.
       Options  are:  "left", "right", "center" and "default".  The "default" value causes spumux
       to use the attribute that is in the text subtitle file if  the  format  supports  such  an
       attribute.

       The  vertical-alignment  attribute  defines  the  vertical alignment.  Options are: "top",
       "center" and "bottom".

       The margin attributes define the minimum blank pixel space between the border of the image
       and the border of the subtitle lines.

       The  subtitle-fps  is  needed  for  subtitle  formats  which use frame numbers rather than
       fractional seconds for specifying subtitle times, while the movie-fps is the frame rate of
       the  movie  onto  which  the  subtitles  are  being multiplexed; if omitted, both of these
       default to 29.97 for NTSC and 25 for PAL.

       Having separate subtitle-fps and movie-fps attributes  make  it  possible  for  spumux  to
       recalculate the subtitle timing if these are not the same.

       The  movie-width and movie-height attributes define the maximum size of the subtitle page,
       these shouldn't be larger than the size of the video frame (720x480 for NTSC, 720x576  for
       PAL), normally they are the same.  Some DVD players prefer subtitle frames that are 2 or 4
       pixels smaller in height.  If omitted, the default movie width is 720 and the height is  2
       pixels less than the video frame height.

       The  aspect attribute lets you specify whether the video aspect ratio is 16:9 (widescreen)
       or 4:3. This, together with the video format, is used to adjust the rendering of the  text
       to ensure it appears undistorted.

       The  force  option  allows you to force the display of the subtitle, regardless of whether
       the user has enabled subtitles or not.

SPECIFYING COLORS

       Colors for image transparency and text fill and outlines can be specified in a  number  of
       ways:

       • As  a  color  name,  e.g.  "green".  You  can  use  most  of  the  color names listed at
         <http://www.imagemagick.org/script/color.php>.

       • As a hexadecimal string preceded by a "#", similar to HTML format, e.g.  "#FF8080".  The
         number  of  digits must be a multiple of 3; the first group specifies the red component,
         the second green, and the third blue.

       • As the name of a color space, followed by one to four component values  in  parentheses,
         e.g. "hsv(120, 50%, 90%)".

       Valid color spaces are "gray" (1 component), "graya" (2 components), "hsl" (3 components),
       "hsla" (4 components), "hsv" (3 components), "hsva" (4 components), "rgb"  (3  components)
       and  "rgba"  (4 components). Each component can be specified as either a percentage of the
       maximum value suffixed by "%", or an absolute value in the range 0-360 for hues, 0-255 for
       everything  else.  For  color space names ending with "a", the last component is the alpha
       (transparency) value.

       Note that alpha values are meaningless for the "transparent" attribute on  the  <spu>  tag
       above.  <marc.leeman@gmail.com> MarcLeeman2003Marc LeemanFri Dec 30 19:47:26 CET 2005

                                         23 October 2010                                SPUMUX(1)