BDSup2Sub

A tool to convert and tweak bitmap based subtitle streams

Version 4.0.0  released 14.12.2009

BDSup2Sub is a tool I wrote initially to convert captions demuxed from a Blu-Ray transport stream (M2TS) into the DVD VobSub format (SUB/IDX) used by many DVD authoring tools - hence the name. Many more features were added over time as was support for other formats. So in the meantime the name seems a little inappropriate. In a nutshell, it's a subtitle conversion tool for image based stream formats with scaling capabilities and some other nice features.
A complete revision history can be found at the end of this document.

Supported Formats

What it can do

What it can't do

BDSup2Sub only supports image based subtitle streams. It doesn't (and probably won't ever) support  text based formats as SRT or SSA. Note that to convert image based subtitles to text based subtitles would need an OCR (Optical Character Recognition) approach which is beyond the idea of converting between image based formats. There are other tools like SubRip and SupRip to convert image based subtitles to SRT. For the other way round (SRT to BD-SUP), you may have a look here.
While importing HD-DVD SUPs is supported, BDSup2Sub can't export this format currently - and with the commercial death of HD-DVD I think adding this feature would be a waste of time. 

Author

0xdeadbeef

Home

Official thread on Doom9.org

Feedback

Please post comments and bug reports to the above thread. Feedback is welcome - especially from the authors of SubRip, SupRip, SubtitleCreator or TsMuxer to discuss compatibility issues. To report problems with a subtitle stream, please either post the stream (if it is compliant with the forum rules) or upload it to a "one click hoster" and send me a PM with the link. And don't forget a detailed error description.

Credits

I dug through hundreds of postings, mainly on Doom9 (started by Pelican9), several source codes (especially FFmpeg) and all the documents I could find. Sam Hocevar's DVD subtitle documentation is especially worth noting. Also the information on exar.ch (while far from being complete) helped me a lot to understand the HD-DVD SUP format. Still, I rifled through hexdumps for hours and hours and hours to find out the details. Really, you can't imagine.
BDSup2Sub uses a palette quantizer (octree) routine by Jerry Huxtable which was slightly adapted to the needs of BDSup2Sub (e.g. extended to include alpha as 4th component).
BDSup2Sub uses the PNG Encoder by J. David Eisenberg to have better control over the written palettes of exported PNG images (in BDN XML mode). I just added the missing code to write the tRNS segment for transparency.
The scaling algorithm is partly based on the Java image scaling library  by Morten Nobel-Joergensen which again is based on the "Java Image Util".
See Source Code and Disclaimer for license details.

Known issues

Reading/writing data from/to transport streams is quite a hassle since the formats are usually not well documented  and you will always stumble over a stream that either contains authoring errors or uses features so uncommon that they are not documented anywhere. Indeed, most of the time it's impossible to tell if some weird stream is only on the edge of what is allowed or simply faulty. So often enough, programs that read or write transport streams will only support a certain amount of commonly used (and known) sub-features.
Therefore it's likely that BDSup2Sub will stumble over the streams created by other programs or other programs will have problems reading the streams created by BDSup2Sub. It's generally hard to tell who's fault it is, but here's a list of issues that I'm aware of:
I tried to catch the most common problems (e.g. out of bounds access due to corrupt size information or wrong RLE info), yet it's kinda impossible to catch every possible fault in every possible stream. So don't be surprised if BDSUP2SUB shuts down with or without an error message. I recommend to start it via the command line in this case to see every exception thrown. E.g. a problem of the Java Runtime can't be caught  by  the application and is therefore only printed to the console.

Using the GUI

The main window is split into five Sections:
Control Panel
Source Panel
Target Panel
Console Panel Preview Panel


BDSup2Sub uses a straightforward GUI design. Most actions are triggered by menu items.
Menu structure:

Editing text fields

BDSup2Sub supports input checking while typing in all text input fields (including editable combo boxes):

Using Keyboard shortcuts (Hotkeys/Mnemonics)

There are keyboard shortcuts for most menu items, buttons and checkboxes. Note that the support for these hotkeys depends on your Operating System and its user interface settings. E.g. on Windows, the hotkeys are displayed only if you press the "Alt" key by default. There's a global setting to hide the hotkeys under "Display Properties/Appearance/Effects" which defined whether the hotkeys are displayed or hidden by default in all applications. Some programs as Firefox seem to ignore this setting, the Java Runtime Environment (and thus BDSup2Sub) doesn't.
Exception for the rule: until I come up with a more convenient solution, Alt+Left Cursor and Alt+Right cursor move to previous or next subtitle in the edit and move dialogs (without saving). On Linux and Mac OS, the accelerator key may differ or the hotkeys may not work at all. Sorry, I can't test this.

Zooming in and out

In case you didn't notice: by clicking left/right in the source and target panels, you can zoom in and out to view details of the current sub picture. This is especially useful for finding the correct alpha/luminance thresholds in SUB/IDX (or SUP/IFO) mode.

Color Palettes

The subtitle data on a Blu-Ray consists of run length encoded images up to 1920x1080 pixels with a color/alpha palette of up to 256 entries (where each undefined entry and the 256th entry are completely transparent by definition). Each single subpicture frame can have a separate palette. The subpicture data on HD-DVD is similar, the main difference is that the palette for each frame has always 256 entries.
The subpicture data on a DVD consists of run length encoded images up to 720x576 (PAL) or 720x480 (NTSC) pixels, where each image can use up to 4 colors from a common palette consisting of 16 colors. This global palette is defined in the IFO files of a DVD. For SUP/IFO streams, this info is read from an IFO file was well; for subtitles in SUB/IDX format, the information is stored in the IDX file.
All bitmap based subtitle formats are able to define transparency in a way. For DVD based subtitles, each of the colors per frame can have a transparency between 0..15. The HD formats can define an alpha value between 0..255 for each palette entry. Transparency is usually used for a transparent background, but it can be also used for fading. BDSup2Sub tries to detect fading and remove it to be able to display and convert each subtitle.

Palette Modes

So to convert from SUP (BD/HD-DVD) to SUB/IDX (or SUP/IFO), not only the pictures and display offsets have to be scaled, but also the color/alpha information has to be reduced. This is the reason why only "create new" palette mode is available when converting a 256 color format like BD-SUP to a DVD format like SUB/IDX.

In "create palette" mode for SUB/IDX (or SUP/IFO) output, BDSup2Sub uses the following approach for each subpicture frame:
  1. the dominant color in the original picture is identified ((non-)transparency and luminance are used as weight factors)
  2. the dominant color is matched with the default primary colors in the global palette (white, red, green, blue, yellow, cyan, magenta)
    The closest match is chosen as main color. A darker tone of the same color is chosen as 2nd color. The two other colors are always black and a transparent color.
  3. the subpicture is downsized to either PAL or NTSC, depending on the setting of "Output Format"
    Scaling up/down  is done with a selectable scaling filter. However, only transparency (alpha) and luminance are considered: if the mean value of the alpha channel is below "Alpha Threshold" ,  the target pixel is considered to be transparent (palette entry 0). Else it is set to either the primary color (palette entry 1), the darker primary color (palette entry) or black (palette entry 3) depending on whether the pixels's luminance is above/below "Hi/Med Threshold" or "Med/Low Threshold".
    Note that the luminance thresholds are automatically detected (when loading a SUP), while the alpha threshold is set to a default value.

In SUP or BDN XML export mode, three different palette creation modes can be selected when scaling SUPs: "keep existing" doesn't change the palette, but uses the nearest existing color for each scaled pixel. This leads usually to good results, but if the palette lacks alpha/brightness/color gradations, the result may be suboptimal. The mode "create new" creates a new palette for each caption and "dithered" creates a new palette and applies a Floyd-Steinberg dithering matrix. This last approach is the slowest, but usually there is no visual difference to "create new". The default setting is "create new".

In VobSub or SUP/IFO export mode, the palette creation can be only changed if the imported caption stream was a VobSub or SUP/IFO as well. Then you may choose to keep the existing (i.e. imported) palette. In any other case, the palette has to be created anyway so the option is grayed out.

Interpreting the SUP palette

BDSup2Sub assumes that the palette entries in SUP streams (BD as well as HD-DVD) are stored as Y, Cr, Cb (three bytes in this order). I can't validate this for HD-DVDs, but for BDs, the resulting colors displayed in BDSup2Sub match exactly what my PS3 displays. I'm aware though that some other programs like SupRip and MPC-HC caption renderers seems to assume a different color order than BDSup2Sub or the PS3 (Y, Cb, Cr instead of Y, Cr, Cb). This means of course that they will display colors differently (e.g. Cyan becomes Yellow and vice versa).
While I'm pretty sure that BDSup2Sub uses the correct order, just for the case that the byte order Y, Cb, Cr is needed instead, there's an an menu item "Settings->Swap Cr/Cb" to swap the Cr and Cb components when reading a SUP. When exporting a SUP with the swap option enabled, this also means that the Cr/Cb components are swapped then compared to those in the imported SUP. So while BDSup2Sub shows the colors like e.g. SupRip for the imported SUP then, SupRip won't show the same colors for the exported SUP. Note that with the swap option disabled, the exported SUP has exactly the same palette as the imported SUP.
When exporting SUB/IDX though, the colors displayed by BDSup2Sub do matter, as the color matching is done in RGB space. Also the palette colors written to the IDX file are stored as RGB values. As long as other tools respect this definition, the colors should appear as they are displayed by BDSup2Sub.

Editing the "default" DVD palette (for "create new" palette mode)

To allow a at least a minimum of anti-aliasing during scaling down/up with SUB/IDX (or SUP/IFO) as output format, the 16 color palette used by BDSup2Sup in "create palette" mode has one light and one dark tone for each predefined color.  E.g. there is a dark blue and a light blue. White is a special case, since it's the most common subtitle color: in addition to white, there is also a light and a dark gray. So for lighter subtitles, the conversion can select white and dark gray, while it can select light gray and dark gray for darker subtitles.
If you're unhappy with the default palette, you can edit the default palette used for conversion to SUB/IDX via the according menu item "Edit default DVD palette" in the "Preferences" menu. Just keep in mind that if you edit a light color, you should also change the dark color accordingly (and vice versa). Also "white, "light gray" and "dark gray" must be different tones of the same color or else you'll get erratic results.
Also note that when you use VobSub or SUP/IFO as import and export format, you may as well choose to keep the existing palette. Then BDSup2Sub's default  palette is completely ignored. Note that when you're scaling, this might lead to worse results than the "create new" palette mode if no intermediate color is present (in the frame palette) for antialiasing.

Editing the "imported" DVD palette

When the import format is either VobSub or SUP/IFO, the menu item ""Edit imported DVD palette" is enabled, which let's you edit the 16 color palette imported from the IDX or IFO. You can change any of the 16 colors as you wish. Just keep in mind that each caption is still limited to a 4 color frame palette which can be edited via a separate menu item ("Edit DVD Frame Palette" described in the next chapter).
Note that editing the imported palette and editing the frame palette/alpha values are the only edit features in BDSup2Sub that actually change the source image. Though this might seem a little inconsistent (in that all other edit features only influence the target subtitle), I decided that these features make more sense this way since else they would only work when converting from SUB/IDX to SUP/IFO or vice versa and using the "keep palette" mode.

Editing the Frame Palette and Alpha values (DVD input only)

As already mentioned, DVD subtitle formats (SUB/IDX or SUP/IFO) use a 4 color palette and 4 alpha values for each frame. All the values can vary from 0 to 15, where the number means the palette entry from the global 16 color palette for the palette while it defines the absolute transparency for the alpha values: 0 is completely transparent, 15 is completely opaque. As editing the imported DVD palette, editing the frame palette/alpha is only available when the import format is either VobSub to SUP/IFO and it also influences the source image displayed in the upper half of the main screen.
Note that apart from changing the palette/alpha values for the current caption, you can also apply the same setting to all subtitles ("Set All"). This is true for restoring the default values (as defined in the original stream): you can either restore only the values for the current caption ("Reset") or for the whole stream ("Reset All").

Automatic fixing of invisible subtitles due to zero alpha frame palette (DVD input only)

In some DVD subtitle streams (SUB/IDX and SUP/IFO) single subtitles are invisible since all four alpha values are zero (due to an authoring fault). In some cases, this hides a useful subtitle, in some cases it hides a garbage bitmap. Anyway, apart from manually setting the according alpha values via the "Edit DVD Frame Palette" menu item, BDSup2Sub can also try to fix this problem automatically by keeping the last non-zero frame palette (i.e. the one from the previous subtitle). This feature can be switched on/off either via the command line (/fixinv) or with the menu item "Fix invisible frames" from the settings menu.
Note that changing this setting in the menu has no influence on the currently loaded subtitle since the alpha fixing already took place then. You need to reload the current subtitle file to see an effect.

Other concepts and features

Output Format

While the output format is indeed a conversion option, currently it's not located in the conversion dialog but in the control panel of the main window. The main reason for this is to keep those options in the control panel which directly affect the bitmap in the target panel.
There are four output modes available:
Depending on the selected output format, the bitmap displayed in the target panel will be updated (4 color palette in DVD modes vs. 256 color palette in BD modes).

Output Resolution

BDSup2Sub supports only default output resolutions:

Forced subtitles

In BD-SUP, VobSub and SUP/IFO streams, individual subtitles can be marked as "forced" which tells the player to display them even if subtitles are switched off. This means that forced subtitles and normal subtitles can be stored in the same stream. If forced subtitle frames are detected in an imported stream (and only then), you can choose to export only the forced subtitles to SUB/IDX or SUP by checking the according checkbox in the export dialog (or by using the "/forced" parameter on the command line).

Source and target frame rate

When reading a BD-SUP, BDSup2Sub tries to read the source frame rate from the stream. Keep in mind that it might be wrong or inaccurate! For HD-DVD SUPs, there is no frame rate information, so always 24p is assumed. However the source frame rate is only important if you change the frame rate during export. In this case, it's used together with the target frame rate to calculate the factor used to manipulate the time stamps. Note that to convert a movie from NTSC (3:2 pulldown) to PAL, you would still need to select 24p as source and not NTSC or 30p because the source timing is natively 24p and this is the only thing that matters for the conversion.
The target frame rate is always important, as it's always used to synchronize the start/end times with the frame rate. For best results, always select the correct target frame rate. Note that the default setting only depends on the resolution (PAL -> 25p, NTSC -> 30p, HD -> 24p).

Filter Modes

You can select a scaling filter in the according combo box in the main view. The fastest algorithm is Bilinear, the slowest modes are Lanczos3 and Mitchell. For SUP/XML export with a 256 color palette, Mitchell or Lanczos3 are usually the best choice. For VobSub (or SUP/IFO) with only 4 colors, this is harder to predict. Just play around with the filters, alpha threshold and luminance thresholds to find the best quality.

Free Scaling

BDSup2Sub allows to scale captions in X and Y direction independently of the screen resolution. This feature can be used to e.g. enlarge the captions to make them more readable or to shrink them a little bit to make them fit into the cinemascope bars. Simply enter any value between 0.5 and 2.0 for scaling in X and Y direction. Indeed, for conversion from BD to DVD it's often a good idea to scale the subtitles by a factor of e.g. 1.2 to make them more readable. To compensate for the slightly increased size, you may want to move the captions with the "move all" feature then.

Fixing of too short frames

Some streams contains single subtitles which are too short to read. It's possible to let BDSup2Sub automatically fix these subtitles. There's command line option ("/tmin") as well as an option in the conversion dialog. Every time that a caption is shorter than the given time (in milliseconds), BDSup2Sub will try to increase the display time to the given time. Note however that this is not possible if the next subtitle starts before that. In this case, the end time of the subtitle in question will be set to the start time of the following frame.

Merging frames

For some reason (probably due to a buggy authoring tool), there are quite a few BD subtitle streams which contain duplicated subtitle frames. I.e. the very same frame is repeated two, three or even more times with no or very short gaps between it. BDSup2Sub automatically tries to fix this issue, yet sometimes this behavior might not be wanted. Therefore it's possible to configure this feature via the command line option "/tmerge:<t>". The default value is 200ms, which means that two identical subtitles with a gap smaller or equal to 200ms will be merged to one subtitle. Setting the time to 0ms ("/tmerge:0") effectively disables the feature.

Language info

Some subtitle streams contain information about the language of the stream. E.g. SUB/IDX, SUP/IFO and XML do, SUP BD and SUP HD don't. For those formats that don't support language information, BDSup2Sub tries to guess the correct language from the file name. If a file name for a BD-SUP or SUP-HD input stream contains a valid English language name (e.g. "german" or "french"), this will be used as default. Note that this can fail if the file name contains language names for other reason (e.g. movie titles like "Greek Wedding" or "Johnny English"). Therefore, there's always the possibility to edit the language in the export dialog. Then again, the language info is only needed if the export format supports it. If you export to BD-SUP, there's no need to define it and the option in the export dialog is grayed out.

Export Dialog

When a stream is saved, the export dialog pops up. It contains the following items:

Conversion Dialog

The conversion dialog pops up after a subtitle stream was loaded. You can also open it via the "Settings" menu.
It shows the following items:

Edit Dialog

Editing time stamps and position

This dialog let's you edit the subtitle data of a single frame. Like position, times and forced flag.
You can access this dialog via the Edit menu or by left clicking in the preview panel (lower right) of the main window.
 
Control Panel
Preview Panel
Times PanelPosition Panel
Flags PanelPatches Panel
Buttons Panel

Move/Crop Dialog

Moving all captions inside/outside bounds

BDSup2Sub 2.7 introduced a feature to move all captions outside/inside certain bounds. The idea is to either move the captions outside the visible cinemascope picture (to not cover parts of the picture) or to move them completely inside the picture to e.g. use a 21:9 screen without losing the captions. The implemented algorithm is pretty simple: captions that are completely inside the upper half of the screen are defined as "upper" captions, while those completely inside the lower half of the screen are defined as "lower" captions. Captions that begin in the upper half and end in the lower half are not moved at all.
When moving captions "outside", the upper captions are simply moved to the top of the screen plus a given offset in pixels. The lower captions are moved to bottom of the screen, where again the pixel offset between the bottom of the caption and the bottom of the screen is kept.
When moving captions "inside", it's important to define the correct target picture aspect ratio. E.g. if you want to move the captions inside a 21:9 picture, you need to select a aspect ratio 2.33 (or push the button labeled "21:9"). Now the upper captions are positioned offset pixels below the upper border of the 21:9 screen and the lower captions are positioned "Y offset" pixels above the lower border of the 21:9 screen.
Indeed, "inside" and "outside" work pretty much exactly the same apart from the fact that when moving "inside", the screen height is virtually decreased by the given factor.

Moving all captions horizontally

Since BDSup2Sub 3.9.6  it's also possible to move (all) captions horizontally. You can either move to the left, to the right or center the captions to the middle of the screen,. When moving to the left or to the right, BDSup2Sub will try to keep a minimum distance of "X offset" to the left or right screen border. However, when the caption is too wide, the actual distance to the border might be smaller or even 0.

Cropping (of screen size)

Implemented due to user request. If a crop offset is defined, the exported Y coordinates will be reduced by the cropping offset. Usually, this should be used in combination with moving captions inside bounds - that's why it's located there in the GUI. Anyway, the crop offset is also the minimum Y coordinate for exported captions. E.g. if the crop offset is 100, all captions with a higher Y coordinate will be moved up by 100 pixels and captions with Y <= crop offset will have an Y coordinate of 0 after the export. The crop offset will be displayed as red line in all preview windows. It can be reset to 0 (without moving captions) by using the according menu command (reset crop offset).
Since 3.0.1, the crop offset is assumed to be symmetrical. Hence two red lines are displayed and also the maximum Y coordinate is reduced to fit into the cropped screen. Now also the screen size in exported IDX or SUP files is reduced by 2*Crop Offset Y. E.g. if the target resolution is 1080p without cropping and you select a crop offset of 100, the resulting screen size is 1920*880.

Automatic Cropping (of caption images)

In some subtitle streams the images that contain the captions are much larger than it would be necessary. Indeed, in some cases, the image is as large as the whole screen area (e.g. 720x576 for PAL). While this doesn't really matter when just displaying the stream, it makes certain features of BDSup2Sub unusable (e.g. moving captions).  Since I saw this only happen in VobSubs, SUP/IFO and BDN XMLs, BDSup2Sub applies automatic cropping for these input formats. This means that BDSup2Sub crops the first/last lines/columns of each image that don't contain any opaque pixels resulting in an image that contains only the subtitle but no empty border.
Unfortunately, probably due to wrong RGB/YCBCr conversion in certain tools, the transparent color is not fully transparent (i.e. alpha = 0) in some streams, but the alpha value is just very small (e.g. alpha = 7). To work around this, BDSup2Sub defines an "alpha cropping threshold": if  a pixel's alpha value is smaller than this threshold, it will be considered invisible. The default value for this threshold is 14, but it can be set (only) via the CLI option "/acrop". Note that setting "/acrop" to 0 disables automatic cropping.

It's worth to mention that the alpha cropping threshold is also used to decide whether to patch the colors of transparent pixels. Again, when displaying a subtitle stream, it doesn't matter if a fully transparent pixel is yellow or black. For scaling this matters though, as all 4 components (alpha, r ,g ,b) are used to determine a new color/alpha value. Now if all transparent pixels are yellow instead of black, the pixels at the outer border of each character will  get a yellow tint. To avoid this effect, BDSup2Sub patches all colors with an alpha value smaller than the alpha cropping  threshold to be (transparent) black. Note that if you disable automatic cropping by setting the alpha cropping threshold to 0, this also disables palette patching and might lead to a color tint when scaling.

Details on supported formats

Sony BDN XML format

This format consists of an XML file containing all the information but the caption graphics and a number of PNG image files (one for each caption).
The XML file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<BDN Version="0.93" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BD-03-006-0093b BDN File Format.xsd">
  <Description>
    <Name Title="BDN Example" Content=""/>
    <Language Code="eng"/>
    <Format VideoFormat="720p" FrameRate="23.976" DropFrame="False"/>
    <Events Type="Graphic" FirstEventInTC="00:00:00:00" LastEventOutTC="02:26:38:18" NumberofEvents="22"/>
  </Description>
  <Events>
    <Event InTC="00:00:00:00" OutTC="00:00:05:00" Forced="False">
      <Graphic Width="1" Height="1" X="0" Y="0">subtitles_0001.png</Graphic>
    </Event>
    ...
    <Event InTC="02:26:35:12" OutTC="02:26:38:18" Forced="False">
      <Graphic Width="601" Height="88" X="343" Y="511">subtitles_0022.png</Graphic>
    </Event>
  </Events>
</BDN>

Palettized or 24bit ARGB images are supported for import - the latter will be converted to a 256 color palette automatically. As a matter of fact, the BDN implementation of BDSup2Sub is pretty unrestricted regarding the image formats for import. Apart from PNG, also e.g. BMP, JPG or GIF files should work. Indeed every format supported by Java's ImageIO library will work.
Note that BDSup2Sub will only export 8bit palettized PNGs with transparency (via tRNS tag) for maximum compatibility with Sonic Scenarist HDMV. Unfortunately, only a few (free) graphic programs support this format correctly. Paint.NET however seems to work just fine. So via BDN SUP export/import, it's even possible to alter any caption beyond the built-in possibilities of BDSup2Sub.

Note: although the BDN XML looks pretty straight forward and clean, the timing information in this format is a little weird for unknown reasons. Indeed the timings are always based on an integer frame rate. E.g. in the above example, while the frame rate is 23.976 Hz (24p), the time codes are related to a 24Hz Signal.
E.g. for the end time this means:
02:26:38:18 (time code in XML)
2 hours = 2*60*60 seconds = 7200s
26 minutes = 26*60 seconds = 1560s
38 seconds = 38s
18 frames = 18/24 s = 750ms
In sum this equals 8798750 ms.
Now since the given frame rate is really 23.976Hz, this value is multiplied by 1.001
This equals 8807548.75ms
This equals 2 hours, 26 minutes, 47 seconds and 549ms
2:26:47.549 (real time code displayed in BDSup2Sub)

Keep this in mind when editing the XML manually. It's weird, and believe me: I would have defined it in a more sensible way, but that's unfortunately how it works.

VobSub IDX file

There are several keywords in the IDX file that some tools may use and other don't. Here's a list of the keywords and what BDSup2Sub makes of them:
keyword example remark
size size: 720x576 screen size: mandatory
org org: 10, 10 origin: x,y position of upper left corner in pixels. Optional.
scale scale: 104%, 164% scaling factors for image: Ignored
(use conversion dialog settings or CLI options instead)
alpha alpha: 0% global alpha blending factor: Ignored.
smooth smooth: OFF apply smoothing algorithm: Ignored.
fadein/out fadein/out: 50, 50 create fade in/out (times in ms): Ignored.
align align: OFF at LEFT TOP force caption placement: Ignored.
time offset time offset: 0 Global delay in in ms or hh:mm:ss:ms: Optional
forced subs forced subs: OFF Show only forced captions: Ignored.
(use export dialog setting or CLI options instead)
palette palette: 000000, 141207, [...], bdab4f 16 color DVD subtitle palette: mandatory
custom colors custom colors: OFF, tridx: 1111, colors: 000000, [...], bdab4f Global palette/alpha setting: Ignored.
langidx langidx: 7 Active language index: mandatory
id, index id: en, index: 7 Language ID and caption index: mandatory
(at least one index in the file must fit langidx)
timestamp, filepos timestamp: 00:01:47:520, filepos: 000000000 Timestamp and file offset of one caption: mandatory

Regarding the language index: there are some tools that store multiple subtitle streams inside one SUB/IDX file (e.g. for different language). In this case, the "id, index" keyword does exist several times, where each appearance has a different index and a separate section of timestamps,filepos pairs defining the captions for this index.
Note that BDSup2Sub ignores all captions but those after the id,index header that fits the language index defined via the "langidx" keyword.

Notes on SUP/IFO

The SUP/IFO format as defined by IfoEdit/VobEdit is supported since version 3.9.0 due to public demand. Internally (e.g. regarding RLE encoding, palette definitions etc.) it's virtually the same as SUB/IDX. Note that there are some limitations to this format though.
Firstly, the palette and the screen size are stored inside an IFO file. BDSup2Sub needs a valid IFO file for each SUP file and both have to share the same file name (except the extension of course). If you e.g. exported a file "english.sup" from a "VTS_02_1.VOB" and the according IFO is "VTS_02_0.IFO", then you need to copy the IFO and rename it to "english.ifo" to make BDSup2Sub accept it as input.
Note that BDSup2Sub recognizes the extension "IFO" for SUP/IFO, but not "SUP". The reason is that BDSup2Sub can differ between BD-SUP and HD-DVD-SUP during import only because both format have different packet identifiers. Unfortunately, HD-DVD-SUP and DVD-SUP use the same (outer) package structure so they can only be distinguished between during parsing of the command buffer. At this time, BDSup2Sub already decided to treat a SUP with that package header as "HD-DVD-SUP" and will throw an error.
When exporting, you should be aware that there are only PAL and NTSC resolutions defined in the DVD format (and therefore in the IFO).Thus hires or cropped formats will lead to major problems, even when importing these files back in BDSup2Sub. I'd strongly suggest to use VobSub in such cases.

Command line interface

While BDSup2Sub has a graphical interface, it can be used from the command line as well. Note that to start the GUI without an open console, use "javaw" instead under Windows.

Syntax1:
java -jar BDSup2Sub.jar [options]

If there is no file name given (all passed parameters are options starting with "/"), the GUI is started. Still you can pass options to e.g. preselect the target frame rate or resolution. If there's only one parameter which is either "/help" or "/?", a short help will be displayed  in the console instead (i.e. the GUI will not start).

Syntax2:
java -jar BDSup2Sub.jar <in> [options]

If there is only file name ("<in>") given, the GUI is started and the file with the given name is loaded immediately. Options passed will be used as default settings if possible.

Syntax3:
java -jar BDSup2Sub.jar <in> <out> [options]

If there is an source file name <in> and a target file name <out>, the GUI is not started, but BDSup2Sub behaves like a command line application.Note that it's mandatory that the target file name has an extension, which might be either ".sup", ".ifo", ".idx" or ".sub". If the extension of the output file name is ".idx" or ".sub", the output format will be SUB/IDX. If the extension of the output file name is ".sup", the output format will be BD-SUP. If the extension is ":ifo", the output format is SUP/IFO.

Any of the following options may passed:
    /res:<n> set output resolution to either 480, 576, 720 or 1080 - default 576.
You can also use "pal", "ntsc", "720p" or "1080p" instead.
For 1440x1080 use "/res:1440x1080"
Use "/res:keep" to keep the resolution of the source
    /dly:<n> set delay in ms - default: 0.0. Will be synchronized to target frame rate.
    /forced[+/-] export only forced subtitles - default: off (all subtitles are exported).
    /forceall[+/-] set/clear forced flag for all subs - default: off (keep)
    /swap[+/-] swap Cr/Cb components - default: off (don't swap).
    /tmin:<t> set minimum display time in ms - default: 500
    /tmerge:<t> set maximum time difference for merging captions in ms - default: 200
Note: currently only supported for BD-SUPs
    /fps:<src>,<trg> convert frame rate from <src> to <trg> given as floating point values.
Predefined values; 24p=23.976, pal or 25p=25, ntsc or 30p=29.967
/fps:auto,<t> detects source frame rate automatically
    /fps:<trg> synchronize target frame rate to <trg>. Default: automatic (dumb!).
Predefined values; 24p=23.976, pal or 25p=25, ntsc or 30p=29.967
"/fps:keep" preserves the source fps (for BD&XML, else default)
    /filter:<f> set scaling filter - default: bilinear. Supported types:
bilinear, triangle, bicubic, bell, b-spline, hermite, lanczos3, mitchell
    /movin:<r>[,<o>] move captions inside screen ratio <r>, plus/minus offset <o>
    /movout:<r>[,<o>] move captions outside screen ratio <r>, plus/minus offset <o>
    /movex:<t>[,<o>]] move captions horizontally. <t> may be "left", "right" or "center".
+/- optional offset <o> (only used if moving left or right)
    /cropy:<n> crop the upper and lower n lines - default: 0
    /acrop:<n> set alpha cropping threshold - default: 10
    /scale:<x>,<y> scale captions with free factors - default: 1.0,1.0  (min: 0.5, max: 2.0)
    /exppal[+/-] export target palette in PGCEdit text format - default: off (don't export)
    /fixinv[+/-] fix zero alpha frame palette - default: off (don't fix)
Note: ignored if import format is neither SUB/IDX nor SUP/IFO.
    /verbatim[+/-] switch on verbatim console output mode - default: off
    /palmode:<s> palette mode: keep, create, dither - default: create
Note: if the export format is SUB/IDX, but the import format isn't, this
setting is ignored. If both input and output format are SUB/IDX, "dither"
is identical to "create".

The following options only make sense for SUB/IDX or SUP/IFO exports:
    /atr:<n> set alpha threshold 0..255. Default 80
    /ltr1:<n>         set luminance low/mid threshold 0..255. Default automatic.
    /ltr2:<n> set luminance mid/high threshold 0..255. Default automatic.
    /lang:<s> set language to string <s> (e.g. "en" for English or "de" for German). Default: "de"
For a complete list, try /lang:?
Note that this also works for XML and BD-SUP exports, yet the full language selection is limited.
    /pal:<s> load palette file named <s> (ini files exported from BDSup2Subs color edit dialog) 

Note: boolean parameters like "/verbatim" or "/fixinv" can be switched on/off with a trailing "+" or "-". So "/verbatim" is the same as "/verbatim+", while "/verbatim-" switches the feature off. If a boolean switch is not used, the current value from the (automatically created) INI file is used. Only if no INI file exists, the default value is used.

Examples:
java -jar BDSUp2Sub.jar sup2.sup sup2.sub /lang:en /res:ntsc
java -jar BDSUp2Sub.jar sup2.sup sup2.sub /lang:no /atr:40 /res:1080 /forced /fps:24p,25p
java -jar BDSUp2Sub.jar sup2.sup sup2_exp.sup /lang:no /atr:40 /res:720p /forced-

Using wildcards at the command line

Since version 2.0, wildcards are supported at the command line (if both, source and target file name are given). Due to limitations of the Java runtime, the complete parameter string has to be enclosed in double quotes if wildcards are used!!! To still allow file names with spaces, use single quotes (apostrophes) then to enclose such file names.
Supported wildcards are "*" (asterisk) for at least one alphanumeric character including underscore and dot (a-z,A-Z,"_", ".") and "?" (question mark) for exactly one occurrence of an alphanumeric character.

Examples:
java -jar BDSUp2Sub.jar "reference\m?trix*.sup out\*.idx /lang:en /res:ntsc"
java -jar BDSUp2Sub.jar "'in path\m?trix*.sup' 'out path\*.idx' /lang:no /atr:40 /res:1080 /forced"

Note: the target file name must contain exactly one asterisk ("*") as wildcard. It will be replaced with the according source file name (stripped off its path and extension). If the source file name doesn't contain wildcards, the asterisk in the target file name will be replaced with the source filename stripped off its extension, but including the path.

Application Hints

Increasing the RAM size

Java application only get a maximum of 64MB of RAM per default. This can lead to memory problems when loading SUPs with thousands of warnings or if importing XML/PNG with very large images. The java runtime supports command line switches to increase the RAM size though:

java -Xmx256m -jar BDSUp2Sub.jar

This will increase the maximum heap to 256MB of RAM which should be enough in all cases. Since this is a parameter to the virtual machine, it must be used before the "-jar" and it has no influence on BDSup2Sub's command line switches.

Disabling Direct3D support in case of problems

When running in Windows, the Java runtime environment tries to make use of Direct3D for hardware accelerated blitting and storing images in the RAM of the video card. However due to implementation bugs in the JRE and or the video card drivers, this can lead to problems with certain combinations of hardware, video card drivers and JRE versions which start with visual artefacts (redraw problems, flickering, displaced graphics) and can end with system crashes. If this happens, the use of Direct3D can be disabled by adding the command line switch "-Dsun.java2d.d3d=false" when starting a Java application.
To affect any Java application, it's usually a good idea to disable the use of Direct3D globally by creating an environment variable called "_JAVA_OPTIONS" with the value "-Dsun.java2d.d3d=false". This can be done in the System control of the Windows control panel.
Just in case that you're using Eclipse, I'd like to mention that setting this environment variable makes it impossible to start current versions of Eclipse with the default launcher (Eclipse.exe). This is obviously a weird bug in the launcher - then again, you can still start Eclipse directly via the correct Jar.

Integration in the Windows Explorer

Unfortunately it's impossible to change the Windows registry in Java without sacrificing platform independence. So to register BDSup2Sub as default application for SUP files, some manual work is needed.
Cut out this text and save it with a plain text editor (e.g. NotePad) as BDSup2Sub.reg (the extension ".reg" is important!).

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\.sup]
@="SUP BD/HD-DVD caption stream"

[HKEY_CLASSES_ROOT\.sup\shell]

[HKEY_CLASSES_ROOT\.sup\shell\open]

[HKEY_CLASSES_ROOT\.sup\shell\open\command]
@="E:\\dev\\java\\jre_6_0\\bin\\javaw.exe -jar d:\\src\\java\\BDSup2Sub\\BDSup2Sub.jar \"%1\""

Then replace "E:\\dev\\java\\jre_6_0\\bin" with the path to your Java runtime and  "d:\\src\\java\\BDSup2Sub" with your installation directory of BDSup2Sub. Remember to use double backlashes ("\\" instead of "\")!!!
Now save the file and double click it from the Explorer. Chose "yes" in the following two dialogs.
If you (and I) did everything right, BDSup2Sub should be used now to open SUP files when you double click on them.
You can use the same approach of course to open VobSubs. Just replace "sup" with "idx" and "SUP BD/HD-DVD caption stream" with "SUB/IDX caption stream" or whatever you like as name.

Desktop Integration (Icons)

While BDSup2Sub has an application icon, unfortunately, the default coffee cup of the Java Virtual Machine is used if you created yourself a desktop icon to start BDSup2Sub. This is because a JAR is always opened with the installed JVM and so you get the icon of the JVM, not the one of the application inside the JAR. Still it's possible to change the icon manually (at least in windows, but I assume this is the same in Linux and MacOS). For your convenience, not only the PNG picture (icon_32.png) used by the application is included in the JAR, but also an ICO file for Windows and an ICNS file for MacOS X. I don't know too much about Linux icons, but I's guess you should be able to use the PNG. Anyway, to extract these icons, simply rename the JAR to ZIP and extract the files.

Drag'n'Drop

BDSup2Sub is able to open files via Drag'n'Drop. Just drag a SUP, XML, IFO or IDX file on the application window and release the mouse button. As BDSup2Sub is not able to open more than one subtitle stream at a time, only one file will be opened if you drag&drop multiple files. Internally, always the first file in the passed list is opened - this might however not be the file that is displayed first in your selection. Anyway, this feature is meant for one file only anyway.
Note: as explained in the SUP/IFO section, Drag'n'Drop of a DVD-SUP will lead to wrong detection as HD-DVD-SUP and the import will fail with error messages. Drag'n'Drop of the IFO works though.

The INI file (persistence)

BDSup2Sub stores some settings in an INI file that is located in the same folder as the JAR. You should usually not need to edit or delete the INI file. Yet both is possible. If the INI file (or entries within it) is missing, BDSup2Sub will use some default settings.
#BDSup2Sub 3.9.5 settings - don't modify manually
#Sat Jun 27 13:28:05 CEST 2009
fixZeroAlpha=true
filter=Mitchell
loadPath=D\:\\src\\Java\\BDSup2Sub\\reference\\colored-forced.idx
mergePTSdiff=18000
frameHeight=600
framePosY=197
framePosX=241
alphaCrop=14
frameWidth=799
verbatim=true
savePath=D\:\\src\\Java\\BDSup2Sub\\reference\\colored-forced.idx
colorPath=
paletteMode=keep existing

As you can see, some (yet not nearly all) program settings are stored in the INI file. E.g. the default filter (in this case: "Mitchell") or the verbatim output setting. Note that also "alphaCrop" and "mergePTSdiff" are stored which can be (currently) only selected via the command line (by using the parameters "/acrop" and "/tmerge"). This means that you don't need to set e.g. "/tmerge" every time you call BDSup2Sub. This however also means that this setting is kept until you actively change it again (or delete the INI file).

Source Code

As of version 4.0.0, BDSup2Sub became an Open Source project. All files that are my own creation are released under the Apache License 2.0. In a nutshell that means you can use them and modify them even for closed source or commercial projects, as long as you leave some copyright info in and give appropriate credit. See the linked Apache License for details.
Note that there are also some sources included which are based on the work of other people and thus have partly different license models:
Each file of the source code should contain a header with the license information.
Note that now that all sources are freely available, the JAR doesn't contain sources any more. The whole source code, the icons and the HTML help are now stored in a Subversion repository hosted on Javaforge. For more information on Subversion, you may have a look here.
To access the repository you need an installation of a Subversion application. Apart from the command line tools, there are also GUIs like RapidSVN or IDE plugins like Subversive for Eclipse.
Repository URL http://javaforge.com/svn/bdsup2sub
login anonymous
password anon

Disclaimer

BDSup2Sub is provided "as is" without warranty of any kind. Use it at your own risk.

BDSup2Sub is freeware in the sense of "free for all to use". Download it, give it to your friends or whatever.
If you intend to put it as download on your site, please make a reference to the thread in the Doom9 forum. Same is true for distribution on magazine CDs/DVDs.
If you plan to distribute BDSup2Sub as part of a commercial tool (which includes Shareware tools), please contact me before via PM.

As of version 4.0.0, BDSup2Sub is also "free software", as all parts of the source are released under licenses approved by the Free Software Foundation. See chapter Source Code for details.

If you wish to use the JAR as a library for converting subtitles, you're invited to as long as you honor the terms defined above. JavaDocs are included for all interesting public interfaces, so you just need to integrate the JAR in your project. For an example how to interface the core objects, just drop me a note.

Change History

26.02.2009 1.0 -> 1.1

02.03.2009 1.1 -> 1.2

04.03.2009 1.2 -> 1.3

06.03.2009 1.3 -> 1.4

06.03.2009 1.4 -> 1.5
08.03.2009 1.5 -> 1.6
10.03.2009 1.6 -> 1.7
13.03.2009 1.7 -> 1.8
11.03.2009 1.8 -> 1.9
15.03.2009 1.9 -> 2.0
17.03.2009 2.0 -> 2.1
18.03.2009 2.1 -> 2.2
22.03.2009 2.2 -> 2.3
25.03.2009 2.3 -> 2.4
26.03.2009 2.4 -> 2.5
27.03.2009 2.5 -> 2.6
31.3.2009 2.6 -> 2.7
02.04.2009 2.7 -> 2.8
05.04.2009 2.8 -> 2.9
08.04.2009 2.9 -> 3.0
10.04.2009 3.0 -> 3.1.0
14.04.2009 3.1.0 -> 3.2.0
18.04.2009 3.2.0 -> 3.3.0
18.04.2009 3.3.0 -> 3.3.1
18.04.2009 3.3.1 -> 3.3.2
19.04.2009 3.3.2 -> 3.4.0
21.04.2009 3.4.0 -> 3.4.1
24.04.2009 3.4.1 -> 3.4.2
26.04.2009 3.4.2 -> 3.4.3

03.05.2009 3.4.3 -> 3.5.0
03.05.2009 3.5.0 -> 3.5.1
06.05.2009 3.5.1 -> 3.5.2
07.05.2009 3.5.2 -> 3.5.3
10.05.2009 3.5.3 -> 3.5.4
12.05.2009 3.5.4 -> 3.5.5
15.05.2009 3.5.5 -> 3.5.6
16.05.2009 3.5.6 -> 3.6.0
18.05.2009 3.6.0 -> 3.7.0
19.05.2009 3.7.0 -> 3.7.1
21.05.2009 3.7.1 -> 3.8.0
22.05.2009 3.8.0 -> 3.8.1
24.05.2009 3.8.1 -> 3.8.2
12.06.2009 3.8.2 -> 3.9.0
13.06.2009: 3.9.0 -> 3.9.1
14.06.2009: 3.9.1 -> 3.9.2
16.06.2009: 3.9.2 -> 3.9.3
21.06.2009: 3.9.3 -> 3.9.4
27.06.2009: 3.9.4 -> 3.9.5
11.07.2009: 3.9.5 -> 3.9.6
07.09.2009: 3.9.6 -> 3.9.7
07.10.2009: 3.9.7 -> 3.9.8
15.11.2009: 3.9.8 -> 3.9.9
14.12.2009: 3.9.9 -> 4.0.0