SPUMUX(1)                     DVDAuthor Man Pages                    SPUMUX(1)



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:

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

       o 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.

       o 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
       Leeman

                         Fri Dec 30 19:47:26 CET 2005                SPUMUX(1)