pysubs2

Warnings

• gotcha The `pysubs2` command-line interface (CLI) works in-place by default, overwriting original subtitle files. Always use the `-o` or `--output-dir` options to specify an output location or pipe output to a new file to prevent accidental data loss.
  Fix: Use `python -m pysubs2 <infile> -o <outfile>` or `python -m pysubs2 --output-dir <directory> <files>` when using the CLI.
• gotcha When dealing with older or non-standard subtitle files, character encoding issues are common. `pysubs2` defaults to UTF-8, but you may need to explicitly specify a different `encoding` (e.g., 'latin-1', 'cp1252') during `load()` or `save()` operations. Version 1.7.0 introduced the `errors` parameter for better handling of unknown encodings.
  Fix: Pass the `encoding='your-encoding'` argument to `pysubs2.load()` and `subs.save()`. For `load()`, consider `errors='surrogateescape'` for pass-through of unsupported bytes.
• gotcha For frame-based formats like MicroDVD, proper retiming and conversion depend on knowing the video's framerate (FPS). If the FPS cannot be autodetected from the file, you must explicitly provide it using the `fps` argument during `pysubs2.load()` and `subs.save()` to ensure correct timing calculations.
  Fix: Always pass `fps=<framerate_value>` to `pysubs2.load()` and `subs.save()` when working with frame-based subtitle formats if the framerate is not reliably embedded or detected.
• gotcha Converting from rich formats (like Advanced SubStation Alpha, ASS) to simpler formats (like SubRip, SRT) may result in the loss of complex styling, override tags, and positioning information, as the target format might not support these features.
  Fix: Be aware of the limitations of the target format. If preserving styling is critical, consider sticking to ASS or using the CLI's `--srt-keep-html-tags` and `--srt-keep-ssa-tags` options, which allow some tags to pass through to SRT output (though not all styling can be converted).
• gotcha The `SSAEvent.plaintext` property is a convenience for getting text without override tags (`{\i1}`). However, directly *assigning* to `SSAEvent.plaintext` will strip *all* existing override tags from the subtitle, which might be an unintended loss of formatting.
  Fix: If you need to modify text while preserving or selectively changing override tags, work directly with the `SSAEvent.text` attribute and manually manage the override tags within the string. Use `plaintext` for read-only access when unformatted text is needed.

Install

• pip install pysubs2 Install with pip

Imports

• SSAFile

  from pysubs2 import SSAFile

  SSAFile is the main class for handling subtitle files.
• SSAEvent

  from pysubs2 import SSAEvent

  SSAEvent represents a single subtitle line.
• make_time

  from pysubs2 import make_time

  A utility function to create time values in milliseconds from H, M, S, MS.
• load

  from pysubs2 import load

  Function to load a subtitle file, an alias for SSAFile.load().
• pysubs2

  import pysubs2

  Commonly used for accessing top-level functions and classes (e.g., pysubs2.SSAFile, pysubs2.load).

Quickstart

This quickstart demonstrates how to load a subtitle file, add a new event, shift all event timings, modify an existing event's text, and save the result in a different format (ASS). It highlights the use of `pysubs2.load`, `pysubs2.SSAEvent`, `pysubs2.make_time`, and `subs.save` methods.

import pysubs2
import os

# Create a dummy SRT file for demonstration
dummy_srt_content = """
1
00:00:01,000 --> 00:00:03,000
Hello, world!

2
00:00:04,000 --> 00:00:06,000
This is a test subtitle.
"""
with open("input.srt", "w", encoding="utf-8") as f:
    f.write(dummy_srt_content)

# Load the subtitle file
subs = pysubs2.load("input.srt", encoding="utf-8")
print(f"Loaded {len(subs)} subtitles.")

# Add a new subtitle event
subs.append(pysubs2.SSAEvent(
    start=pysubs2.make_time(s=7),
    end=pysubs2.make_time(s=9, ms=500),
    text="A new subtitle added via pysubs2."
))

# Shift all subtitles by 1.5 seconds forward
subs.shift(s=1, ms=500)

# Modify an existing subtitle
if len(subs) > 0:
    subs[0].text = "(Modified) " + subs[0].text

# Save the modified subtitles to a new ASS file
output_filename = "output_modified.ass"
subs.save(output_filename, format_="ass", encoding="utf-8")
print(f"Modified subtitles saved to {output_filename}.")

# Clean up dummy files
os.remove("input.srt")
os.remove(output_filename)