rustling.srt#

SRT (SubRip Subtitle) data handling.

Package Contents#

class rustling.srt.Utterance(*, index: int, line: str, time_marks: tuple[int, int])#

A single subtitle block within an SRT file.

property index: int#

1-based sequence number from the SRT file.

property line: str#

The subtitle text.

property time_marks: tuple[int, int]#

Start and end time in milliseconds as a tuple.

class rustling.srt.SRT#

SRT (SubRip Subtitle) data reader.

classmethod from_strs(strs: Sequence[str], ids: Sequence[str] | None = None, parallel: bool = True) → SRT#

Parse SRT data from in-memory strings.

classmethod from_files(paths: Sequence[str | os.PathLike[str]], *, parallel: bool = True) → SRT#

Load SRT data from file paths.

classmethod from_dir(path: str | os.PathLike[str], *, match: str | None = None, extension: str = '.srt', parallel: bool = True) → SRT#

Recursively load SRT data from a directory.

classmethod from_zip(path: str | os.PathLike[str], *, match: str | None = None, extension: str = '.srt', parallel: bool = True) → SRT#

Load SRT data from a ZIP archive.

classmethod from_git(url: str, *, rev: str | None = None, depth: int | None = None, match: str | None = None, extension: str = '.srt', cache_dir: str | os.PathLike[str] | None = None, force_download: bool = False, parallel: bool = True) → SRT#

Load SRT data from a git repository.

Clones the repository (or uses a cached clone) and parses all matching files from the resulting directory.

Parameters:

  • url – Git repository URL.

  • rev – Branch, tag, or commit hash. If None, uses the repository’s default branch.

  • depth – Clone depth. Defaults to 1 (shallow clone). Ignored when rev is a commit hash.

  • match – Regex pattern to include only matching file paths.

  • extension – File extension to filter by (default: “.srt”).

  • cache_dir – Directory for caching cloned repositories. Defaults to ~/.rustling/cache/.

  • force_download – If True, re-clone even if a cached copy exists.

  • parallel – If True, use parallel processing.

Returns:

A new SRT reader with the parsed data.

classmethod from_url(url: str, *, match: str | None = None, extension: str = '.srt', cache_dir: str | os.PathLike[str] | None = None, force_download: bool = False, parallel: bool = True) → SRT#

Load SRT data from a URL.

Downloads the file (or uses a cached copy) and parses it. ZIP files are automatically detected and extracted.

Parameters:

  • url – URL to download from.

  • match – Regex pattern to include only matching file paths (applicable for ZIP files).

  • extension – File extension to filter by (default: “.srt”, applicable for ZIP files).

  • cache_dir – Directory for caching downloads. Defaults to ~/.rustling/cache/.

  • force_download – If True, re-download even if a cached copy exists.

  • parallel – If True, use parallel processing.

Returns:

A new SRT reader with the parsed data.

property file_paths: list[str]#

Return the list of file paths.

property n_files: int#

Return the number of files.

utterances() → list[Utterance]#

Return all subtitle blocks across all files as a flat list.

to_strs() → list[str]#

Return SRT strings, one per file.

to_chat_strs() → list[str]#

Return CHAT format strings, one per file.

to_chat() → rustling.chat.CHAT#

Convert to a CHAT object.

Each SRT file produces one CHAT file with a default participant code "SPK" (Speaker).

Returns:

A CHAT object.

to_chat_files(dir_path: str | os.PathLike[str], /, *, filenames: Sequence[str] | None = None) → None#

Write CHAT (.cha) files to a directory.

Parameters:

  • dir_path – Directory path to write .cha files to.

  • filenames – Custom filenames for the output files.

Raises:

  • ValueError – If filenames count doesn’t match file count.

  • IOError – If writing fails.

to_elan_strs() → list[str]#

Return EAF XML strings, one per file.

to_elan() → rustling.elan.ELAN#

Convert to an ELAN object.

Each SRT file produces one ELAN file with a single tier named "SPK" (Speaker).

Returns:

A ELAN object.

to_elan_files(dir_path: str | os.PathLike[str], /, *, filenames: Sequence[str] | None = None) → None#

Write ELAN (.eaf) files to a directory.

Parameters:

  • dir_path – Directory path to write .eaf files to.

  • filenames – Custom filenames for the output files.

Raises:

  • ValueError – If filenames count doesn’t match file count.

  • IOError – If writing fails.

to_textgrid_strs() → list[str]#

Return TextGrid format strings, one per file.

to_textgrid() → rustling.textgrid.TextGrid#

Convert to a TextGrid object.

to_textgrid_files(dir_path: str | os.PathLike[str], /, *, filenames: Sequence[str] | None = None) → None#

Write TextGrid (.TextGrid) files to a directory.

to_files(dir_path: str | os.PathLike[str], /, *, filenames: Sequence[str] | None = None) → None#

Write SRT files to a directory.

Parameters:

  • dir_path – Directory path to write .srt files to.

  • filenames – Custom filenames for the output files.

Raises:

  • ValueError – If filenames count doesn’t match file count.

  • IOError – If writing fails.

append(other: SRT, /) → None#

Append data from another SRT reader.

append_left(other: SRT, /) → None#

Left-append data from another SRT reader, preserving order.

extend(others: Sequence[SRT], /) → None#

Extend data from multiple SRT readers.

pop() → SRT#

Remove and return the last file as a new SRT reader.

pop_left() → SRT#

Remove and return the first file as a new SRT reader.

clear() → None#

Remove all data from this reader.

rustling.srt.read_srt(path: str | os.PathLike[str], *, cls: type[SRT] = SRT) → SRT#

Read SRT data.

Parameters:

  • path – Path to a .zip file, a local directory containing .srt files, a single .srt file, a git repository URL (ending in .git), or an HTTP/HTTPS URL.

  • cls – The class used to create the reader. Must be SRT or a subclass of it.

Returns:

An SRT instance.

Raises:

  • TypeError – If cls is not SRT or a subclass of it.

  • ValueError – If path does not point to a recognized source.