| 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">< <replaceable>mpeg</replaceable></arg> |
| 28 |
<arg choice="req">> <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 |
<subpictures> |
| 71 |
<stream> |
| 72 |
<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>" ] > |
| 78 |
<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>" ] /> |
| 81 |
<action [ name="<replaceable>name</replaceable>" ] [ x0="<replaceable>x0</replaceable>" ] [ y0="<replaceable>y0</replaceable>" ] [ x1="<replaceable>x1</replaceable>" ] |
| 82 |
[ y1="<replaceable>y1</replaceable>" ] /> |
| 83 |
</spu> |
| 84 |
</stream> |
| 85 |
</subpictures> |
| 86 |
</synopsis> |
| 87 |
<para> |
| 88 |
|
| 89 |
Each subtitle image is described by an <spu> 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 |
<subpictures [format="NTSC|PAL"]> |
| 189 |
<stream> |
| 190 |
<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 |
/> |
| 201 |
</stream> |
| 202 |
</subpictures> |
| 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&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 <http://www.imagemagick.org/script/color.php>.</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 <spu> |
| 333 |
tag above.</para> |
| 334 |
|
| 335 |
</refsect1> |
| 336 |
</refentry> |