Home

GEONius.com
11-Aug-2019
E-mail

subtle - SUBTitLEr

subtle adjusts the time tags in a SubRip Text (".srt") file in order to synchronize the subtitles with the video. subtle doesn't actually deal with the video, but instead requires the user to watch the video with subtitles, measure their asynchronicity, and invoke subtle with those measurements.

For example, I usually watch the video with VideoLAN's VLC media player. At the same time, I have the SRT file open in a text editor. In two trial-and-error steps:

  1. I pick one of the earliest subtitles for which the audio is clear. (This is not necessarily the very first subtitle; e.g., the first few subtitles may be difficult-to-distinguish voices in a crowd.) I position the video around where the subtitle occurs, playback the video, and listen for a person to speak the text of the subtitle. When the person begins to speak those words, I pause the video player and note the time at which I paused. I then compare that time to the subtitle's start time, the difference between the two being the time-shift required to synchronize that subtitle with the video's audio track.

  2. I repeat the first step for one of the last subtitles in the video.

If I'm lucky, the subtitles are already in sync with the video. If not, I now have the offset in seconds of the subtitles at the beginning of the video and the offset of the subtitles at the end of the video. If a subtitle is displayed before the corresponding audio, the offset will be positive (e.g., 5 if the subtitle appears 5 seconds before the audio). If the subtitle is delayed, the offset will be negative (e.g., -5 if the subtitle appears 5 seconds after the audio.

With the measurements in hand, I run subtle with the beginning and ending offsets:

    % subtle -offset begin,end SRT file

subtle computes the equation of the line connecting the shifted times at the beginning and ending subtitles in the video. (The x-axis is the uncorrected subtitle times in seconds; the y-axis is the shifted times in seconds.) subtle then goes through the list of subtitles, substitutes each subtitle's start and stop times in the equation to get the shifted times, and, finally, regenerates the SRT file with the corrected times so that the subtitles are now synchronized with the audio track.

If the offset is constant throughout the video, subtle can be invoked with a single offset:

    % subtle -offset seconds SRT file

Going back to the two-offset case, subtle, by default, associates the beginning offset with the second subtitle in the file and the ending offset with the next-to-last subtitle. My thinking is that sometimes the first subtitle is for information purposes only and has no correlation with the audio track. Likewise for the last subtitle.

More accurate synchronization is possible by, instead, associating the offsets with specific subtitles, identified by their sequence numbers:

    %subtle -offset seq#>:begin,seq#:end SRT file

The corrected SRT file is written to standard output unless the "-output file" option is specified on the command line.


Invocation:

% subtle [-debug] [-help]
         [-apply] [-calculate] [-check]
         [-fix] [-insert position]
         [-line slope,y-intercept] [-merge]
         [-offset [seq#:]seconds[,[seq#:]seconds]]
         [-output file] [-renumber start]
         file1 [file2]

where

-debug
turns debug on.
-help
prints out a help message.
-apply
is a useless option. When the "-offset" operation is specified alone, subtle (i) calculates the slope and y-intercept of the line connecting the shifted times and (ii) applies the correction to all of the subtitles. If the "-offset" operation is specified along with the "-calculate" option, subtle calculates and displays the slope and y-intercept, but the correction is not applied to the subtitles. In other words, "-apply" is the default option for the "-offset" operation.
-calculate
displays the slope and y-intercept calculated for the "-offset" operation. The correction is not applied to the subtitles. If this option is specified on the command line, the "-offset" option must also be specified.
-check
checks the subtitles for (i) too many text lines, (ii) out-of-order sequence numbers, (iii) zero or negative display durations, and (iv) display times that overlap or even precede the immediately previous subtitles.
-fix
Not implemented yet.
-insert position
inserts the subtitles from one file into those of another file, at the specified position, and outputs the combined list to a third file. This may be useful in its own right at some point, but, for now, I use it to test the coherence of positions in the SRT_UTIL library package. Two SRT input files must be specified on the command line, either by two file names or by one file name and the "-stdin" option. The combined list of subtitles is output to standard output or to the file named in a "-output" option. The subtitles from the first SRT file are loaded into a list. The subtitles from the second SRT file are loaded into the same list at position P. For P in the range 1..N, where N is the number of subtitles in the first file, subtitles P..N from the first file are displaced by the number of subtitles in the second file. If P is 1, the second file's subtitles are prepended to the first file's subtitles. If P < 1 (zero or negative) or P > N, the second file's subtitles are appended to to the first file's subtitles.
-line slope,y-intercept
specifies a pre-computed equation of the line connecting shifted times. As in the "-offset" operation, the correction is applied to the subtitles and the corrected SRT file is written out.
-merge
merges the subtitles from one file with those of another file and outputs the combined list to a third file. Two SRT input files must be specified on the command line, either by two file names or by one file name and the "-stdin" option. The merged list of subtitles is output to standard output or to the file named in a "-output" option. Subtitles are pulled from each input file one by one: (i) the earliest subtitle is added to the merged list, (ii) the merge process advances to the next subtitle in the earliest subtitle's list, and (iii) the process repeats, comparing the new subtitle's start time with that of the not-yet-added subtitle from the other input list. The sequence numbers in the merged list are renumbered before the list of subtitles is output.
-offset [seq#:]seconds[,[seq#:]seconds]
specifies the differences in seconds, respectively, between the start times of of two subtitles and the corresponding times in the audio track. Ideally, the first subtitle should be early in the video and the second subtitle should be late in the video. A positive offset, M, means the subtitle appears M seconds before the audio, so the subtitle's start time must be adjusted (delayed) by adding M seconds to it. A negative offset, -M, means the subtitle appears M seconds after the audio, so the subtitle's start time must be adjusted (hastened) by subtracting M seconds from it. subtle calculates the equation of the line connecting the shifted times of the two subtitles, applies the correction to all of the subtitles, and writes the corrected SRT file to standard output (or the "-output" file). If "-calculate" is also specified on the command line, subtle calculates and displays the equation, but does not apply the correction to the subtitles. By default, the first offset is associated with the second subtitle in the SRT file; the second offset is associated with the next-to-last subtitle in the file. An offset can be linked to a specific subtitle by specifying the subtitle's sequence number, "seq#:".
-output file
specifies the name of a file to which output is to be written. By default, output is written to standard output.
-renumber start
renumbers the sequence numbers of all the subtitles. The very first subtitle is assigned this option's start number. The sequence number is incremented by 1 for each of the subsequent subtitles. If this option is accompanied by a "-offset" or "-line" option, the subtitle times are adjusted before the sequence numbers are renumbered.
-stdin
causes the SRT subtitles to be read from standard input instead of a disk file, useful if subtle is used in a command pipeline.
file1
specifies the SRT file to process.
file2
specifies a second SRT file to be used with the "-insert" and "-merge" operations.

Alex Measday  /  E-mail