Documentation

Table of Contents



The program uses three tabs to control its operation:
  1. Create XSUB or Idx/Sub
  2. Configuration 1
  3. Configuration 2

1. Create XSUB or Idx/Sub

1. File Name(s). Input. Is entered the name of the video file. Can be a group of 1 or more files or a group of 1 or more folders or a mix of these. There are various ways to fill this box. By typing, by the button (...) (2) which displays a File Open dialog, by drag&drop of selected files or folders in the icon of the program or its shortcut, or directly to the edit box when the program runs. You can also activate "Right Click option" through "Configuration 2" and just right click over selected files or folders and be able to fill this box automatically.

2. Displays a Open File dialog and permits the user to select one or more files to enter at 1.

3. Output Folder. The output of the program goes to this directory. If this option left empty then the output goes in the same place as the original file. You can type the full path of the folder or use button 4 to display a select folder dialog.

4. Displays a dialog to select a folder to fill the output directory at 3.

5. When 1 is filled with files to be processed, press "Start".

6. When an operation is in progress you can stop it at any time pressing "Stop".

7. Exit. Exits the program.

2. Configuration 1

This tab permits the configuration of basic parameters of the generated subtitles, about colors, fonts, fonts size and position, character set and language. It contains another 8 tabs (SUB 1-8) that represent srt to be loaded and processed and one tab (idx/sub) for a pair of idx/sub files to be loaded and converted in XSUB.

The tabs SUB 1-8 load srt and produce subtitles in various configurations for both types, XSUB (incorporated only in avi) and idx/sub (external files) for any kind of video file. Look at 1 below. The idx/sub tab configures one idx/sub file that would be converted to XSUB and incorporated in the avi.

SUB 1-8 tabs

1. XSUB or Idx/Sub. The program can generate two kind of bitmapped subtitles. XSUB, incorporated as an additional stream in avi files, and idx/sub. The second subtitle type is not incorporated in the video file, is a combo of two external files with .idx and .sub extension. XSUB subtitles apply only to avi files but idx/sub, as external files, can accompany any kind of video file, if your player supports the combination. Choose the subtitle type that your player supports better.

2. Rearrange Subtitle text. This option controls a function of the program which processes the text of every subtitle and rearranges to fit in a specific screen width to avoid clipping at left or right. There are three selections.

  • When Very Long: Activates this function only when the text is too long to fit in the screen.
  • Always: To have a more uniform text for all subtitles regardless if they fit or not.
  • Never: Subtitles appear as the srt creator made them. Note that even the rearrange function is deactivated the program will use a smaller font if a subtitle appears not fitting in the screen.


The operation of this function is affected by option "SubWidth" at 19.

3. Character Set. The program processes ANSI (that is, not Unicode) srt files. So to be processed correctly the correct character set has to be entered here. The selection DEFAULT uses the information entered in your Windows system at "Control Panel/Regional and Language Options/Advanced/default character set for non-Unicode text". Selection ANSI is for the "western languages", that is, with Latin alphabets. Unicode or UTF8 srt files, in most cases, are automatically converted in ANSI format given that this option is correctly set.

4. Language Code. This is informational and marks the subtitle with the code of the language selected. The language information is displayed in various players when selecting subtitles.

5. Font. Font name. You can type it or select it from a list pressing button at 6.

6. Select a font family from a list of available fonts.

7. Font Size. Select the font size you prefer.

8. Width. Controls the width of the text as a percentage of its default for the specific size (Height) entered at 7.

9. Bold. The generated subtitle text is in bold.

10. Outline size. In pixels. Defines the thickness of the outline used.

11. Color. Chose the color of subtitles. You can choose color for both, text body and its outline.

12. Align. In case of multiline subtitles. This option defines its alignment (justification). Left, Center or Right.

13. SRT Extension. This, very important, option defines the file name of the srt to be loaded and processed according to the configuration found on every tab 1-8. The name of the srt to be loaded is defined in a specific way: [video file name]+[SRT Extension]+[.srt]. So having all the rest of file name parts constant you control the "SRT extension" part through this option. If left empty the video file name and srt file name will be exactly the same - except extension. See more at "Multiple subtitles from srt".

14. Opaque box. An opaque box surrounds the subtitle in the color of the outline. This is used mainly to cover up subtitles burned in the video picture already and so make more readable and distinguished your subtitles.

15. Preview. You can see how your subtitles appear when all selections (at tabs 1-8) have been applied. There is a sample text but you can load any srt to see the result with real subtitles. You can see all effects applied to subtitle except positioning on screen which depends on player's firmware and is not possible to be depicted by the program:

16. Add Subtitles. Adds the subtitles. Normal operation

17. No Subtitles. No subtitles generated. In this case already incorporated XSUB subtitles in avi will be removed. Option "unpack packed bitstream" will apply if checked.

18. Add Test Subtitles. Adds test subtitles that start from the top of the screen and go to the bottom.

19. Subtitle bitmap. The generated subtitles are bitmaps and through this option their resolution is defined. The are four options:

  • 720 X 576

  • 1280 X 720

  • 1920 X 1080

  • Custom

The first three options represent the corresponding resolution categories existed today: Standard, 720, 1080.

When "Custom" is selected then you are able, manually, to enter Width and Height of the bitmap insteed of the predefined values of the three other options.

Full Screen. When this option is checked then a full bitmap in the specified resolution will be created for every subtitle. If not checked then the subtitle will have the resolution necessary to contain its text but will be marked for the resolution defined. Generally leave this option unchecked. Some players need this checked to display subtitles or have them in a constant VP/CP (see 20 below) for all videos. Experiment to see what fits best for your player in case of problems.

SubWidth. Is a percentage value that affects the way the subtitle text is rearranged to fit in the defined bitmap width. A value of 100% means that the Subtitle Width=Bitmap Width. This value can be below or above 100%. Values above 100% are useful in cases the player's firmware shrinks the subtitle bitmap when doing its rendering to your TV. Please note that values above 100% work best when "Full Screen" option is unchecked.

20. Subtitle position. There are two values that control the position of subtitles in your TV. VP (Vertical Position) and CP (Center Point - or Horizontal Position). Subtitles are positioned  in the rectangle defined in 19, according VP/CP values.

VP has the value of zero (0) and the top of your TV screen and as the subtitles go down, increases. Points to the bottom of every subtitle so the top of the subtitle is calculated through the following formula: VP-Subtitle Height.

CP is a value that determines the center of your TV screen so the subtitles can be positioned in its center.

Is very important to understand that these values are not depended on your TV but in the way the firmware of your player interprets them. So there is no any standard concerning these values. Every player needs its own values to display subtitles in the wished position on your TV. Most of the time you have to experiment a bit to find the correct values. This is done once for every player. It is true that some players cannot be configured with one set of values and they need different values depending on the video resolution. The solution in this case is, the user, to find out this relation and select the correct values for any given video resolution by hand. Another solution is to incorporate more than once the same srt, in various VP/CP (usually only VP varies) configurations so at playback time can choose the correct subtitle for the given video. This ability is controlled through "SRT extension" (13) option because any of the SUB 1-8 tabs having the same value in this field load the same srt. So use this ability to have one srt producing subtitles in various VP/CP values, selectable at playback.

idx/sub tab

This tab configures idx/sub subtitles you wish to convert in XSUB exclusively for avi video files.

The idx/sub to XSUB conversion tab includes the same "Subtitle Bitmap" and "Subtitle position" options, as in the case of SUB 1-8 tabs. Because idx/sub contain subtitles already in bitmap format all other options found at SUB 1-8, with the purpose to construct the text content of the bitmaps, are not needed. Instead there is a new set of options under the "Choosing Subtitles". One idx/sub combo can contain subtitles in many languages so the user has to be able to select which of them to include in the conversion process.

All. Subtitles in all languages will be included.

Ask User. A dialog asks the user which of them to choose.

These Language codes only. When this is selected then, in the edit box below it, the user has to enter the language codes to be selected automatically every time an idx/sub is converted to XSUB. The language codes have to be separated by comas, as in the picture.

3. Configuration 2

Some additional configuration options, of a general scope, can be found here.

1. Unpack packed bitstream. Some players (like my PHILIPS DVP5980) do not fully support "packed bitstream". This causes some video encoded this way to appear with jerky move, like some frames are dropped, etc. This is a nice way to catch a headache. If this option is checked (default) the frames become unpacked automatically and all "packed" AVIs have a much smoother playback. Unpacking packed bitstream has nothing to do with video compression. The "unpacked" AVI actually can be slightly smaller.

2. Use .avi for output file(s) if possible (XSUB only). By default the output file is named with extension divx. If this is checked and has been defined an output directory different from the one of the source file, then the generated file is named with extension avi. This cannot work, of course, when input and output directory are the same because we cannot write the new over the original avi.

3. Delete original avi: If this option is checked then after the successful generation of the new subtitled file, the original (or source) will be deleted.

4. Move srt to output directory: When is checked (and the avi is copied too) the srt is moved in the output directory. Please note that the srt is not needed to view the subtitles in the player. This option is useful in cases the output directory is used also for archiving purposes. To avoid confusion do not burn the srt together with the avi in the DVD will use to play the video in the player.

5. Do not copy avi when no XSUB: Checking this option and configuring the program only for idx/sub generation the original avi will not be copied in the output directory. Please note that except of cases of a simple copy of the file this operation applies the "Unpack packed bitstream" option that makes some players to have a smoother playback.

6. Do not convert idx/sub in XSUB: You need to check this option in case you generate only idx/sub subtitles and you don't want idx/sub to be converted in XSUB and incorporated in the avi. This way you are avoiding the case when the program will take its idx/sub output as input when you repeat the subtitle operation. This can happen when the input and output directories are the same.

7. YUV values at Idx/Sub color palette: Applies to idx/sub subtitle generation from srt and defines the kind of color values in idx/sub color palette. If it is checked then YUV values are generated else RGB values (those are different techniques to express color). If you get strange colors check or uncheck, depending on what it was the previous state.

8. Start at once: When files or folders are dropped at program's icon or shortcut or through right click on them, then, if this option is checked, the processing will start immediately without having to press "Start".

9. Merge mkv and idx/sub. When idx/sub subtitles generation is selected for a mkv video file AVIAddXSubs can automatically merge them with mkv through mkvmerge utility. This to work mkvmerge.exe has to be present in AVIAddXSubs installation directory. If MKVToolNix is already installed in your PC then copy mkvmerge.exe in AVIAddXSubs directory too. If not download and install MKVToolNix from here. The new mkv, with subtitles merged, is created at the output directory.

10. Mark DivX as (XSUB only): You can mark generated divx files as DIVX, XVID or DX50. Some players need a specific mark to show the subtitles. This option affects original avi with the above marks that represent compatible encodings. For example DIV3 avi will not be affected by this option. Selection NONE leaves the mark of the original avi.

11. Chapter every ... minutes (XSUB only). When a value above zero is entered then this defines a time interval at which a chapter will be generated. If the value is zero then no chapters are generated. In case of adding chapters then a small avi, supplied in the zip, is incorporated in the avi. This small avi ("menu.avi") displays the message "Loading... Please Wait...".  The user can change that to display another message or picture(s) of his/her preference. See more at Changing the introductory avi. For this feature to work the hardware player has to support officially or unofficially DivX Ultra.

The user has the option to add chapters in specific time points too. This is accomplished through a text file placed together with the avi. This file must have the same name as the avi but with extension .chp. Every chapter is represented in a separate line in the text with time information in the form of 00:00:00:000 (hours, minutes, seconds, milliseconds), familiar from srt files. For example:

00:10:00:000
00:12:00:000
00:20:00:000
01:10:05:100
...

Please note that the program always adds automatically a chapter at 00:00:00:000 (video start).

This feature applies only to XSUB subtitles and works in players supporting DivX 6 Ultra.

12. Right Click Context Menu Option. Provides the ability to select an avi/srt or a group of avi/srt or a group of folders (or a mix) with a right click in the selection:

This is a fast way to start the program. Note that if "Start at once" (8) is checked then the process starts immediately without the need to press button "Start" (First tab - 1) first.

Please note that when this option is activated AVIAddXSub.dll file of AVIAddXSubs installation is connected with Windows shell. So if you try to delete this file the OS will refuse because it uses it. In this case, to delete this dll (for example to upgrade to newer version), first disable this option, make a log off/log on (or reboot) and then you will be able to delete it.

Users of Vista/Win7 have to deactivate UAC (User Account Control) so AVIAddXSubs can write to the registry.

13. Subtitle Time (in milliseconds). Under this title there are two options:

  • Time Shift by ... a number of milliseconds. Using a negative number subtitles will appear the specified milliseconds sooner. With positive numbers later.
  • Increase Duration by ... a number of milliseconds. This is useful in cases that subs go away very fast or the synchronizations is "suspected" not that good. Of course the duration extension is limited by the start of the next subtitle.

Converting mp4/mkv to avi
for XSUB subtitle incorporation

XSUB subtitles apply only to avi files. This creates problems for users, for example of PS3, that they cannot have easily subtitles other than XSUB in avi. At the same time mp4 and mkv files start to replace avi files. So AVIAddxSubs from version 9.11 can convert automatically any mp4 or mkv file, using ffmpeg, in its avi equivalent and then incorporate XSUB subtitles.

To do the conversion automatically you  have to copy ffmpeg.exe command line executable in AVIAddXSubs directory. This file has to be downloaded separately. Get it from here. It is advised to use this provided ffmpeg executable version as I did all my tests with it and I know that it works well.

When ffmpeg.exe is present in AVIAddXSubs directory and XSUB subtitle type is selected (at SUB 1-8 pages) and the video file is of mp4/mkv format, AVIAddXSubs will convert it to avi and after this is done will incorporate XSUB subtitles. During the conversion information will appear in the screen showing its progress. These are:

  • FRAME: The frame number currently processed.
  • FPS: The number of frames processed per second. The bigger this number the faster the conversion.
  • SIZE: Current size of the avi.
  • TIME: The time the current processed frame corresponds during playback. This time "passes" as fast as the conversion progress.

The avi is generated in the same directory as the original mp4/mkv and is not deleted after use. So in case you repeat the XSUB incorporation will not need to repeat the conversion. You have to delete it yourself when it is not needed.

The ffmpeg command line used by AVIAddXSubs to convert mp4/mkv files to avi format can be edited by a user who can understand its various parameters and wish to experiment with various results in file size and/or video quality, used encoders/decoders etc. The editing is provided through AVIAddXSubs ffmpeg page:

All information about the various ffmpeg parameters can be found here.

Multiple Subtitles from srt

In configuration page you can configure up to 8 srt subtitle files. There are 8 tabs, SUB1 through SUB8, with a number of configuration options. For every tab corresponds a srt file that is searched through a specific naming convention. This naming convention is controlled through a literal at option "SRT extension" found in every such tab. The corresponding srt file name is composed from the avi file name and the literal defined in the aforementioned option, that is [AVI name]+[SRT extension]+[.srt]. For example, to an avi lost0204.avi and a "SRT extension" "-en" corresponds a srt "lost0204-en.srt". If "SRT Extension"  is empty the srt file has exactly the name of the avi: lost0204.srt.

In case you wish to incorporate the same srt more than once in an avi, using different configurations in every incorporation, enter the same literal in "SRT extension" option for all those tabs (SUB 1-8) that represent those configurations.

Examples:

For a file lost0303.avi, a tab (SUB 1-8) with "SRT extension":

  • empty string loads the srt "lost0303.srt"
  • "-en" loads the srt "lost0303-en.srt"
  • "-pt" loads the srt "lost0303-pt.srt"
  • "-For My flat TV" loads the srt "lost0303-For My flat TV.srt"
  • ".fr" loads the srt "lost0303.fr.srt"

Configuration tips

As the firmware of the player decides how to render the subtitles in your TV, the configuration is not very simple in some cases. Lucky people need just to play a bit with VP option to position correctly the subtitles and the only thing left is to decide font and font size of their liking. Then, whatever is the resolution of the video they throw in their player, the subtitles look always the same.

But some others are not so lucky with their player as they see that subtitles vary depending on the video resolution. And the subtitles configured for one resolution doesn't seem acceptable for another. To my experience the problem can be manageable as we can have up to three categories of resolution to consider about. Files of standard (DVD) resolution (around 480p), 720p files and 1080p files. So you need up to three configurations of subtitles.

The solution offered from AVIAddXSubs is to generate all the time up to three subtitles for every video, with different configuration each, and be able, at playback time, to choose the one that fits better the played video. In this case you just incorporate the same srt 2 or 3 times. Look above topic on how you can do that.

To get the best configurations, for every resolution category, most of the time you have to experiment a bit. This, other times is easier and in others needs more effort. There is a number of options that help us to get the best possible result. These are: All the options at "Subtitle bitmap" and option Width(%) at the font section.

It is not always true but when the video resolution increases you have to adapt the bitmap resolution too. Use Custom option for resolutions above standard.

Have in mind that the subtitle resolution and video resolution have no need to be the same as the rendering of subtitles is a separate process from video rendering. Subtitles could appear in the bottom of the screen where there are black horizontal bands, as it is usual for videos not in 16:9 aspect ratio.

Generally you have to play with values in "Subtitle bitmap" to see the effect they produce in the subtitle rendering and so be able to decide the "strategy" to get your best subtitles.

One thing I have found is the use of the Width option at the font section. This option increases or decreases letter width as a percentage of its normal value (for the specified size). It can create "condensed" or "expanded" text. But it can also help in cases the player's firmware changes the aspect ratio of the original subtitle bitmap. If subtitle text is not "round" and looks wider or condensed than normal, it can be "fixed" with this option. If the text looks wider experiment with values less than 100%. If looks condensed experiment with values above 100%.

Starting and ending AVIAddXSubs without user intervention

Normally to start the processing the user has to press "Start". But if the program starts through a drag&drop or through right click menu option and if the configuration page option "Start at once" is checked, then this step is bypassed and the processing starts immediately.

Also there is a capability so AViAddXSubs can stop its execution after finishing processing. This is intended to advanced users that wish to use the program in batch processing jobs that do various things and a XSUB subtitle incorporation in addition. This capability can be accessed only through AVIAddXSubs configuration file (aviaddxsubs.txt) and through the parameter ENDATONCE. Its default value is 0. Just put an 1 there.

About Idx/Sub subtitle files (in case of conversion in XSUB format)

Any such file pair can contain subtitles for more than one languages. In case of more than one language a dialog will appear so the user is able to choose which of them to include. Up to 8 languages can be selected and included.

Also in case the subtitle colors are not satisfactory the user is able to intervene in the idx file with any text editor, like Windows notepad, and get better results. First check the text entry Custom Colors. This entry provides a palette of 4 colors that can be used in subtitle bitmaps. This entry appears as in the following example:

custom colors: ON, tridx: 0001, colors: 000000, 808080, FFFFFF, 0000FF

Check if marked as ON or OFF. If it is OFF make it ON and check again in case you get better results. If not you can change any of these colors as follows: In the same entry there is a section with the name tridx. This defines which of the palette colors are used as transparent. Its value is four digits of 0 or 1. If you see 1, then in the corresponding palette position there is a transparent color. Then you point your attention to the rest of palette colors. To get letters with white body and black outline, use the (RGB in hex format) color FFFFFF (white) and 00000 (black). Put these values in the various none transparent positions of the palette (all except the last in the example above), every time save the idx file, run AVIAddXSubs and see if the result is now satisfactory.

Changing the introductory avi (XSUB)

When user chooses to add chapters in the generated avi then a small supplied avi ("menu.avi") is incorporated in the final file. This avi displays a message ("Loading... Please Wait...") briefly at video initialization. User is able to replace this avi with another that display what he/she prefers. To do so just use an imaging software to create an image (.jpg) with 720X576 resolution. Then use VirtualDub to make an avi based in this image (or many images if you prefer). Load the image(s) with VirtuaDub. Then select any Frame Rate (I choosed 1) and choose for compression XVid. These options are under the menu "Video" of VirtualDub. Then you can save the new avi under the name "menu.avi". Finally replace the supplied avi with this one and start incorporating subtitles as usual using any interval for the generated chapters.

SUBRenamer utility

This utility is used to rename easily an avi file and its associated srt. The easiest way to use it is to create a shortcut of the program in your desktop. Then select an avi and all its associated srt and drag&drop them to program's shortcut. When the program runs resembles in a way the list of SUB 1-8 + idx/sub tabs in AVIAddXSubs itself. The avi will appear under an edit box named "AVI File" and all srt (or idx) in the list at the bottom. The list has always 9 lines. The lines 1-8 represent SUB 1-8 tabs of AVIAddXSubs and the 9 the idx/sub tab. Every file will go in an appropriate position. You can use "UP" and "Down" buttons to rearrange the list so every srt file is listed in the SUB position you prefer.

In the list there are four columns. The first is the SUB number and the second is the current srt/idx file name. The third (ext) and four (lang) display information read from AVIAddXSubs configuration file. They display the literal found in "SRT extension" and the language for all tabs 1-8.

Under the edit box "New common name for avi and idx/sub" will appear automatically the name of the AVI without extension. For example if the avi was "lost0209.avi" there will appear "lost0209". You can accept or modify this name. Under this name all files (avi, srt, idx, sub) will be renamed if you press the button "Rename".