TXT to SRT Subtitle Converter
Overview
Convert TXT subtitle files to standard UTF-8 SRT format. The skill handles encoding
detection (UTF-16LE/UTF-8/GBK/etc.) and multiple common subtitle layout patterns
automatically.
Quick Start
To convert a TXT subtitle file:
python3 scripts/convert.py <input.txt> [output.srt] [options]
If no output path is specified, the output file is created by replacing the input
file's extension with .srt.
Workflow
Step 1: Identify the input file
The user typically provides a path to a .txt file containing subtitle data.
Read the first 5-10 lines of the file to assess the format before invoking
the script, so any issues can be diagnosed early.
Step 2: Run the conversion
Execute the script with the input path. The script auto-detects encoding and
format. Use --encoding only if auto-detection fails or the user specifies
an encoding explicitly.
Common command patterns:
# Basic conversion (output to same directory, .srt extension)
python3 scripts/convert.py /path/to/subtitles.txt
# Specify output path
python3 scripts/convert.py /path/to/subtitles.txt /output/path/output.srt
# Force encoding (e.g., GBK for Chinese legacy files)
python3 scripts/convert.py /path/to/subtitles.txt --encoding gbk
# Remove HTML-style tags from subtitle text
python3 scripts/convert.py /path/to/subtitles.txt --clean
# Validate only, no output
python3 scripts/convert.py /path/to/subtitles.txt --validate-only
Step 3: Report results
After conversion, report:
- The detected encoding and format
- Number of subtitle blocks converted
- Time range of the subtitles
- Any validation warnings (overlaps, long durations, empty text)
- Output file path
Step 4: Validate output (optional)
Open the generated .srt file and check the first few and last few blocks
to confirm the conversion is correct.
Supported Input Formats
The script auto-detects which format the input file uses:
Format 1: SRT-like numbered blocks
1
00:00:00,000 --> 00:00:21,041
Subtitle text here
2
00:00:53,875 --> 00:00:59,250
More subtitle text
The most common format. Often encoded as UTF-16LE (common in East Asian
subtitle communities). The script handles the encoding conversion
transparently.
Format 2: Timestamp-first lines
00:01:23,456 --> 00:01:25,789 This is the subtitle text
00:01:26,000 --> 00:01:28,500 Next subtitle line
Format 3: Bracketed timestamps
[00:01:23] Subtitle text here
[00:01:26] Next subtitle text
For bracket format, end times are calculated from the next subtitle's start
time (capped at 7 seconds gap, minimum 1 second duration).
Edge Cases & Troubleshooting
- Garbled Chinese text: Usually encoding issue. Try
--encoding gbkor
--encoding utf-16-le. - No subtitles detected: The format may be unsupported. Check what the
first 10 lines look like and adapt the approach manually. - Overlapping timestamps: The script warns about overlaps. Manual
editing of the source may be needed. - Multi-line subtitles: The SRT-like parser correctly preserves
multi-line subtitle text blocks.
Script Location
scripts/convert.py — Self-contained Python 3 script with no external
dependencies beyond the standard library. Optionally uses chardet for
improved encoding detection if available.
