1SPUMUX(1) DVDAuthor Man Pages SPUMUX(1)
2
6 spumux - generates and multiplexes subtitles into an existing mpeg2
7 program stream
8
10 spumux [ -m dvd | -m cvd | -m svcd ] [ -s stream ] [ -v level ] [ -P ]
11 [ --nomux ] [ --nodvdauthor-data ] file < mpeg > mpeg-with-subtitles
12
15 spumux encodes the subtitles and multiplexes it into the mpeg2 program
16 stream.
17 -m mode
19 Sets the encoding for the subtitles. Can be dvd, cvd, or svcd.
20 Default is dvd.
21 -s stream
23 Sets the subtitle stream id. Default is 0.
24 -v level
26 Sets the verbosity level.
27 -P Enables a progress bar.
29 --nomux
31 Disables reading of an MPEG stream from standard input. Instead,
32 the output will contain only the subpicture stream.
33 --nodvdauthor-data
35 Disables passing of color and button info to dvdauthor.
36 Here's a sample configuration file:
38 <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 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 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 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 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 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 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
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 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 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 <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 The textsub tag defines the settings for the text to graphics render‐
144 ing.
145 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 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 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 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 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 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 The vertical-alignment attribute defines the vertical alignment.
184 Options are: "top", "center" and "bottom".
185 The margin attributes define the minimum blank pixel space between the
187 border of the image and the border of the subtitle lines.
188 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 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 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 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 The force option allows you to force the display of the subtitle,
211 regardless of whether the user has enabled subtitles or not.
212
214 Colors for image transparency and text fill and outlines can be speci‐
215 fied in a number of ways:
216 · 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 · 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 · 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 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 Note that alpha values are meaningless for the "transparent" attribute
237 on the <spu> tag above. <marc.leeman@gmail.com> MarcLeeman2003Marc
238 Leeman
239 Fri Dec 30 19:47:26 CET 2005 SPUMUX(1)