srt (SubRip) Format

pytitle.srt.subtitle

class pytitle.srt.subtitle.SrtSubtitle(path: Optional[Union[str, bytes, PathLike]] = None, lines: Optional[List[Line]] = None, encoding: Optional[str] = 'utf-8')[source]

Bases: object

Subtitle object for .srt formatted subtitles

classmethod open(path: ~typing.Union[str, bytes, ~os.PathLike], encoding: ~typing.Optional[str] = 'utf-8', use_chardet: bool = False, fallback_encodings: ~pytitle.srt.types.Encodings = <pytitle.srt.types.Encodings object>, **kwargs) → SrtSubtitle[source]

Open subtitle file from a path

Parameters

path (str) – the path to the subtitle file
encoding (Optional[str]) – the encoding of the subtitle file
use_chardet (bool) – if True, use chardet to detect the encoding if ‘utf-8’ failed

Returns

the subtitle object

Return type

SrtSubtitle

classmethod parse(filestring: str) → List[Line][source]

Parse the string formatted as a .srt file

Parameters: filestring (str) – the string of the subtitle file
Returns: a list of Line objects
Return type: List[Line]

save(path: Optional[Union[str, bytes, PathLike]] = None, encoding: Optional[str] = None) → None[source]

Save subtitle to a path

Parameters

path (str) – the path to save the subtitle to
encoding (str) – the encoding of the subtitle file

Returns

None

Return type

None

shift(shift_by: Timestamp, indexes: Optional[List[int]] = None, lines: Optional[List[Line]] = None, backward: bool = False, start: bool = True, end: bool = True) → None[source]

Shift the timing of one or multiple lines of subtitle, backward or forward

Parameters

shift_by (Timestamp) – Timestamp object to shift by
indexes (List[int]) – the index of a lines to shift, all lines if None
lines (List[Line]) – the lines to shift, all lines if None
backward (bool) – if True, shift backward, otherwise forward

Returns

None

Return type

None

shift_forward(hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0, index: Optional[Union[int, List[int]]] = None, lines: Optional[List[Line]] = None) → None[source]

Shift the timing of a line by index or all: lines of subtitle forward by hour, minutes, seconds, milliseconds

shortcut for SrtSubtitle.shift(…)

Parameters

hours (int) – the number of hours to shift
minutes (int) – the number of minutes to shift
seconds (int) – the number of seconds to shift
milliseconds (int) – the number of milliseconds to shift
index (Union[int, List[int]]) – the index of the line to shift, all lines if None

Lines

the lines to shift, all lines if None

Returns

None

Return type

None

shift_backward(hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0, index: Optional[Union[int, List[int]]] = None, lines: Optional[List[Line]] = None) → None[source]

Shift the timing of a line by index or all: lines of subtitle backward by hour, minutes, seconds, milliseconds

shortcut for SrtSubtitle.shift(…)

Parameters

hours (int) – the number of hours to shift
minutes (int) – the number of minutes to shift
seconds (int) – the number of seconds to shift
milliseconds (int) – the number of milliseconds to shift
index (Union[int, List[int]]) – the index of the line to shift, all lines if None

Lines

the lines to shift, all lines if None

Returns

None

Return type

None

search(keyword: str, filters: Optional[str] = None) → Line[source]: Serach a keyword in text lines, duration in timings and line index

reindex() → None[source]: Reindexes the subtitle lines by timing

remove_italic()[source]: Remove italic tags from subtitle

fix_italic()[source]: Fix italic tags from subtitle

fix_arabic()[source]: Fix arabic/persian characters in subtitle

fix_question_mark()[source]: Fix question marks for arabic/persian subtitles

find_overlaps() → List[Line][source]: Find overlapping lines in subtitle

property output: str

pytitle.srt.types

class pytitle.srt.types.Timestamp(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

The Timestamp object is used to store the start or end of a subtitle the Timestamp is rendered as 00:00:00,000 from the output property

hours: int = 0

minutes: int = 0

seconds: int = 0

milliseconds: int = 0

property output: str: output the timestamp in the format 00:00:00,000

classmethod from_string(timestr: str) → Timestamp[source]

Create a Timestamp object from a string

Parameters: timestr (srt) – the string to create the Timestamp from in the format of 00:00:00,000
Returns: the Timestamp object
Return type: Timestamp

get_value(property: Literal['hours', 'minutes', 'seconds', 'milliseconds']) → str[source]

get the hour, minute, second or millisecond values properly formatted

Parameters: property (str) – the property to get the value of
Returns: the value of the property
Return type: str

beautify(property: str, optimal_length: int = 2, right_append: bool = False)[source]

Beautify the property value

adds 0s to the left or right side of the each property to change them into the right format that is: 00:00:00,000

Parameters

optimal_length (int) – the length that the property should be, 2 or 3 based on the type
right_append (bool) – add the 0s to the right side of the property instead of the left

Returns

the property value with the right format

Return type

str

class pytitle.srt.types.Timing(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Timing object for a subtitle Timing consists of a start and end Timestamp and is rendered as 00:00:00,000 –> 00:00:00,000 from the output method

start: Timestamp

end: Timestamp

property output: str: output the timing in the format 00:00:00,000 –> 00:00:00,000

classmethod from_string(start: str, end: str) → Timing[source]

Create a Timing object from a string the start and end should be in the format of 00:00:00,000

Parameters

start (str) – the start Timestamp of the subtitle
end (str) – the end Timestamp of the subtitle

Returns

the Timing object

Return type

Timing

shift(shift_by: Timestamp, backward: bool = False, start: bool = True, end: bool = True) → None[source]

Shift the timing by a Timestamp

Parameters

shift_by (Timestamp) – the Timestamp to shift the timing by
backward (bool) – shift the timing backward instead of forward
start (bool) – shift the start Timestamp
end (bool) – shift the end Timestamp

Returns

None

Return type

None

class pytitle.srt.types.Line(*args: Any, **kwargs: Any)[source]

Bases: BaseModel

Line object for a subtitle

Line consists of index, timing and text an example formatted line would be:

1
00:00:00,000 --> 00:00:00,000
This is a subtitle

index: int

timing: Timing

text: Optional[str] = ''

property output: str

output the line in the format of:

1
00:00:00,000 --> 00:00:00,000
This is a subtitle

classmethod from_string(linestring: str) → Line[source]

Create a Line object from a string

Parameters: linestring (str) – the string to create the Line from
Returns: the Line object
Return type: Line

classmethod get_lines(lines: List[Line], index: List[int], check_contains: bool = False) → List[Line][source]

get line objects from index of them

Parameters

lines (List[int]) – the index of the lines to get
index (List[int]) – the index of the lines to get
check_contains (bool) – check if all the indexes are in the lines

Returns

the lines

Return type

List[Line]

class pytitle.srt.types.Encodings(encodings: Optional[List[str]] = None)[source]

Bases: object

Encodings class.

UTF_8 = 'utf-8'

CP1252 = 'cp1252'

CP1256 = 'cp1256'

UTF_16 = 'utf-16'

UTF_32 = 'utf-32'

get_encoding(index: int) → Tuple[Optional[str], Optional[int]][source]

Get encoding by index.

Parameters: index (int) – the index of the encoding
Returns: the encoding and the index of the next encoding
Return type: Tuple[Optional[Encoding], Optional[int]]