1SPUMUX(1)                     DVDAuthor Man Pages                    SPUMUX(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

15       spumux  encodes the subtitles and multiplexes it into the mpeg2 program
16       stream.
17
18       -m mode
19              Sets the encoding for the subtitles.  Can be dvd, cvd, or  svcd.
20              Default is dvd.
21
22       -s stream
23              Sets the subtitle stream id.  Default is 0.
24
25       -v level
26              Sets the verbosity level.
27
28       -P     Enables a progress bar.
29
30       --nomux
31              Disables reading of an MPEG stream from standard input. Instead,
32              the output will contain only the subpicture stream.
33
34       --nodvdauthor-data
35              Disables passing of color and button info to dvdauthor.
36
37       Here's a sample configuration file:
38
39       <subpictures>
40          <stream>
41             <spu start="start-time" [ end="end-time" ] [ image="picture.png" ]
42                  [ highlight="picture.png" ] [ select="picture.png" ]
43                  [ transparent="color-spec" ] [ force="yes" ]
44                  [ autooutline="infer" [ outlinewidth="width" ]
45                    [ autoorder="rows" | autoorder="columns" ] ]
46                  [ xoffset="x-coord" yoffset="y-coord" ] >
47                <button [ name="name" ] [ x0="x0" ] [ y0="y0" ] [ x1="x1" ]
48                        [ y1="y1" ] [ up="name" ] [ down="name" ]
49                        [ left="name" ] [ right="name" ] />
50                <action [ name="name" ] [ x0="x0" ] [ y0="y0" ] [ x1="x1" ]
51                        [ y1="y1" ] />
52             </spu>
53          </stream>
54       </subpictures>
55
56       Each subtitle image is described  by  an  <spu>  tag.   The  start  and
57       optional end attributes describe when the subtitle will be displayed on
58       the screen, in "HR:MM:SS.HU".  The image attribute describes  the  main
59       subtitle  image,  which can either be a PNG or BMP file.  If your image
60       is not a full screen image, you can use xoffset and yoffset to move the
61       picture  around.   In  the  advent  that  the author is unable to use a
62       graphics format with an alpha channel, then the  transparent  attribute
63       can  be  used  to describe which color should become fully transparent.
64       For the valid formats for color-spec, see SPECIFYING COLORS below.   If
65       you  want  to  force the display of the subtitle, regardless of whether
66       the user has enabled subtitles or not, you can use the force tag.  When
67       you are making menus, the force tag is required.
68
69       The  remaining  attributes  and tags are related to menu creation.  The
70       highlight attribute shows what all the buttons look like when they  are
71       highlighted  (i.e.  when you are using the arrows in the menu), and the
72       select attribute shows what all the buttons  look  like  when  the  are
73       selected  (i.e. for the 1-2 seconds after you press enter in the menu).
74       If either of these (or the image attribute) are  omitted,  then  spumux
75       creates  a  blank  (totally transparent) image.  Obviously at least one
76       tag should be specified.
77
78       To aid in button creation, the autooutline attribute  instructs  spumux
79       to  infer where the buttons are located.  It does this by attempting to
80       draw rectangles around a composition of the highlight and select images
81       which  do  not intersect any opaque or semi-opaque pixels.  In order to
82       support textual buttons, the attribute outlinewidth allows you to spec‐
83       ify the width of the rectangle which is tested.  Wider rectangles won't
84       be able to squeeze between the letters.  Finally,  autoorder  describes
85       which  way to order the automatically detected buttons, which is impor‐
86       tant for numerically selected buttons and for mapping buttons to button
87       names or to the implied names.
88
89       The  button  and  action  tags describe the buttons (visibly selectable
90       objects on the screen) and actions (commands that are executed as  soon
91       as  the associated key is pressed on the remote).  If you are using the
92       autooutline  feature,  just  designing  buttons,  are  happy  with  the
93       inferred  button  navigation,  and  can deal with the simplistic naming
94       system, then you actually do not even need to specify  any  buttons  or
95       actions.  Otherwise, read on.
96
97       The  name attribute is used to give a button or action an easy to refer
98       to name.  By default they are numbered sequentially starting with  "1".
99       The  up,  down,  left,  and right names describe which button or action
100       should be tied to the corresponding key  when  the  current  button  is
101       highlighted, though if omitted spumux will use a reasonably intelligent
102       algorithm to determine which buttons to move to.
103
104       The (x0,y0) coordinates describe the  upper  left  hand  corner  inclu‐
105       sively,  while  the  (x1,y1)  coordinates describe the lower right hand
106       corner EXclusively.  The coordinates start at 0,0 for  the  upper  left
107       hand  corner.   Ideally, the y0 and y1 coordinates should both be even,
108       so the button edges fully empasses two interlaced  scanlines,  even  if
109       there  is no data in the extra scanline.  Some DVD players will fill in
110       the extra scanline if it is not specified; spumux makes  an  effort  to
111       ensure that will be transparent but there is no guarantee.
112

HANDLING TEXT-BASED SUBTITLES

114       Spumux is also able to handle text subtitles, which will be rendered to
115       graphics by spumux. A lot of different text (must be non-graphic)  for‐
116       mats  are  supported  (.sub,  .srt, .ssa, .smi, .rt , .txt, .aqt, .jss,
117       .js, ass).  Spumux will try to determine the format automatically.
118
119       If processing text-based subtitles no other  streams  can  be  defined,
120       buttons  or  others  need  to be processed in another pass with spumux,
121       using another xml file.
122
123       Following .xml file shows the available tags  and  their  default  set‐
124       tings.   Only  the  textsub  tag is mandatory, defaults are used if the
125       specific tag is not specified.
126
127       <subpictures [format="NTSC|PAL"]>
128          <stream>
129             <textsub filename="demo1.srt" characterset="UTF-8"
130                fontsize="28.0" font="arial" fill-color="color-spec"
131                outline-color="color-spec" outline-thickness="3.0"
132                shadow-offset="0, 0" shadow-color="color-spec"
133                horizontal-alignment="left"  vertical-alignment="bottom"
134                left-margin="60" right-margin="60"
135                top-margin="20" bottom-margin="30" subtitle-fps="fps"
136                movie-fps="fps"
137                movie-width="720" movie-height="height" aspect="4:3"
138                force="yes"
139             />
140          </stream>
141       </subpictures>
142
143       The textsub tag defines the settings for the text to  graphics  render‐
144       ing.
145
146       The filename attribute defines the path and name of the input text sub‐
147       title file, this is the only attribute that is mandatory.
148
149       The characterset attribute defines the characterset to be used,  avail‐
150       able  charactersets  can  be found at http://www.gnu.org/software/libi
151       conv.
152
153       The fontsize attribute defines the size of the font in font units.  The
154       font  attribute  defines the font used. Spumux will match the font name
155       using Fontconfig if available, else it will use it  as  a  filename  on
156       linux  systems  and  will  look into the windows/fonts and subdirectory
157       spumux of the cygwin/mingw home directory and into the execution direc‐
158       tory  for  windows-based  execution for the specified font. Looking for
159       free  fonts?  One  listing  is  here  http://www.microsoft.com/typogra
160       phy/links/links.asp?type=free&part=1  (this  is  only  about fonts, not
161       about operating systems).
162
163       The fill-color attribute specifies the color to be used for filling the
164       interior  of  the text, while outline-color specifies the color for the
165       outline border to draw around each character, to set it  off  from  the
166       video background.  The outline-thickness attribute specifies the thick‐
167       ness of this outline. For the valid formats for color-spec, see  SPECI‐
168       FYING  COLORS  below.   The default fill color is white and the default
169       outline color is black.
170
171       The shadow-offset and shadow-color attributes specify a  shadow  effect
172       to  be  applied to the text. The shadow-offset is specified as 2 signed
173       integers, being the horizontal and vertical offset  respectively,  with
174       positive  values being to the right and down. For the valid formats for
175       color-spec, see SPECIFYING COLORS below.  The default shadow  color  is
176       black.
177
178       The  horizontal-alignment attribute defines the horizontal alignment of
179       the subtitles. Options are: "left", "right",  "center"  and  "default".
180       The  "default"  value causes spumux to use the attribute that is in the
181       text subtitle file if the format supports such an attribute.
182
183       The  vertical-alignment  attribute  defines  the  vertical   alignment.
184       Options are: "top", "center" and "bottom".
185
186       The  margin attributes define the minimum blank pixel space between the
187       border of the image and the border of the subtitle lines.
188
189       The subtitle-fps is needed for subtitle formats which use frame numbers
190       rather than fractional seconds for specifying subtitle times, while the
191       movie-fps is the frame rate of the movie onto which the  subtitles  are
192       being  multiplexed; if omitted, both of these default to 29.97 for NTSC
193       and 25 for PAL.
194
195       Having separate subtitle-fps and movie-fps attributes make it  possible
196       for  spumux  to  recalculate  the  subtitle timing if these are not the
197       same.
198
199       The movie-width and movie-height attributes define the maximum size  of
200       the subtitle page, these shouldn't be larger than the size of the video
201       frame (720x480 for NTSC, 720x576 for PAL), normally they are the  same.
202       Some  DVD players prefer subtitle frames that are 2 or 4 pixels smaller
203       in height.  If omitted, the default movie width is 720 and  the  height
204       is 2 pixels less than the video frame height.
205
206       The aspect attribute lets you specify whether the video aspect ratio is
207       16:9 (widescreen) or 4:3. This, together with the video format, is used
208       to adjust the rendering of the text to ensure it appears undistorted.
209
210       The  force  option  allows  you  to  force the display of the subtitle,
211       regardless of whether the user has enabled subtitles or not.
212

SPECIFYING COLORS

214       Colors for image transparency and text fill and outlines can be  speci‐
215       fied in a number of ways:
216
217       · As  a  color  name, e.g. "green". You can use most of the color names
218         listed at <http://www.imagemagick.org/script/color.php>.
219
220       · As a hexadecimal string preceded by a "#", similar  to  HTML  format,
221         e.g.  "#FF8080".  The  number  of digits must be a multiple of 3; the
222         first group specifies the red component, the second  green,  and  the
223         third blue.
224
225       · As  the name of a color space, followed by one to four component val‐
226         ues in parentheses, e.g. "hsv(120, 50%, 90%)".
227
228       Valid color spaces are "gray" (1 component),  "graya"  (2  components),
229       "hsl"  (3  components),  "hsla"  (4  components), "hsv" (3 components),
230       "hsva" (4 components), "rgb" (3 components) and "rgba" (4  components).
231       Each  component  can be specified as either a percentage of the maximum
232       value suffixed by "%", or an absolute value  in  the  range  0-360  for
233       hues, 0-255 for everything else. For color space names ending with "a",
234       the last component is the alpha (transparency) value.
235
236       Note that alpha values are meaningless for the "transparent"  attribute
237       on  the  <spu>  tag  above.  <marc.leeman@gmail.com> MarcLeeman2003Marc
238       LeemanFri Dec 30 19:47:26 CET 2005
239
240
241
242                                23 October 2010                      SPUMUX(1)
Impressum