pysublib.core — Core functions, classes and methods

This module implements core functions, classes and methods for use in the pysublib module.

Public functions

pysublib.core.detect_format([path[, encoding]][, lines])
Parameters:
  • path (string) – path to the subtitle file
  • encoding (string) – encoding to use to open the file with
Returns:

A string representation of a format, e.g. “SubRip”

Detects the file format under path using a specified encoding. If the encoding parameter is not specified, the automatic detection capability is used. Alternatively, it is possible to pass a list object parameter, lines, containing the individual lines of data. Either path, or lines parameters have to be specified.

pysublib.core.read(path[, encoding])
Parameters:
  • path (string) – path to the subtitle file
  • encoding (string) – encoding to use to open the file with
Returns:

An instance of the Document class.

Opens a subtitle file under the path using a specified encoding. If the encoding parameter is not specified, the automatic detection capability is used.

Obviously, PySubLib is capable of automatic file format detection, which allows it to correctly parse all the subtitles contained in the given file. Similarly to the file format, PySubLib is able to automatically detect the file encoding. However, it is better to instruct the read() method to use a specific encoding if it is known prior to opening the file to get a better performance.

Note

Invoking the read() method with the right encoding parameter results in approximately twice the fast performance opposed to the case when PySubLib has to detect the file encoding itself.

pysublib.core.write(doc)
Parameter:doc (Document) – document to write

Write subtitles in the format described by doc.file attribute, which is an instance of pysublib.file.SubtitleFile object.

Public objects

class pysublib.core.Subtitle([start[, end[, lines[, mode[, fps]]]]])
Parameters:
  • start (int or datetime.timedelta) – sets the start attribtue
  • end (int or datetime.timedelta) – sets the end attribute
  • lines (list or None) – sets the lines attribute
  • mode (string) – sets the mode attribute
  • fps (int or float) – sets the fps attribute

An object which represents a single subtitle. All parameters are optional.

start
Represents a start time or frame of the subtitle. In case the subtitle mode is set to frame, it has to be an integer value. In case of the time mode, the value must be an object of a datetime.timedelta class. The default value is datetime.timedelta(0).
end
Raises:ValueError

Represents an end time or frame of the subtitle. In case the subtitle mode is set to frame, it has to be an integer value. In case of the time mode, the value must be an object of a datetime.timedelta class. The default value is datetime.timedelta(0).

Note

The value of this attribute cannot be lesser than the value of the start attribute, in such case a ValueError exception is raised.

duration

Value representing the duration of time/frame in which the subtitle is displayed on the screen. Simply put, it is a difference between end and start attributes.

Note

This attribute is actually a property – if its value is set to some value, the end attribute will be calculated based on the passed value and the start attribute. For example:

>>> import pysublib
>>> sub = pysublib.Subtitle(start=datetime.timedelta(seconds=1))
>>> sub.duration = datetime.timedelta(seconds=5)
>>> print sub.end
0:00:06
duration_frame
A property, which returns the duration represented in frames. In case the subtitle’s mode is set to pysublib.MODES["time"], the value will be calculated based on the value of the fps attribtue. See also duration.
duration_time
Analogous to duration_frame.
lines
A list of string values representing individual subtitle lines. The default value is None, which in turn means an empty list.
mode
String representing a subtitle mode. Its value should be set to one of the values defined in MODES attribute. The default value is pysublib.MODES["time"].
fps
Value representing a subtitle framerate. It is used in conversions between times and frames. Its value should be set to one of the values defined in FPS attribute. The default value is pysublib.FPS[24].
shift(value)
Parameter:value (int or datetime.timedelta) – value to shift the subtitle by

Shifts the subtitle’s start and end values by a specified value. The value has to be either of type int or datetime.timedelta depending on the subtitle mode.

shift_frame(value)
Parameter:value (int) – value to shift the subtitle by

Shifts the subtitle’s start and end values by a specified value, which must be of an int type. If the subtitle’s mode is set to pysublib.MODES["time"], the value is calculated via subtitles’s fps attribute.

shift_time(value)
Parameter:value (datetime.timedelta) – value to shift the subtitle by

Shifts the subtitle’s start and end values by a specified value, which must be of an datetime.timedelta type. If the subtitle’s mode is set to pysublib.MODES["frame"], the value is calculated via subtitles’s fps attribute.

class pysublib.core.Document([file[, subtitles]])
Parameters:
  • file (SubtitleFile or None) – object providing methods to manipulate a given subtitle file format
  • subtitles (list or None) – list of Subtitle objects

Class representing all the subtitles, providing methods for mass synchronization. This class is a simple iterator, which iterates through the subtitles attribute.

file
Attribute pointing at the SubtitleFile class instance, which provides methods for parsing and writing a specific subtitle file format.
subtitles
List of Subtitle objects.
__iter__()
Allows to iterate through the Document class instance like with other common iterator objects.
__len__()
Returns the number of subtitles in the document. This allows for use of len() builtin function.
shift(value[, start[, end]])
Parameters:
  • value (int or datetime.timedelta) – value to shift the subtitles by
  • start (int or None) – first subtitle to shift
  • end (int or None) – last subtitle to shift

Shift the specified subtitles by value. For further information see Subtitle.shift().

shift_frame(value[, start[, end]])
Parameters:
  • value (int) – value to shift the subtitles by
  • start (int or None) – first subtitle to shift
  • end (int or None) – last subtitle to shift

Shift the specified subtitles by value. For further information see Subtitle.shift_frame().

shift_time(value[, start[, end]])
Parameters:
  • value (datetime.timedelta) – value to shift the subtitles by
  • start (int or None) – first subtitle to shift
  • end (int or None) – last subtitle to shift

Shift the specified subtitles by value. For further information see Subtitle.shift_time().

Table Of Contents

Previous topic

pysublib — Manipulate subtitle files easily

Next topic

pysublib.calc — Convert times and frames values

This Page