0
# Command Line Tools
1
2
Command-line interface for batch subtitle processing. The `srt` command provides utilities for common subtitle operations including time shifting, framerate conversion, file splitting, and line breaking.
3
4
## Installation
5
6
The command-line tool is automatically installed with the pysrt package:
7
8
```bash
9
pip install pysrt
10
```
11
12
This makes the `srt` command available in your terminal.
13
14
## Capabilities
15
16
### Global Options
17
18
Options available for all commands.
19
20
```bash { .api }
21
srt [global_options] <command> [command_options] <file>
22
23
Global Options:
24
-i, --in-place Edit file in-place, saving backup as file.bak
25
-e, --output-encoding Set output file encoding
26
-v, --version Show version information
27
-h, --help Show help message
28
```
29
30
### Time Shifting
31
32
Shift all subtitles by a specified time offset.
33
34
```bash { .api }
35
srt shift [options] <offset> <file>
36
37
Arguments:
38
offset Time offset in format: [-][Hh][Mm]S[s][MSms]
39
file Input subtitle file
40
41
Examples:
42
srt shift 2s movie.srt # 2 seconds forward
43
srt shift -1m30s movie.srt # 1 minute 30 seconds backward
44
srt shift 500ms movie.srt # 500 milliseconds forward
45
srt -i shift -2s500ms movie.srt # 2.5 seconds backward (in-place)
46
```
47
48
### Framerate Conversion
49
50
Convert subtitles between different framerates.
51
52
```bash { .api }
53
srt rate [options] <initial_fps> <final_fps> <file>
54
55
Arguments:
56
initial_fps Original framerate (e.g., 23.976)
57
final_fps Target framerate (e.g., 25)
58
file Input subtitle file
59
60
Examples:
61
srt rate 23.976 25 movie.srt # Convert 23.976fps to 25fps
62
srt -i rate 25 23.976 movie.srt # Convert 25fps to 23.976fps (in-place)
63
srt rate 30 24 movie.srt > slow_movie.srt # Convert and save to new file
64
```
65
66
### File Splitting
67
68
Split subtitle files into multiple parts.
69
70
```bash { .api }
71
srt split [options] <duration>... <file>
72
73
Arguments:
74
duration Duration of each part in format: [Hh][Mm]S[s][MSms]
75
file Input subtitle file
76
77
Output:
78
Creates numbered files: basename.1.srt, basename.2.srt, etc.
79
80
Examples:
81
srt split 45m movie.srt # Split at 45 minutes
82
srt split 30m 30m movie.srt # Three parts: 0-30m, 30m-60m, 60m-end
83
srt split 1h30m movie.srt # Split at 1 hour 30 minutes
84
```
85
86
### Line Breaking
87
88
Break long subtitle lines at word boundaries.
89
90
```bash { .api }
91
srt break [options] <max_length> <file>
92
93
Arguments:
94
max_length Maximum characters per line
95
file Input subtitle file
96
97
Examples:
98
srt break 40 movie.srt # Break lines longer than 40 characters
99
srt -i break 32 movie.srt # Break lines (in-place edit)
100
srt break 50 movie.srt > formatted.srt # Break lines and save to new file
101
```
102
103
## Time Format Specification
104
105
All commands use a flexible time format for specifying durations and offsets:
106
107
```bash { .api }
108
Time Format: [-][Hh][Mm]S[s][MSms]
109
110
Components (all optional):
111
- Negative (backward) time
112
H, h Hours
113
M, m Minutes
114
S, s Seconds (default unit if no suffix)
115
MS, ms Milliseconds
116
117
Examples:
118
5 5 seconds
119
1m30s 1 minute 30 seconds
120
-2s500ms 2.5 seconds backward
121
1h15m 1 hour 15 minutes
122
750ms 750 milliseconds
123
2h30m45s 2 hours 30 minutes 45 seconds
124
```
125
126
## Usage Examples
127
128
### Basic Operations
129
130
```bash
131
# Simple time adjustments
132
srt shift 2s movie.srt > delayed_movie.srt
133
srt shift -1s500ms movie.srt > advanced_movie.srt
134
135
# In-place editing with backup
136
srt -i shift 3s movie.srt # Creates movie.srt.bak
137
138
# Framerate conversion for different media
139
srt rate 23.976 25 ntsc_movie.srt > pal_movie.srt
140
```
141
142
### File Processing Workflows
143
144
```bash
145
# Split long movie into parts
146
srt split 50m long_movie.srt
147
# Creates: long_movie.1.srt, long_movie.2.srt, long_movie.3.srt
148
149
# Format subtitles for small screens
150
srt break 30 movie.srt > mobile_movie.srt
151
152
# Chain operations using pipes
153
srt shift 1s movie.srt | srt break 40 > processed_movie.srt
154
```
155
156
### Encoding Handling
157
158
```bash
159
# Convert encoding while processing
160
srt -e latin1 shift 2s utf8_movie.srt > latin1_movie.srt
161
162
# Process files with specific input encoding
163
# (Automatic detection usually works, but can be overridden in code)
164
```
165
166
### Batch Processing
167
168
```bash
169
# Process multiple files
170
for file in *.srt; do
171
srt -i shift 1s500ms "$file"
172
done
173
174
# Split all movies in directory
175
for movie in *.srt; do
176
srt split 45m "$movie"
177
done
178
179
# Convert all subtitles for different framerate
180
for sub in *.srt; do
181
srt rate 25 23.976 "$sub" > "ntsc_${sub}"
182
done
183
```
184
185
### Advanced Examples
186
187
```bash
188
# Complex timing adjustment
189
srt shift -2m30s500ms movie.srt > synced_movie.srt
190
191
# Multi-part processing
192
srt split 1h movie.srt # Split into 1-hour parts
193
srt -i shift 500ms movie.1.srt # Adjust first part
194
srt -i shift 1s movie.2.srt # Different adjustment for second part
195
196
# Format for specific display requirements
197
srt break 25 movie.srt | srt shift 2s > tv_movie.srt
198
199
# Prepare subtitles for different distributions
200
srt rate 25 23.976 movie.srt > movie_ntsc.srt # NTSC version
201
srt rate 25 24 movie.srt > movie_film.srt # Film version
202
srt -e latin1 shift 0 movie.srt > movie_compat.srt # Compatibility version
203
```
204
205
## Error Handling
206
207
The command-line tool provides informative error messages:
208
209
```bash
210
# File not found
211
$ srt shift 2s nonexistent.srt
212
No such file nonexistent.srt
213
214
# Invalid time format
215
$ srt shift 99x movie.srt
216
# Will show usage help and error message
217
218
# Encoding issues
219
$ srt -e invalid_encoding shift 1s movie.srt
220
# Will report encoding error
221
```
222
223
## Integration with Scripts
224
225
### Shell Scripting
226
227
```bash
228
#!/bin/bash
229
# Subtitle processing script
230
231
input_file="$1"
232
delay="${2:-2s}" # Default 2 second delay
233
234
if [[ ! -f "$input_file" ]]; then
235
echo "Error: File $input_file not found"
236
exit 1
237
fi
238
239
# Create processed version
240
echo "Processing $input_file with $delay delay..."
241
srt shift "$delay" "$input_file" > "processed_$(basename "$input_file")"
242
243
# Also create formatted version
244
srt break 40 "processed_$(basename "$input_file")" > "formatted_$(basename "$input_file")"
245
246
echo "Created processed and formatted versions"
247
```
248
249
### Python Integration
250
251
```python
252
import subprocess
253
import sys
254
255
def process_subtitle_cli(input_file, delay="2s"):
256
"""Process subtitle using command-line tool"""
257
try:
258
result = subprocess.run([
259
'srt', 'shift', delay, input_file
260
], capture_output=True, text=True, check=True)
261
return result.stdout
262
except subprocess.CalledProcessError as e:
263
print(f"Error processing subtitle: {e.stderr}")
264
return None
265
266
# Usage
267
processed_content = process_subtitle_cli('movie.srt', '1s500ms')
268
if processed_content:
269
with open('processed_movie.srt', 'w') as f:
270
f.write(processed_content)
271
```
272
273
### Makefile Integration
274
275
```makefile
276
# Subtitle processing Makefile
277
278
SUBTITLES = $(wildcard *.srt)
279
PROCESSED = $(SUBTITLES:.srt=_processed.srt)
280
MOBILE = $(SUBTITLES:.srt=_mobile.srt)
281
282
# Process all subtitles with 2 second delay
283
processed: $(PROCESSED)
284
285
%_processed.srt: %.srt
286
srt shift 2s $< > $@
287
288
# Create mobile-friendly versions
289
mobile: $(MOBILE)
290
291
%_mobile.srt: %.srt
292
srt break 30 $< > $@
293
294
# Clean up generated files
295
clean:
296
rm -f *_processed.srt *_mobile.srt
297
298
.PHONY: processed mobile clean
299
```
300
301
## Comparison with Library Usage
302
303
While the command-line tool is convenient for batch operations, the Python library offers more flexibility:
304
305
```python
306
# Command line equivalent: srt shift 2s movie.srt
307
import pysrt
308
subs = pysrt.open('movie.srt')
309
subs.shift(seconds=2)
310
subs.save('processed_movie.srt')
311
312
# Command line equivalent: srt rate 25 23.976 movie.srt
313
subs = pysrt.open('movie.srt')
314
subs.shift(ratio=23.976/25)
315
subs.save('converted_movie.srt')
316
317
# More complex operations not available via CLI
318
subs = pysrt.open('movie.srt')
319
for item in subs:
320
if item.duration.ordinal < 1000: # Less than 1 second
321
item.end += pysrt.SubRipTime(milliseconds=500)
322
subs.save('extended_movie.srt')
323
```