How to Use SUBtools

Hopefully, most of the operations of SUBtools are fairly intuitive. If you enable Tool Tips in the help menu or in the preference, then you'll see useful contextual help for key operations. Before proceeding, you might find that going over the brief discussion about  subtitle formats can be useful.

Opening Subtitle Files

Open a subtitle file using either the "Open" button, the "File" menu, or you can drag the file to SUBtools' main table. For VobSub files, open the .idx file. The interface will change based on the type of file being opened, and the selected export format.

Text-Based Subtitles

  1. Before opening a file, select from the popup button the type of text encoding to use for importing the subtitles. The default of UTF-8 should work for most circumstances.
  2. If SUBtools can not read the file, or the text contains strange characters, changing the text encoding should fix things. You can do this using one of two different methods.
    1. Select a new text encoding from the popup button. This can potentially involve a lot of trial and error, but it can be a quick method if you know something about the subtitle file. For example, MacArabic would be a good choice if you know the subtitle contains Arabic characters.
    2. Or, click on the Cycle Encodings button. SUBtools will cycle through the list of text encodings and show you the results of each one that allows the file to be opened. This can be a long process, but can be quicker than the manual method if you don't know much about the subtitle
  3. Note that when you change the encoding setting, the current subtitle and any edits you have made since last saving will be lost.
  4. Before you begin to edit the subtitle that you just opened, you need to be sure that the you are using the correct export option - Export as SRT or Export as ASS. Each selection has a unique GUI, and edits made in one mode will not carry over to the opposite mode.

Image-Based Subtitles

  1. Text encodings are not needed when opening image-based subtitles. SUBtools uses an optical character recognition (OCR) tool called tesseract to translate the subtitle images into text. Note that this can be a fairly slow process. It can also be inaccurate.
  2. Before opening an image-based subtitle file, to increase the accuracy, you should select the language dictionary to use in the OCR processing.
    1. Open the SUBtools preference panel.
    2. Click on the OCR tab.
    3. Select the Current Language from the popup button. SUBtools comes with one language (English) installed. Use the Find Languages button to find other languages on the internet and then the "+" button to add the downloaded "tessdata".
  3. As you use the OCR capabilities of SUBtools, you'll find that some character conversion errors occur fairly regularly. For example, for certain fonts, the letter "l" can easily be misidentified as the vertical bar character - "|". To prevent this error, use the exclusion feature of tesseract.
    1. Open the SUBtools preference panel.
    2. Click on the OCR tab.
    3. The Characters to Exclude text field contains all the characters that SUBtools should ignore as possible output characters during the conversion. Be sure not to use commas to separate the characters you enter, or commas will be excluded from the conversion.
  4. As SUBtools is processing the data, you can check the accuracy of the translations, and edit any mistakes. SUBtools will warn you about what it thinks are potential spelling mistakes. Note though, that it will not find all misspellings.

Subtitles can also be opened indirectly via MP4toolsMKVtools, and AVItools. These applications have the ability to export a subtitle track from a video file directly into SUBtools. SUBtools does not have to be open for this to work. Be sure you save your current subtitle file before doing this as any edits will be lost when you open a new file.

 

Saving/Exporting Subtitle Files

Save/export a subtitle file using either the "Export to ..." button or the "File" menu. When exporting a video you need to specify the format of the exported file - either SRT or ASS. As mentioned above, you should have made this selection before you started editing the subtitle. You also need to select the destination for the export from among the following choices:

  • Disk - A standard Save panel will open allowing you to save the file to your hard drive in the selected folder with the name that you specify.
  • MP4tools - The file is saved temporarily to disk and then imported into MP4tools as a subtitle track for further processing. For this to work, you must have a valid location for MP4tools specified in the SUBtools preferences and MP4tools must already be open with a video file loaded. The typical work flow is open a video in MP4tools, send the subtitle track to SUBtools for editing, and then export it back to MP4tools.
  • MKVtools - The file is saved temporarily to disk and then imported into MKVtools as a subtitle track for further processing. For this to work, you must have a valid location for MKVtools specified in the SUBtools preferences and MKVtools must already be open with a video file loaded. The typical work flow is open a video in MKVtools, send the subtitle track to SUBtools for editing, and then export it back to MKVtools.

 

Interface for Exporting to SRT from SRT

When opening an SRT subtitle and setting the app the export it as an SRT, you'll see the most basic interface, simplified primarily because of the absence of ASS/SSA styles. The important section of this interface are:

Main Table

This lists the dialog and time codes of each subtitle line. You can edit both times and dialog by selecting the line of interest and working in the Line Edits section.

The Conflict column of the indicates the existence of any timing issues with the SRT subtitles. There are five types of conflicts possible:

  • End Overlap - the end time of the given subtitle overlaps with the following subtitle. SUBtools can usually automatically fix this type of conflict by adjusting both time proportionally.
  • Start Overlap - the start time of the given subtitle overlaps with the previous subtitle. SUBtools can usually automatically fix this type of conflict by adjusting both time proportionally.
  • Both Overlap - the the start time and end time of the given subtitle overlaps with both neighboring subtitles. SUBtools can usually automatically fix this type of conflict by adjusting both times proportionally.
  • Enclosed - Indicates that the timing for the particular subtitle line is completely enclosed by the previous line. SUBtools can not automatically correct for this type of conflict.
  • Decreasing Time - the start time for the subtitle is larger than the end time. You must edit the times to correct this conflict

The Exclude column contains checkboxes that you can use to mark lines of dialog to be excluded from the exported/saved SRT file. This can be useful to clean up timing conflicts that can't be handled by SUBtools.

Time Conflicts Section

This section helps you to manage any timing conflicts. Most SRT files that you open should be exhibit no conflicts, but you'll run across a few that have been converted from another format that can lead to different possible time conflicts. This section has three functions:

  • The number of time conflicts for the current file is displayed.
  • You can use the appropriate buttons to jump quickly to lines with time conflicts so that you can edit them.
  • Click the “Fix” button to have SUBtools automatically adjust times so that overlap-type conflicts are resolved. SUBtools accomplishes this by shifting end and start times proportionally while trying to maintain the integrity of each subtitle.

Note that SUBtools will allow you to save SRT subtitles with unresolved timing conflicts, but the resulting file may not work properly depending on its use.

Line Edits Section

In this section you can edit timing and text of the currently selected line in the Main Table.

  • Start/End Times - Enter any edits to times that you'd like to make to the start and/or end time of the line. Note that though there is some error checking, it is possible for you to enter numbers that will create conflicts. The original time is remembered, so if you make a mistake you can reset the time(s) to its original value(s).
  • Up/Down Arrow Buttons - Use to navigate the subtitle lines of the main table. The Return/Enter key and the Up/Down keys on the keyboard are used to navigate within the text box.
  • Text Formatting Buttons - These will enclose text selected in the text box with Bold, Italic, or Underline tags. These may not be honored depending on the playback method. The tags might actually appear as text in the display.
  • Reset Times Button - Resets the start and end times of the current subtitle line to their original values.
  • Reset Dialog Button - Resets the text of the current subtitle line to its original value.
  • Clean Text Button - Removes any text formatting characters of the current subtitle line. These can be restored using the Reset Dialog Button.

Global Edits Section

These edits are applied to every line of the subtitle file, including those that might not be visible.

  • Reset Times Button - Resets all of the start and end times of the subtitle to their original values.
  • Reset Dialog Button - Resets all of the text of the subtitle to their original value.
  • Clean Text Button - Removes all text formatting characters in the subtitle. These can be restored using the Reset Dialog Button.

Global Time Edits Section

This section can be used to fix sync issues with the subtitle by editing all the subtitles uniformly using one of two possible methods:

  • Shift - every subtitle time is shifted forward or backward in time by the amount entered in the sections time text box.
  • Stretch - subtitle times are shifted forward or backward in time by an amount that is proportional to their location in the video. Dialog times at 0:00:00,000 are not shifted at all. Dialog at the end of the video have times shifted by the full amount entered in the time text box. Dialog at the halfway point of the video have times shifted by the half the amount entered in the time text box.

You can use either of the Reset Times buttons to undo the edits. Note that there is no error checking so you can shift the times to values that will lead to errors.

 

Interface for Exporting to SRT from SSA/ASS

When opening  ASS/SSA subtitles, styles can play a roll in how the subtitle is converted to SRT. Because of the formatting options possible with these types of files, it fairly likely that there will be potential timing conflicts when trying to convert to SRT. Using the Exclude checkbox and the Included Styles filtering can help when resolving these conflicts. The important section of this interface are:

Main Table

This lists the dialog and time codes of each subtitle line. You can edit both times and dialog by selecting the line of interest and working in the Line Edits section. For reference, the ASS/SSA style of each line is also displayed.

The Conflict column of the indicates the existence of any timing issues with the SRT subtitles. There are five types of conflicts possible:

  • End Overlap - the end time of the given subtitle overlaps with the following subtitle. SUBtools can usually automatically fix this type of conflict by adjusting both time proportionally.
  • Start Overlap - the start time of the given subtitle overlaps with the previous subtitle. SUBtools can usually automatically fix this type of conflict by adjusting both time proportionally.
  • Both Overlap - the the start time and end time of the given subtitle overlaps with both neighboring subtitles. SUBtools can usually automatically fix this type of conflict by adjusting both times proportionally.
  • Enclosed - Indicates that the timing for the particular subtitle line is completely enclosed by the previous line. SUBtools can not automatically correct for this type of conflict.
  • Decreasing Time - the start time for the subtitle is larger than the end time. You must edit the times to correct this conflict

The Exclude column contains checkboxes that you can use to mark lines of dialog to be excluded from the exported/saved SRT file. This can be useful to clean up timing conflicts that can't be handled by SUBtools.

Time Conflicts Section

This section helps you to manage any timing conflicts. These can be fairly common when converting form ASS/SSA to SRT. This section has three functions:

  • The number of time conflicts for the current file is displayed.
  • You can use the appropriate buttons to jump quickly to lines with time conflicts so that you can edit them.
  • Click the “Fix” button to have SUBtools automatically adjust times so that overlap-type conflicts are resolved. SUBtools accomplishes this by shifting end and start times proportionally while trying to maintain the integrity of each subtitle.

Note that SUBtools will allow you to save SRT subtitles with unresolved timing conflicts, but the resulting file may not work properly depending on its use.

Included Styles Filter Table

This table lists all of the styles for the subtitle file. The checkbox in the table can be used to include or remove all subtitle lines with the checked/unchecked style. Note that this is different from the Exclude checkbox in the Main Table which works only on individual lines. As an example of how this might be of use:

You might find that an English subtitle for a Japanese video also includes "Romaji"text. So for dialog you might see the English text at the bottom of the display, and at the same time the Romaji text is displayed at the top of the display. This would not convert well to SRT. Luckily, both sets of subtitles have more than likely been assigned with different styles. To see and save just the English subtitles, uncheck the Romaji style.

Note that whichever styles are unchecked in this table will not be displayed and will not be saved when exported. The Global Edit buttons will however effect all subtitle lines regardless of whether or not they are visible.

Line Edits Section

In this section you can edit timing and text of the currently selected line in the Main Table.

  • Start/End Times - Enter any edits to times that you'd like to make to the start and/or end time of the line. Note that though there is some error checking, it is possible for you to enter numbers that will create conflicts. The original time is remembered, so if you make a mistake you can reset the time(s) to its original value(s).
  • Up/Down Arrow Buttons - Use to navigate the subtitle lines of the main table. The Return/Enter key and the Up/Down keys on the keyboard are used to navigate within the text box.
  • Text Formatting Buttons - These will enclose text selected in the text box with Bold, Italic, or Underline tags. These may not be honored depending on the playback method. The tags might actually appear as text in the display.
  • Reset Times Button - Resets the start and end times of the current subtitle line to their original values.
  • Reset Dialog Button - Resets the text of the current subtitle line to its original value.
  • Clean Text Button - Removes any text formatting characters of the current subtitle line. These can be restored using the Reset Dialog Button.

Global Edits Section

These edits are applied to every line of the subtitle file, including those that might not be visible.

  • Reset Times Button - Resets all of the start and end times of the subtitle to their original values.
  • Reset Dialog Button - Resets all of the text of the subtitle to their original value.
  • Clean Text Button - Removes all text formatting characters in the subtitle. These can be restored using the Reset Dialog Button.

Global Time Edits Section

This section can be used to fix sync issues with the subtitle by editing all the subtitles uniformly using one of two possible methods:

  • Shift - every subtitle time is shifted forward or backward in time by the amount entered in the sections time text box.
  • Stretch - subtitle times are shifted forward or backward in time by an amount that is proportional to their location in the video. Dialog times at 0:00:00,000 are not shifted at all. Dialog at the end of the video have times shifted by the full amount entered in the time text box. Dialog at the halfway point of the video have times shifted by the half the amount entered in the time text box.

You can use either of the Reset Times buttons to undo the edits. Note that there is no error checking so you can shift the times to values that will lead to errors.

 

Interface for Exporting to ASS from SRT or SSA/ASS

When exporting ASS/SSA subtitles, timing conflicts become a non-issue. It's OK for subtitle times to overlap. With the extensive formatting available in these types of subtitles, the interface is dedicated to a large number of these options.

Main Table

This lists the dialog and time codes of each subtitle line. You can edit both times and dialog by selecting the line of interest and working in the Line Edits section. The Styles Formatting Section shows the format settings for the currently selected line. The Exclude column contains checkboxes that you can use to mark lines of dialog to be excluded from the exported/saved ASS file.

Styles Formatting Section

The style table lists all of the styles for the subtitle file. The checkbox in the table can be used to include/remove all subtitle lines with the checked/unchecked style. Note that this is different from the Exclude checkbox in the Main Table which works only on individual lines. Note that whichever styles are unchecked in this table will not be displayed and will not be saved when exported. The Global Edit buttons will however effect all subtitle lines regardless of whether or not they are visible.

The remaining part of this section shows the formatting for the currently selected style. The format options that SUBtools currently supports are:

  • Font Formatting - You can edit the standard font attributes shown. SUBtools remembers the original settings, so you can reset them using the Reset Fonts button.
  • Font Color - There are four color settings available. SUBtools remembers the original settings, so you can reset them using the Reset Colors button.
    • Primary - The main color of the subtitle.
    • Secondary - This color may be used instead of the primary color when a subtitle is automatically shifted to prevent an on-screen collision, to distinguish the different subtitles.
    • Outline - The color of the subtitle's outline. The size if the outline in pixels can also be specified. If set to zero there will be no outline.
    • Shadow - The color of the subtitle's background/shadow effect. The size if the shadow in pixels can also be specified. If set to zero there will be no shadow effect.
  • Alignment - Click one one of the buttons to indicate the location of the subtitle text within the display. The most common setting is shown above - lower center.
  • Margin - This section can be used to more precisely specify the location of subtitle text. Note that some of the settings will be ignored depending on the Alignment setting. For example, the Vertical value is ignored if the alignment is set to one of the three vertically centered settings.
    • Left - The horizontal distance from the left edge of the display in pixels.
    • Vertical - The vertical distance from the bottom/top edge of the display (depends on the alignment setting) in pixels.
    • Right - The horizontal distance from the right edge of the display in pixels.

Line Edits Section

In this section you can edit timing and text of the currently selected line in the Main Table.

  • Start/End Times - Enter any edits to times that you'd like to make to the start and/or end time of the line. Note that though there is some error checking, it is possible for you to enter numbers that will create conflicts. The original time is remembered, so if you make a mistake you can reset the time(s) to its original value(s).
  • Up/Down Arrow Buttons - Use to navigate the subtitle lines of the main table. The Return/Enter key and the Up/Down keys on the keyboard are used to navigate within the text box.
  • Text Formatting Buttons - These will enclose text selected in the text box with Bold, Italic, or Underline tags. These may not be honored depending on the playback method. The tags might actually appear as text in the display.
  • Styles Popup Button - Change the style assigned to the subtitle line. The original style is remembered, so if you make a mistake you can reset it to its original value.
  • Reset Times Button - Resets the start and end times of the current subtitle line to their original values.
  • Reset Dialog Button - Resets the text of the current subtitle line to its original value.
  • Reset Dialog Button - Resets the Style of the current subtitle line to its original value.
  • Clean Text Button - Removes any text formatting characters of the current subtitle line. These can be restored using the Reset Dialog Button.

Global Edits Section

These edits are applied to every line of the subtitle file, including those that might not be visible.

  • Reset Times Button - Resets all of the start and end times of the subtitle to their original values.
  • Reset Dialog Button - Resets all of the text of the subtitle to their original value.
  • Reset Styles Button - Resets all of the styles of the subtitle to their original value.
  • Clean Text Button - Removes all text formatting characters in the subtitle. These can be restored using the Reset Dialog Button.

Global Time Edits Section

This section can be used to fix sync issues with the subtitle by editing all the subtitles uniformly using one of two possible methods:

  • Shift - every subtitle time is shifted forward or backward in time by the amount entered in the sections time text box.
  • Stretch - subtitle times are shifted forward or backward in time by an amount that is proportional to their location in the video. Dialog times at 0:00:00,000 are not shifted at all. Dialog at the end of the video have times shifted by the full amount entered in the time text box. Dialog at the halfway point of the video have times shifted by the half the amount entered in the time text box.

You can use either of the Reset Times buttons to undo the edits. Note that there is no error checking so you can shift the times to values that will lead to errors.

Subtitle Preview

  • Change ... Button - Use this button to select a video file to be used when previewing the subtitle.
  • Preview Button - Use this button to open a separate window to play the selected video with the current subtitle settings. The video will start at the currently selected subtitle line.

 

Interface for Exporting SRT from Image-Based

SUBtools uses tesseract OCR software to translate image-based subtitles into SRT subtitles. Note that this can be a very time consuming process. It can also be a very inaccurate process. Be sure to review the section about opening image-based subtitles above to increase accuracy. The focus in this interface on correcting OCR errors, which you can do as the process proceeds. If you want to do more with the finished subtitle, you should export the subtitle to disk, and then open the saved subtitle in SUBtools for more extensive editing.

Main Table

This lists the dialog and time codes of each subtitle line. In the warning column, SUBtools will warn you about what it thinks are potential spelling mistakes. Note though, that it will not find all misspellings. You can edit the text by selecting the line of interest and working in the Line Edits section.

Line Edits Section

In this section you can edit the text of the currently selected line in the Main Table. For reference, the subtitle image associated with the subtitle line is displayed.

  • Up/Down Arrow Buttons - Use to navigate the subtitle lines of the main table. The Return/Enter key and the Up/Down keys on the keyboard are used to navigate within the text box.
  • Reset Current Dialog Button - Resets the text of the current subtitle line to its original value.
  • Reset All Dialog Button - Resets all of the text of the subtitle to their original value.