PYSUBS2(1)

🎀 pysubs2 🎀

okay bestie, gather round, because this is the glow-up your subtitle files have been waiting for 💅

pysubs2</purpose> — a command-line tool to convert and retime subtitle files. that's it, that's the whole vibe, and it ate. ✨

---

✨ DESCRIPTION ✨

here's the whole usage situation, copied exactly because we do NOT play with flags around here:

usage: pysubs2 [-h] [-v] [-f {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}]
              [-t {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}] [--input-enc ENCODING] [--output-enc ENCODING] [--enc-error-handling {strict,surrogateescape}] [--fps FPS] [-o DIR] [--clean]
              [--verbose] [--shift TIME | --shift-back TIME | --transform-framerate FPS1 FPS2] [--srt-keep-unknown-html-tags] [--srt-keep-html-tags] [--srt-keep-ssa-tags]
              [--sub-no-write-fps-declaration] [FILE ...]

The pysubs2 CLI for processing subtitle files.

https://github.com/tkarabela/pysubs2 — go follow the source, it's iconic 👑

---

🌸 positional arguments 🌸

• FILE — your input subtitle files, bestie. they can be in SubStation Alpha (*.ass, *.ssa), SubRip (*.srt), MicroDVD (*.sub) or any other supported format. and here's the cute part: if you don't name any files at all, pysubs2 goes full pipe mode — it reads from standard input and writes to standard output. main character energy fr fr 🫶

---

💖 options 💖

• -h, --help — shows this help message and dips. classic. ✨
• -v, --version — prints the program's version number and exits. short and sweet, no cap.
• -f {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}, --from {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt} — by default, the subtitle format is detected straight from the file. this option lets you skip autodetection and force a specific format. ngl, generally you should never need it. it's giving "emergency button" 💀
• -t {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt}, --to {srt,ass,ssa,microdvd,json,mpl2,tmp,vtt} — converts subtitle files to the given format. by default, each file is saved in its original format. lowkey the whole point of the tool 🌈
• --input-enc ENCODING — character encoding for input files. by default, UTF-8 is used for both input and output. simple, clean, obsessed 💖
• --output-enc ENCODING — character encoding for output files. by default it's the same as the input encoding. ⚠️ real talk though: if you wanna convert between encodings, make sure --input-enc is set correctly! otherwise your output files will probably be corrupted. it's a genuinely good idea to back up your files or use the -o option. don't be the girl who loses her subs 😭
• --enc-error-handling {strict,surrogateescape} — character encoding error handling for input and output. defaults to 'surrogateescape', which passes through unrecognized characters to output unchanged. use 'strict' if you want the command to fail when it hits a character that's incompatible with the selected input/output encoding. pick your fighter ⭐
• --fps FPS — this argument specifies framerate for MicroDVD files. by default, framerate is detected from the file. use this when the framerate spec is missing, or when you want to force a different framerate. 🦋
• -o DIR, --output-dir DIR — use this to save all files to the given directory. by default, every file is saved to its parent directory, ie. unless it's being saved in a different subtitle format (and thus with a different file extension), it overwrites the original file. just so you know. 🙈
• --clean — attempts to remove non-essential subtitles (eg. karaoke, SSA drawing tags), and strips styling information when saving to non-SSA formats. decluttering, we love to see it ✨
• --verbose — prints misc logging. chatterbox mode, but make it useful 💬
• --shift TIME — delays all subtitles by the given time amount. time is specified like this: '1m30s', '0.5s', ... 🕐
• --shift-back TIME — the opposite of --shift (subtitles will appear sooner). rewind era 💫
• --transform-framerate FPS1 FPS2 — multiplies all timestamps by the FPS1/FPS2 ratio. math girlies rise 🔥

---

🎀 optional arguments (SRT) 🎀

• --srt-keep-unknown-html-tags — (input) do not strip unrecognized HTML tags. 🫶
• --srt-keep-html-tags — (input) do not convert HTML tags to SubStation internally; this implies --srt-keep-unknown-html-tags. chain reaction, iconic 💅
• --srt-keep-ssa-tags — (output) do not convert/strip SubStation tags for output. 🌸

---

💜 optional arguments (MicroDVD) 💜

• --sub-no-write-fps-declaration — (output) omit writing FPS as the first zero-length subtitle. bye bye little declaration line 👋

---

🌟 usage examples 🌟

the moment you've all been waiting for — copy these, run these, slay:

python -m pysubs2 --to srt *.ass
python -m pysubs2 --to srt --clean *.ass
python -m pysubs2 --to microdvd --fps 23.976 *.ass
python -m pysubs2 --shift 0.3s *.srt
python -m pysubs2 --shift 0.3s <my_file.srt >retimed_file.srt
python -m pysubs2 --shift-back 0.3s --output-dir retimed *.srt
python -m pysubs2 --transform-framerate 25 23.976 *.srt

see? retiming, converting, piping, all of it. you're basically a wizard now 🧚

---

🦋 SEE ALSO 🦋

The full documentation for pysubs2 is maintained as a Texinfo manual. If the info and pysubs2 programs are properly installed at your site, the command

info pysubs2

should give you access to the complete manual. go read the lore, iykyk 📖✨

---

and that's the whole page, bestie! this is pysubs2 1.7.1, from June 2024, manual section 1, User Commands — so if you see that version and date floating around, you know exactly where you are. stay converted, stay retimed, mwah 💋💖