Debian Codegraph @

doc/spumux.sgml

raw
1 <refentry id="spumux">
2
3 <refmeta>
4 <refentrytitle>spumux</refentrytitle>
5 <manvolnum>1</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname>spumux</refname>
10 <refpurpose>generates and multiplexes subtitles into an existing mpeg2 program stream</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <cmdsynopsis>
15 <command>spumux</command>
16 <group>
17 <arg>-m dvd</arg>
18 <arg>-m cvd</arg>
19 <arg>-m svcd</arg>
20 </group>
21 <arg>-s <replaceable>stream</replaceable></arg>
22 <arg>-v <replaceable>level</replaceable></arg>
23 <arg>-P</arg>
24 <arg>--nomux</arg>
25 <arg>--nodvdauthor-data</arg>
26 <arg choice="req"><replaceable>file</replaceable></arg>
27 <arg choice="req">&lt <replaceable>mpeg</replaceable></arg>
28 <arg choice="req">&gt <replaceable>mpeg-with-subtitles</replaceable></arg>
29 </cmdsynopsis>
30 </refsynopsisdiv>
31
32 <refsect1><title>Description</title>
33 <para>
34 <command>spumux</command> encodes the subtitles and multiplexes it into the mpeg2 program stream.
35 </para>
36 <glosslist>
37 <glossentry><glossterm>-m <replaceable>mode</replaceable></glossterm>
38 <glossdef><para>
39
40 Sets the encoding for the subtitles. Can be dvd, cvd, or svcd.
41 Default is dvd.
42
43 </para></glossdef></glossentry>
44 <glossentry><glossterm>-s <replaceable>stream</replaceable></glossterm>
45 <glossdef><para>
46 Sets the subtitle stream id. Default is 0.
47 </para></glossdef></glossentry>
48 <glossentry><glossterm>-v <replaceable>level</replaceable></glossterm>
49 <glossdef><para>
50 Sets the verbosity level.
51 </para></glossdef></glossentry>
52 <glossentry><glossterm>-P</glossterm>
53 <glossdef><para>
54 Enables a progress bar.
55 </para></glossdef></glossentry>
56 <glossentry><glossterm>--nomux</glossterm>
57 <glossdef><para>
58 Disables reading of an MPEG stream from standard input. Instead, the output will
59 contain only the subpicture stream.
60 </para></glossdef></glossentry>
61 <glossentry><glossterm>--nodvdauthor-data</glossterm>
62 <glossdef><para>
63 Disables passing of color and button info to dvdauthor.
64 </para></glossdef></glossentry>
65 </glosslist>
66 <para>
67 Here's a sample configuration file:
68 </para>
69 <synopsis>
70 &lt;subpictures&gt;
71 &lt;stream&gt;
72 &lt;spu start="<replaceable>start-time</replaceable>" [ end="<replaceable>end-time</replaceable>" ] [ image="<replaceable>picture.png</replaceable>" ]
73 [ highlight="<replaceable>picture.png</replaceable>" ] [ select="<replaceable>picture.png</replaceable>" ]
74 [ transparent="<replaceable>color-spec</replaceable>" ] [ force="yes" ]
75 [ autooutline="infer" [ outlinewidth="<replaceable>width</replaceable>" ]
76 [ autoorder="rows" | autoorder="columns" ] ]
77 [ xoffset="<replaceable>x-coord</replaceable>" yoffset="<replaceable>y-coord</replaceable>" ] &gt;
78 &lt;button [ name="<replaceable>name</replaceable>" ] [ x0="<replaceable>x0</replaceable>" ] [ y0="<replaceable>y0</replaceable>" ] [ x1="<replaceable>x1</replaceable>" ]
79 [ y1="<replaceable>y1</replaceable>" ] [ up="<replaceable>name</replaceable>" ] [ down="<replaceable>name</replaceable>" ]
80 [ left="<replaceable>name</replaceable>" ] [ right="<replaceable>name</replaceable>" ] /&gt;
81 &lt;action [ name="<replaceable>name</replaceable>" ] [ x0="<replaceable>x0</replaceable>" ] [ y0="<replaceable>y0</replaceable>" ] [ x1="<replaceable>x1</replaceable>" ]
82 [ y1="<replaceable>y1</replaceable>" ] /&gt;
83 &lt;/spu&gt;
84 &lt;/stream&gt;
85 &lt;/subpictures&gt;
86 </synopsis>
87 <para>
88
89 Each subtitle image is described by an &lt;spu&gt; tag. The start and
90 optional end attributes describe when the subtitle will be displayed
91 on the screen, in "HR:MM:SS.HU". The image attribute describes the
92 main subtitle image, which can either be a PNG or BMP file. If your
93 image is not a full screen image, you can use xoffset and yoffset to
94 move the picture around. In the advent that the author is unable to
95 use a graphics format with an alpha channel, then the transparent
96 attribute can be used to describe which color should become fully
97 transparent. For the valid formats for <replaceable>color-spec</replaceable>,
98 see SPECIFYING COLORS below. If you want to
99 force the display of the subtitle, regardless of whether the user has
100 enabled subtitles or not, you can use the force tag. When you are
101 making menus, the force tag is required.
102
103 </para>
104 <para>
105
106 The remaining attributes and tags are related to menu creation. The
107 highlight attribute shows what all the buttons look like when they are
108 highlighted (i.e. when you are using the arrows in the menu), and the
109 select attribute shows what all the buttons look like when the are
110 selected (i.e. for the 1-2 seconds after you press enter in the menu).
111 If either of these (or the image attribute) are omitted, then spumux
112 creates a blank (totally transparent) image. Obviously at least one
113 tag should be specified.
114
115 </para>
116 <para>
117
118 To aid in button creation, the autooutline attribute instructs spumux
119 to infer where the buttons are located. It does this by attempting to
120 draw rectangles around a composition of the highlight and select
121 images which do not intersect any opaque or semi-opaque pixels. In
122 order to support textual buttons, the attribute outlinewidth allows
123 you to specify the width of the rectangle which is tested. Wider
124 rectangles won't be able to squeeze between the letters. Finally,
125 autoorder describes which way to order the automatically detected
126 buttons, which is important for numerically selected buttons and for
127 mapping buttons to button names or to the implied names.
128
129 </para>
130 <para>
131
132 The button and action tags describe the buttons (visibly selectable
133 objects on the screen) and actions (commands that are executed as soon
134 as the associated key is pressed on the remote). If you are using the
135 autooutline feature, just designing buttons, are happy with the
136 inferred button navigation, and can deal with the simplistic naming
137 system, then you actually do not even need to specify any buttons or
138 actions. Otherwise, read on.
139
140 </para>
141 <para>
142
143 The name attribute is used to give a button or action an easy to refer
144 to name. By default they are numbered sequentially starting with "1".
145 The up, down, left, and right names describe which button or action
146 should be tied to the corresponding key when the current button is
147 highlighted, though if omitted spumux will use a reasonably
148 intelligent algorithm to determine which buttons to move to.
149
150 </para>
151 <para>
152
153 The (x0,y0) coordinates describe the upper left hand corner
154 inclusively, while the (x1,y1) coordinates describe the lower right
155 hand corner EXclusively. The coordinates start at 0,0 for the upper
156 left hand corner. Ideally, the y0 and y1 coordinates should both be
157 even, so the button edges fully empasses two interlaced scanlines,
158 even if there is no data in the extra scanline. Some DVD players will
159 fill in the extra scanline if it is not specified; spumux makes an
160 effort to ensure that will be transparent but there is no guarantee.
161
162 </para>
163 </refsect1>
164 <refsect1><title>Handling text-based subtitles</title>
165 <para>
166
167 Spumux is also able to handle text subtitles, which will be rendered to
168 graphics by spumux. A lot of different text (must be non-graphic) formats
169 are supported (.sub, .srt, .ssa, .smi, .rt , .txt, .aqt, .jss, .js, ass).
170 Spumux will try to determine the format automatically.
171
172 </para>
173 <para>
174
175 If processing text-based subtitles no other streams can be defined, buttons
176 or others need to be processed in another pass with spumux, using another
177 xml file.
178
179 </para>
180 <para>
181
182 Following .xml file shows the available tags and their default settings.
183 Only the textsub tag is mandatory, defaults are used if the specific tag
184 is not specified.
185
186 </para>
187 <synopsis>
188 &lt;subpictures [format="NTSC|PAL"]&gt;
189 &lt;stream&gt;
190 &lt;textsub filename="demo1.srt" characterset="UTF-8"
191 fontsize="28.0" font="arial" fill-color="<replaceable>color-spec</replaceable>"
192 outline-color="<replaceable>color-spec</replaceable>" outline-thickness="3.0"
193 shadow-offset="0, 0" shadow-color="<replaceable>color-spec</replaceable>"
194 horizontal-alignment="left" vertical-alignment="bottom"
195 left-margin="60" right-margin="60"
196 top-margin="20" bottom-margin="30" subtitle-fps="<replaceable>fps</replaceable>"
197 movie-fps="<replaceable>fps</replaceable>"
198 movie-width="720" movie-height="<replaceable>height</replaceable>" aspect="4:3"
199 force="yes"
200 /&gt;
201 &lt;/stream&gt;
202 &lt;/subpictures&gt;
203 </synopsis>
204 <para>
205
206 The textsub tag defines the settings for the text to graphics rendering.
207
208 </para>
209 <para>
210
211 The filename attribute defines the path and name of the input text subtitle
212 file, this is the only attribute that is mandatory.
213
214 </para>
215 <para>
216
217 The characterset attribute defines the characterset to be used, available
218 charactersets can be found at http://www.gnu.org/software/libiconv.
219
220 </para>
221 <para>
222
223 The fontsize attribute defines the size of the font in font units.
224 The font attribute defines the font used. Spumux will match the font name
225 using Fontconfig if available, else it will use it as a filename on linux
226 systems and will look into the windows/fonts and subdirectory spumux of
227 the cygwin/mingw home directory and into the execution directory for windows-based
228 execution for the specified font. Looking for free fonts? One listing is
229 here http://www.microsoft.com/typography/links/links.asp?type=free&amp;part=1
230 (this is only about fonts, not about operating systems).
231
232 </para>
233 <para>
234
235 The fill-color attribute specifies the color to be used for filling the interior
236 of the text, while outline-color specifies the color for the outline border to draw
237 around each character, to set it off from the video background.
238 The outline-thickness attribute specifies the thickness of this outline. For the
239 valid formats for <replaceable>color-spec</replaceable>, see SPECIFYING COLORS below.
240 The default fill color is white and the default outline color is black.
241
242 </para>
243 <para>
244
245 The shadow-offset and shadow-color attributes specify a shadow effect to be applied
246 to the text. The shadow-offset is specified as 2 signed integers, being the horizontal and
247 vertical offset respectively, with positive values being to the right and down. For the
248 valid formats for <replaceable>color-spec</replaceable>, see SPECIFYING COLORS below.
249 The default shadow color is black.
250 </para>
251 <para>
252
253 The horizontal-alignment attribute defines the horizontal alignment of the
254 subtitles. Options are: "left", "right", "center" and "default".
255 The "default" value causes spumux to use the attribute that is in the text
256 subtitle file if the format supports such an attribute.
257
258 </para>
259 <para>
260
261 The vertical-alignment attribute defines the vertical alignment.
262 Options are: "top", "center" and "bottom".
263
264 </para>
265 <para>
266
267 The margin attributes define the minimum blank pixel space between the
268 border of the image and the border of the subtitle lines.
269
270 </para>
271 <para>
272
273 The subtitle-fps is needed for subtitle formats which use frame numbers rather
274 than fractional seconds for specifying subtitle times, while the movie-fps
275 is the frame rate of the movie onto which the subtitles are being multiplexed; if
276 omitted, both of these default to 29.97 for NTSC and 25 for PAL.
277
278 </para>
279 <para>
280
281 Having separate subtitle-fps and movie-fps attributes make it possible for
282 spumux to recalculate the subtitle timing if these are not the same.
283
284 </para>
285 <para>
286
287 The movie-width and movie-height attributes define the maximum size of
288 the subtitle page, these shouldn't be larger than the size of the
289 video frame (720x480 for NTSC, 720x576 for PAL), normally they are the same.
290 Some DVD players prefer subtitle frames that are 2 or 4 pixels smaller in height.
291 If omitted, the default movie width is 720 and the height is 2 pixels less than
292 the video frame height.
293
294 </para>
295 <para>
296
297 The aspect attribute lets you specify whether the video aspect ratio is 16:9 (widescreen)
298 or 4:3. This, together with the video format, is used to adjust the rendering of the
299 text to ensure it appears undistorted.
300
301 </para>
302 <para>
303
304 The force option allows you to force the display of the subtitle,
305 regardless of whether the user has enabled subtitles or not.
306
307 </para>
308 </refsect1>
309 <refsect1><title>Specifying Colors</title>
310
311 <para>
312 Colors for image transparency and text fill and outlines can be specified in a number
313 of ways:
314 </para>
315 <itemizedlist>
316 <listitem><para>As a color name, e.g. "green". You can use most of the color names
317 listed at &lt;http://www.imagemagick.org/script/color.php&gt;.</para></listitem>
318 <listitem><para>As a hexadecimal string preceded by a "#", similar to HTML format,
319 e.g. "#FF8080". The number of digits must be a multiple of 3; the first group specifies
320 the red component, the second green, and the third blue.</para></listitem>
321 <listitem><para>As the name of a color space, followed by one to four component values
322 in parentheses, e.g. "hsv(120, 50%, 90%)".</para></listitem>
323 </itemizedlist>
324
325 <para>Valid color spaces are "gray" (1 component), "graya"
326 (2 components), "hsl" (3 components), "hsla" (4 components), "hsv" (3 components),
327 "hsva" (4 components), "rgb" (3 components) and "rgba" (4 components). Each component can
328 be specified as either a percentage of the maximum value suffixed by "%", or an absolute
329 value in the range 0-360 for hues, 0-255 for everything else. For color space names ending
330 with "a", the last component is the alpha (transparency) value.</para>
331
332 <para>Note that alpha values are meaningless for the "transparent" attribute on the &lt;spu&gt;
333 tag above.</para>
334
335 </refsect1>
336 </refentry>