srt2vobsub(1)

NAME
srt2vobsub - a textual subtitiles to vobsub conversion tool

SYNOPSIS
srt2vobsub [-v 0|1|2] [-k] [-n name] [-d directory] [-i 0|1] [-l languagecode] [-e encoding] [-E strict|replace] [-S 0|1] [-M msec.] [-X msec.] [-D msec.] [-F 0|1] [-f 24|25|30] [-r resolution] [-m moviefile] [-t font] [-g 0|1] [-s fontsize] [-z maxlinesize] [-w outlinewidth] [-y yoffset] [-B padx,pady] [-c colorspec] [-o colorspec] [-b colorspec] [-j bdsup2subruntime] [-p options-tuple] [-V 4|5] subtitlesfile

DESCRIPTION

srt2vobsub is a Python3 script that generates .idx/.sub vobsub subtitles files from a given textual subtitles file.

The script uses ffmpeg to convert non-srt subtitle files into the srt format (if necessary), Chris Down's srt module to parse the srt file, mediainfo to detect the video properties of a given movie file (if requested), Python-Wand to convert the captions into images and finally bdsup2sub to generate the vobsub files from these images.

The resulting subtitle stream is not strictly standards compliant. Depending on the playback software or the hardware player in use your mileage may vary.

OPTIONS

-v, --verbose
    Set the verbosity level.
    If set to 0, nothing will be written to stdout (some messages may be printed to stderr, though).
    If set to 1 (default) some messages will be printed to stdout.
    If set to 2, more messages will be written to stdout.

-k, --keeptemp
    Keep the temporary files generated while processing the subtitles.
    This may be useful if the resulting vobsub stream does not work as expected.
    The user can then inspect the image files and the xml content for possible problems. The name of the temporary directory that was used will be printed to stderr.
    It is the user's responsibility to remove the temporary files afterwards.

-n, --name
    Base name to use for the .idx/.sub output files.
    If no name is given, the base name of the original subtitles file will be used. If the file(s) already exist, backup copies will be made with the suffix "_bak". If the backup files already exist, they will be removed.

-d, --directory
    Target directory to use for the .idx/.sub output files.
    If no directory is given, the directory of the original subtitles file will be used.

-i, --remove-hi
    Determines if the script should try to remove captions for the hearing impaired. This is not perfect, it will just remove any text from the captions that is enclosed in [brackets] and/or (parentheses). Set the value to "b" to remove caption text in brackets, to "p" to remove text in parentheses or to "bp" to remove both.
    If set to none (the default), no such attempt will be undertaken.

-h, --help
    Show command line option help.

-l, --lang
    Set the language code for the subtitles.
    This must be a 2-character language code as accepted by bdsup2sub. See the file langcodes.txt for a list of supported language codes.
    The default value is "ja" (Japanese).

-e, --encoding
    Encoding of the original subtitles file. Must be either a valid encoding identifier or auto.
    If set to auto (the default), the script will try to guess the input file's encoding. This is not perfect and may fail with some input files.
    If the correct encoding is not given, some characters may be displayed incorrectly or the program might even refuse to process the file at all. See https://docs.python.org/3/library/codecs.html#standard-encodings for a complete list of supported encodings.

-E, --encodingerrors
    Defines how to handle errors if the given encoding does not match the encoding of the subtitles file.
    If set to "strict" (the default) errors will cause the program to stop with an error message.
    If set to "replace", characters that cannot be decoded will be replaced with a question mark.

-S, --savesrt
    srt2vobsub does internally try to fix a number of common problems that may be encountered in srt files, as empty lines within a caption or end times of subtitles that are earlier than the start time etc. If requested it also removes captions for the hearing impaired.
    If -S is set to 1, an UTF-8 encoded srt file that includes these corrections will be saved as "NAME_proc.srt" in the target directory. If this file already exists, a backup copy will be created with the filename suffix "_bak". If the backup already exists, it will be overridden. The default value is 0.

-F, --fixtimes
    If set to 1 (default), srt2vobsub will attempt to fix invalid timecodes in the subtitles file, i.e. end times that are earlier than start times and end times that are later than the start time of the next caption. It can also try to fix technically legal but unreasonable short or long display times of individual captions, according to the values given to the -M, -X and -D options (see below).
    If set to 0 the timings will not be corrected.
    It should be noted that bdsup2sub seems to handle broken timings quite gracefully: if end < start, it will display the caption anyway for about 5 seconds (which seems to be hardcoded) and if captions overlap, the earlier caption will be cut short just before the next caption shows. So generally it does not seem necessary to fix broken timings to create usable vobsub content.

-M, --mindisplaytime
    Minimum time to display a caption (in msec). This has no effect if -F is set to 0. Must be an integer value from 0-2000. The default value is 500.
    If the display time of a caption is smaller than the given value, its duration will be extended to this value if possible without interfering with the start time of the next subtitle.

-X, --maxdisplaytime
    Maximum time to display a caption (in msec). This has no effect if -F is set to 0. Must be an integer value from 3000-20000. The default value is 8000.
    If the display time of a caption is greater than the given value, it will be reduced to this value.

-D, --defaultdisplaytime
    Default time in ms to display a caption whose end time was originally before its start time, if possible without interfering with the start time of the next subtitle. This has no effect if -F is set to 0. Must be an integer value from 500-5000. The default value is 2500.

-f, --framerate
    Framerate of the original subtitles file.
    This must be one of 24, 25 or 30.
    Normally the framerate can be safely ignored, since by default it is only used to convert the subtitle's milliseconds into frame numbers, which may cause the caption's timings to be shifted only by an unnoticable number of ms.
    It may be important, though, if you want to use bdsup2sub to convert the framerate of the original subtitles file.
    The default is 24.

-r, --resolution
    Video resolution to use for the vobsub stream.
    bdsup2sub only supports five resolutions: "1080p" (1920x1080), "720p" (1280x720), "1440x1080", "pal" (720x576) and "ntsc" (720x480).
    If the video's resolution differs from these, you can try to use one of the supported resolutions, depending on the video's aspect ratio. For example if the video resolution is 640x360, "720p" or "1080p" can be used. It depends on the player in use, if the resulting subtitles will be displayed correctly.
    The default is "1080p"

-m, --movie
    Video file to detect resolution and framerate from.
    If given, any values given to the -f and -r options will be ignored. The script will the try to detect the framerate and resolution using mediainfo and set the target resolution and framerate to sensible values.
    If this fails for some reason, the script will stop with an error message. In this case you can still try to set the options manually instead.

-t, --font
    Specify a font to use.
    Please note, Python-Wand requires the full path to the font file. If a font name is given it must be the exact base name of the corresponding font file; srt2vobsub will try to detect the corresponding font file using the fc-list command.
    If the given font can not be found, the script will first try to use "DejaVuSans" as a fallback, if this fails, too, the script will stop with an error.
    The default is "DejaVuSans".

-g, --antialiasing
    If set to 1, the caption images will be rendered using font antialiasing. The default value is 0.

-s, --fontsize
    Set the fontsize to use.
    Must be either a positive integer value which will be used as point size for the font or a positive floating point number from 1.0-10.0 which will be used to calculate the font's point size as percentage of the screen height.
    The default value is 5.0, meaning that the font size in points will be screenheightx0.05.

-z, --maxlinesize
    Maximum width of a caption in percent of the screen width. If the width of the caption string would exceed this width, a line break will automatically be inserted. The value must be an integer from 35-100.
    The default value is 60.

-w, --outlinewidth
    Width of the font outline in pixels. Must be an integer value from 0-10. The default value is 1.

-y, --yoffset
    Distance between the bottom of the screen and the caption in percent of the screen height. Must be an integer value from 0-100. The default is 5.

-B, --boxpadding
    Either the string "auto" or a comma-separated list of two positive integer values defining the x- and y-padding between the text and the text's bounding box (in pixels). These will be taken into account when calculating the coordinates of the caption text even if the box is not visible.
    Please note that the second (y-) value will affect the vertical offset between the text lines of multi-line captions. The extra padding between lines of text will be pady+1 px. There will also be a small amount of padding even if either value is set to 0 and the text does not necessarily be exactly centered within the box. This is due to the internal mechanics of libmagickwand and as it seems can not be avoided.
    The default value is auto.

-c, --fillcolor
    Fill color to use for the text. This (as well as all other color values) may be either a color name or a 6-digit hex color descriptor of the form #RRGGBB. If the color is not known to Wand, it will fall back to some default color.
    Please note that colors are generally tricky with vobsub; there is no guarantee that the colors in the resulting captions will look as requested.
    The default value is "#ffffff" (white).

-o, --outlinecolor
    Color to use for the text outline. The default is "#000000" (black).

-b, --boxcolor
    Color to use for the bounding box. Set this to "none" if no bounding box should be drawn. The default is "none".

-j, --bdsup2subruntime
    Path to the java runtime file of bdsup2sub. This option is present because a bug in the bdsup2sub caller script in the package coming from deb-multimedia stops the script from working when simply calling "bdsup2sub".
    The default value is "/usr/share/bdsup2sub/BDSup2Sub.jar".

-P, --bdsup2subversion
    Must be either auto, 4 or 5, depending on the version of bdsup2sub in use. This option is present, because both versions have a completely different command line syntax.
    The default is auto, which means that the script will try to auto-detect the bdsup2sub version.

-p, --bdsup2subopts
    Additional command line options that will be passed to bdsup2sub.
    This option is rather tricky:
    the value must be a string enclosed in quotation marks that evaluates into a proper python tuple. To achieve this the following conditions must be met:
    * the contents of the string must be enclosed in parentheses.
    * the arguments must be strings enclosed in single quotes (i.e. apostrophes), separated by commas.
    * if only a single argument is given, it must be followed by a comma.
    For example, to set the minimum display time of a subtitle in bdsup2sup v.4 to 1000 ms you could use:
    -p "('/tmin:1000',)"
    To do the same with v.5 you would use:
    -p "('-m', '1000')"
    Please note that the language (option 'lang:' in v.4 resp. '-l' in v.5) is always passed on by srt2vobsub and must not be given here again, as well the
    The default value is "()", which means that no options are given.

CONFIGURATION FILE

The default values of most command line options can be changed in the configuration file ~/.config/srt2vobsub/defaults.conf.
See the sample configuration file shipped with srt2vobsub for the available options and OPTIONS above for possible values for each option.

VIDEO RESOLUTION

Since bdsup2sub supports only five different resolutions (1080p, 720p, 1440x1080, pal=720x576 and ntsc=720x480) finding the best target resolution may be tricky for a given video resolution that is not among these.
Here I never got anywhere using "pal" or "ntsc", even when this exactly matches the video resolution. The best bet seems to be for any resolution other than 1280x720 to use 1080p for any video with an aspect ratio of 16:9 and 1440x1080 if the original aspect is 4:3.
For any other video aspect ratio either of these can be used, but the quality of the resulting subtitles may vary depending on the target player. The font may appear horizontally condensed or stretched, so an appropriately "broad" or "slender" font might need to be chosen. With some players the yoffset value may need to be set to a rather high value (like 30 percent or so) so that the player will not move the caption outside of the visible area. Anyway, the captions need not necessarily look alike with different players and some players might refuse to display them at all.

COLORS

bdsup2sub seems to usually do a good job creating a suitable color pallette if only two colors are in use. However, if you want to use three different colors for fill, outline and bounding box things may become rather tricky and the result might not look as expected. Some amount of experimenting may be necessary to achieve satisfying results, and maybe even a custom color pallette needs be created and passed on to bdsup2sub. Maybe it is even not possible at all.

EXAMPLES

Generate vobsub files foo.idx and foo.sub with default parameters:

srt2vobsub foo.srt

Retrieve video properties from movie and generate vobsub files with matching name from an advanced substation alpha file:

srt2vobsub -m "Life of Brian.mp4" -n "Life of Brian" foo.ass

Create subtitles with 1080x720 px. resolution and save corrected subtitles file to subs_proc.srt :

srt2vobsub -r 720p -S 1 subs.srt

SOFTWARE REQUIREMENTS

srt2vobsub requires Python3, Python-Chardet to detect the input file encoding if requested and Wand a Python implementation of libmagickwand.
For the user's convenience Chris Down's srt module v. 1.11.0 comes already packaged with srt2vobsub. The original package can be found at:
https://pypi.org/project/srt/

External programs that are used include fc-list to detect the font file for a given font name, ffmpeg to convert non-srt textual subtitle files to temporary .srt files, mediainfo to detect video file properties and bdsup2sub to generate the vobsub files.

BUGS

If you encounter a bug, please report at the sourceforge bugtracker at

https://sourceforge.net/p/srt2vobsub/tickets/

or mailto: <klappnase@users.sf.net>

AUTHOR
Copyright © 2020 Michael Lange <klappnase@users.sf.net>