pysubs2 Documentation - media.readthedocs.org · This tutorial will show you how to use most of what pysubs2 library has to offer. ... Aegisub, you will hopefully ﬁnd the API quite

pysubs2 DocumentationRelease 0.2.2

Tomas Karabela

Jul 22, 2017

Contents

1 Documentation 31.1 Using pysubs2 from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Let’s import pysubs2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2 License 19

Python Module Index 21

i

ii

pysubs2 Documentation, Release 0.2.2

pysubs2 is a Python library for editing subtitle files. It’s based on SubStation Alpha, the native format of Aegisub; italso supports SubRip and MicroDVD formats. There is a small CLI tool for batch conversion and retiming.

import pysubs2subs = pysubs2.load("my_subtitles.ass", encoding="utf-8")subs.shift(s=2.5)for line in subs:

line.text = "{\\be1}" + line.textsubs.save("my_subtitles_edited.ass")

pysubs2 works with Python 2.7 and 3.3+. It’s available under the MIT license (see bottom of the page).

To install pysubs2, just use pip: pip install pysubs2. You can also clone the GitHub repository and install viapython setup.py install.

If you find a bug or have something to say, please let me know via GitHub or email (tkarabela at seznam dot cz). Yourfeedback is much appreciated. Thanks!

Contents 1

http://www.aegisub.org/

https://pypi.python.org/pypi/pip

https://github.com/tkarabela/pysubs2/

https://github.com/tkarabela/pysubs2/issues


2 Contents

CHAPTER 1

Documentation

Using pysubs2 from the Command Line

Do you want to convert subtitle files from one format to another, or do simple retiming? You can use pysubs2 CLI,which is invoked by executing the pysubs2 module: python -m pysubs2.

See python -m pysubs2 --help for usage. Here are some examples:

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

Warning: By default, the script works in-place; original files are overwritten. You can use the -o/--output-dir option to specify output directory or process files in single-file mode (python -m pysubs2<infile >outfile).

Let’s import pysubs2

This tutorial will show you how to use most of what pysubs2 library has to offer. If you are familiar with Python andAegisub, you will hopefully find the API quite intuitive.

If you want to follow along in your REPL, make sure to have Python 3 and pysubs2 installed.

Let’s settle on a simple subtitle file first.

>>> SIMPLE_FILE = """\... 1... 00:00:00,000 --> 00:01:00,000

3


... Once upon a time,

...

... 2

... 00:01:00,000 --> 00:02:00,000

... there was a SubRip file

... with two subtitles.

... """>>> with open("subtitles.srt", "w") as fp:... fp.write(SIMPLE_FILE)

Now that we have a real file on the harddrive, let’s import pysubs2 and load it.

>>> import pysubs2>>> subs = pysubs2.load("subtitles.srt")>>> subs<SSAFile with 2 events and 1 styles, last timestamp 0:02:00>

Tip: pysubs2 is written with Python 3 in mind, meaning that it speaks Unicode. By default, it uses UTF-8 whenreading and writing files. Use the encoding keyword argument in case you need something else.

Now we have a subtitle file, the pysubs2.SSAFile object. It has two “events”, ie. subtitles. You can treat subsas a list:

>>> subs[0].text"Once upon a time,">>> for line in subs:... print(line.text)"Once upon a time,""there was a SubRip file\\Nwith two subtitles."

Individual subtitles are pysubs2.SSAEvent objects and have the attributes you’d expect, like start, end andtext. Notice that the second subtitle text doesn’t contain a newline, but literal “backlash N”, which is how SubStationrepresents newlines. There could also be override tags like {\i1} for italics.

Tip: If you don’t entertain SubStation, there is also a pysubs2.SSAEvent.plaintext property which hidesoverride tags and translates newlines for you. Be warned, however, that writing to this property throws away anyoverride tags.

Let’s have a look at the timestamps.

>>> subs[1].start60000

That is 60,000 milliseconds, or one minute. pysubs2 uses plain int milliseconds for time. Since you probably don’twant to convert all times to milliseconds by hand, there is a handy function called pysubs2.make_time(). Youcan use this function to give times in minutes and seconds, but also in frames.

>>> subs[1].start == pysubs2.make_time(s=2)True>>> subs[1].start == pysubs2.make_time(frame=50, fps=25)True

Tip: pysubs2.SSAEvent objects define ordering with respect to time, meaning you can sort them chronologically.

4 Chapter 1. Documentation


There is pysubs2.SSAFile.sort() method for this purpose.

Let’s write a function to retime a subtitle file by adding a constant to all timestamps!

>>> def shift(subs, ms):... for line in subs:... line.start += ms... line.end += msshift(subs, 500)

Well, it turns out the library can already do this with pysubs2.SSAFile.shift(), which takes the same argu-ments as pysubs2.make_time(). Let’s shift the subtitles back.

>>> subs.shift(s=-0.5)

Note: You can have negative timestamps in your subs. They are assumed to be zero for purposes of export.

As you’ve seen already with the newlines, pysubs2 works with SubStation, meaning our SRT file actually has a“Default” style associated with its subtitles.

>>> subs.styles["Default"]<SSAStyle 20.0px 'Arial'>

Let’s add one more style, with italics, and let the second subtitle have it.

>>> my_style = subs.styles["Default"].copy()>>> my_style.italic = True>>> subs.styles["MyStyle"] = my_style>>> subs[1].style = "MyStyle"

Notice that the subtitle object (pysubs2.SSAEvent) and the style object (pysubs2.SSAStyle) aren’t reallyconnected. Instead, styles are referred to by their name in the pysubs2.SSAFile.styles dictionary.

Tip: This means that renaming a style is a little difficult, because you also have to fix all references to the old name.The pysubs2.SSAFile.rename_style() method does what’s needed behind the scenes.

Now that the second subtitle uses “MyStyle”, it should appear in italics. Let’s export to SRT again to see if that’s thecase!

>>> modified_srt = subs.to_string("srt")>>> modified_srt"""\100:00:00,000 --> 00:01:00,000Once upon a time,

200:01:00,000 --> 00:02:00,000<i>there was a SubRip filewith two subtitles.</i>

"""

1.2. Let’s import pysubs2 5


Indeed it is. Of course, since SubRip has no concept of styles, the italics will get converted to inline tags and styleswill be lost if we load this exported file:

>>> modified_subs = pysubs2.SSAFile.from_string(modified_srt)>>> modified_subs[1].text"{\\i1}there was a SubRip file\\Nwith two subtitles.{\\i0}">>> modified_subs[1].style"Default"

It’s better to save the file as ASS so that style information isn’t lost.

>>> subs.save("modified_subtitles.ass")>>> with open("modified_subtitles.ass") as fp:... print(fp.read())[Script Info]; Script generated by pysubs2; https://pypi.python.org/pypi/pysubs2WrapStyle: 0ScaledBorderAndShadow: yesCollisions: NormalScriptType: v4.00+

[V4+ Styles]Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour,→˓BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle,→˓BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, EncodingStyle: Default,Arial,20.0,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100.0,→˓100.0,0.0,0.0,1,2.0,2.0,2,10,10,10,1Style: MyStyle,Arial,20.0,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,-1,0,0,100.0,→˓100.0,0.0,0.0,1,2.0,2.0,2,10,10,10,1

[Events]Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, TextDialogue: 0,0:00:00.00,0:01:00.00,Default,,0,0,0,,Once upon a time,Dialogue: 0,0:01:00.00,0:02:00.00,MyStyle,,0,0,0,,there was a SubRip file\Nwith two→˓subtitles.

And that’s it! Now you should be a little familiar with pysubs2. Have a look at the API Reference to see what’s there.

Some final thoughts, in no particular order:

• The library tries its best to read given file. Format detection and actual parsing is rather benevolent.

• Only basic SubRip/MicroDVD tags are supported.

• If you are unsure about SubStation, get familiar with the Aegisub subtitle editor. You can also use the SubStationspecification for reference.

• When working with MicroDVD, you sometimes have to specify the fps argument when loading and saving.There is a convention to specify framerate in the first subtitle, which pysubs2 handles transparently.

API Reference

Note: The documentation is written from Python 3 point of view; a “string” means Unicode string.



http://moodub.free.fr/video/ass-specs.doc

http://moodub.free.fr/video/ass-specs.doc


Supported input/output formats

pysubs2 is built around SubStation Alpha, the native subtitle format of Aegisub.

SubStation Alpha — supported in two versions:

• .ass files (Advanced SubStation Alpha v4.0+), format identifier is "ass".

• .ssa files (SubStation Alpha v4.0), format identifier is "ssa".

SubRip — .srt files, format identifier is "srt".

MicroDVD — .sub files, format identifier is "microdvd".

MPL2 — Time-based format similar to MicroDVD, format identifier is "mpl2". To save subtitles in MPL2 format,use subs.save("subtitles.txt", format_="mpl2").

JSON-serialized internal representation, which amounts to ASS. Format identifier is "json".

pysubs2 — the main module

pysubs2.load = <bound method ABCMeta.load of <class ‘pysubs2.ssafile.SSAFile’>>Alias for SSAFile.load().

pysubs2.make_time(h=0, m=0, s=0, ms=0, frames=None, fps=None)Alias for pysubs2.time.make_time().

class pysubs2.Color(r, g, b, a) namedtuple for 8-bit RGB color with alpha channel.

All values are ints from 0 to 255.

SSAFile — a subtitle file

class pysubs2.SSAFileSubtitle file in SubStation Alpha format.

This class has a list-like interface which exposes SSAFile.events, list of subtitles in the file:

subs = SSAFile.load("subtitles.srt")

for line in subs:print(line.text)

subs.insert(0, SSAEvent(start=0, end=make_time(s=2.5), text="New first subtitle"))

del subs[0]

aegisub_project = NoneDict with Aegisub project, ie. [Aegisub Project Garbage].

events = NoneList of SSAEvent instances, ie. individual subtitles.

format = NoneFormat of source subtitle file, if applicable, eg. "srt".

fps = NoneFramerate used when reading the file, if applicable.

1.3. API Reference 7



info = NoneDict with script metadata, ie. [Script Info].

styles = NoneDict of SSAStyle instances.

Reading and writing subtitles

Using path to file

classmethod SSAFile.load(path, encoding=u’utf-8’, format_=None, fps=None, **kwargs)Load subtitle file from given path.

Parameters

• path (str) – Path to subtitle file.

• encoding (str) – Character encoding of input file. Defaults to UTF-8, you may need tochange this.

• format (str) – Optional, forces use of specific parser (eg. “srt”, “ass”). Otherwise,format is detected automatically from file contents. This argument should be rarely needed.

• fps (float) – Framerate for frame-based formats (MicroDVD), for other formats thisargument is ignored. Framerate might be detected from the file, in which case you don’tneed to specify it here (when given, this argument overrides autodetection).

• kwargs – Extra options for the parser.

Returns SSAFile

Raises

• IOError

• UnicodeDecodeError

• pysubs2.exceptions.UnknownFPSError

• pysubs2.exceptions.UnknownFormatIdentifierError

• pysubs2.exceptions.FormatAutodetectionError

Note: pysubs2 may autodetect subtitle format and/or framerate. These values are set as SSAFile.formatand SSAFile.fps attributes.

Example

>>> subs1 = pysubs2.load("subrip-subtitles.srt")>>> subs2 = pysubs2.load("microdvd-subtitles.sub", fps=23.976)

SSAFile.save(path, encoding=u’utf-8’, format_=None, fps=None, **kwargs)Save subtitle file to given path.

Parameters

• path (str) – Path to subtitle file.



• encoding (str) – Character encoding of output file. Defaults to UTF-8, which should befine for most purposes.

• format (str) – Optional, specifies desired subtitle format (eg. “srt”, “ass”). Otherwise,format is detected automatically from file extension. Thus, this argument is rarely needed.

• fps (float) – Framerate for frame-based formats (MicroDVD), for other formats thisargument is ignored. When omitted, SSAFile.fps value is used (ie. the framerateused for loading the file, if any). When the SSAFile wasn’t loaded from MicroDVD,or if you wish save it with different framerate, use this argument. See also SSAFile.transform_framerate() for fixing bad frame-based to time-based conversions.

• kwargs – Extra options for the writer.

Raises

• IOError

• UnicodeEncodeError

• pysubs2.exceptions.UnknownFPSError

• pysubs2.exceptions.UnknownFormatIdentifierError

• pysubs2.exceptions.UnknownFileExtensionError

Using string

classmethod SSAFile.from_string(string, format_=None, fps=None, **kwargs)Load subtitle file from string.

See SSAFile.load() for full description.

Parameters string (str) – Subtitle file in a string. Note that the string must be Unicode (inPython 2).

Returns SSAFile

Example

>>> text = '''... 1... 00:00:00,000 --> 00:00:05,000... An example SubRip file.... '''>>> subs = SSAFile.from_string(text)

SSAFile.to_string(format_, fps=None, **kwargs)Get subtitle file as a string.

See SSAFile.save() for full description.

Returns str

Using file object

classmethod SSAFile.from_file(fp, format_=None, fps=None, **kwargs)Read subtitle file from file object.



See SSAFile.load() for full description.

Note: This is a low-level method. Usually, one of SSAFile.load() or SSAFile.from_string() ispreferable.

Parameters fp (file object) – A file object, ie. io.TextIOBase instance. Note that thefile must be opened in text mode (as opposed to binary).

Returns SSAFile

SSAFile.to_file(fp, format_, fps=None, **kwargs)Write subtitle file to file object.

See SSAFile.save() for full description.

Note: This is a low-level method. Usually, one of SSAFile.save() or SSAFile.to_string() ispreferable.

Parameters fp (file object) – A file object, ie. io.TextIOBase instance. Note that thefile must be opened in text mode (as opposed to binary).

Retiming subtitles

SSAFile.shift(h=0, m=0, s=0, ms=0, frames=None, fps=None)Shift all subtitles by constant time amount.

Shift may be time-based (the default) or frame-based. In the latter case, specify both frames and fps. h, m, s, mswill be ignored.

Parameters

• m, s, ms (h,) – Integer or float values, may be positive or negative.

• frames (int) – When specified, must be an integer number of frames. May be positive ornegative. fps must be also specified.

• fps (float) – When specified, must be a positive number.

Raises ValueError – Invalid fps or missing number of frames.

SSAFile.transform_framerate(in_fps, out_fps)Rescale all timestamps by ratio of in_fps/out_fps.

Can be used to fix files converted from frame-based to time-based with wrongly assumed framerate.

Parameters

• in_fps (float) –

• out_fps (float) –

Raises ValueError – Non-positive framerate given.



Working with styles

SSAFile.rename_style(old_name, new_name)Rename a style, including references to it.

Parameters

• old_name (str) – Style to be renamed.

• new_name (str) – New name for the style (must be unused).

Raises

• KeyError – No style named old_name.

• ValueError – new_name is not a legal name (cannot use commas) or new_name is taken.

SSAFile.import_styles(subs, overwrite=True)Merge in styles from other SSAFile.

Parameters

• subs (SSAFile) – Subtitle file imported from.

• overwrite (bool) – On name conflict, use style from the other file (default: True).

Misc methods

SSAFile.equals(other)Equality of two SSAFiles.

Compares SSAFile.info, SSAFile.styles and SSAFile.events. Order of entries in OrderedDictsdoes not matter. “ScriptType” key in info is considered an implementation detail and thus ignored.

Useful mostly in unit tests. Differences are logged at DEBUG level.

SSAFile.sort()Sort subtitles time-wise, in-place.

SSAEvent — one subtitle

class pysubs2.SSAEvent(**fields)A SubStation Event, ie. one subtitle.

In SubStation, each subtitle consists of multiple “fields” like Start, End and Text. These are exposed as attributes(note that they are lowercase; see SSAEvent.FIELDS for a list). Additionaly, there are some convenienceproperties like SSAEvent.plaintext or SSAEvent.duration.

This class defines an ordering with respect to (start, end) timestamps.

Tip: Use pysubs2.make_time() to get times in milliseconds.

Example:

>>> ev = SSAEvent(start=make_time(s=1), end=make_time(s=2.5), text="Hello World!")

FIELDS = frozenset([u’layer’, u’end’, u’name’, u’text’, u’style’, u’marked’, u’effect’, u’start’, u’type’, u’marginr’, u’marginv’, u’marginl’])All fields in SSAEvent.



copy()Return a copy of the SSAEvent.

durationSubtitle duration in milliseconds (read/write property).

Writing to this property adjusts SSAEvent.end. Setting negative durations raises ValueError.

effect = NoneLine effect

end = NoneSubtitle end time (in milliseconds)

equals(other)Field-based equality for SSAEvents.

is_commentWhen true, the subtitle is a comment, ie. not visible (read/write property).

Setting this property is equivalent to changing SSAEvent.type to "Dialogue" or "Comment".

layer = NoneLayer number, 0 is the lowest layer (ASS only)

marginl = NoneLeft margin

marginr = NoneRight margin

marginv = NoneVertical margin

marked = None(SSA only)

name = NoneActor name

plaintextSubtitle text as multi-line string with no tags (read/write property).

Writing to this property replaces SSAEvent.text with given plain text. Newlines are converted to \Ntags.

shift(h=0, m=0, s=0, ms=0, frames=None, fps=None)Shift start and end times.

See SSAFile.shift() for full description.

start = NoneSubtitle start time (in milliseconds)

style = NoneStyle name

text = NoneText of subtitle (with SubStation override tags)

type = NoneLine type (Dialogue/Comment)



SSAStyle — a subtitle style

class pysubs2.SSAStyle(**fields)A SubStation Style.

In SubStation, each subtitle (SSAEvent) is associated with a style which defines its font, color, etc. Like asubtitle event, a style also consists of “fields”; see SSAStyle.FIELDS for a list (note the spelling, which isdifferent from SubStation proper).

Subtitles and styles are connected via an SSAFile they belong to. SSAEvent.style is a string which is (orshould be) a key in the SSAFile.styles dict. Note that style name is stored separately; a given SSAStyleinstance has no particular name itself.

This class defines equality (equality of all fields).

FIELDS = frozenset([u’marginl’, u’encoding’, u’scalex’, u’scaley’, u’secondarycolor’, u’borderstyle’, u’marginr’, u’tertiarycolor’, u’alignment’, u’marginv’, u’fontname’, u’strikeout’, u’angle’, u’underline’, u’italic’, u’backcolor’, u’outlinecolor’, u’bold’, u’spacing’, u’fontsize’, u’alphalevel’, u’shadow’, u’outline’, u’primarycolor’])All fields in SSAStyle.

alignment = NoneNumpad-style alignment, eg. 7 is “top left” (that is, ASS alignment semantics)

alphalevel = NoneOld, unused SSA-only field

angle = NoneRotation (ASS only)

backcolor = NoneBack, ie. shadow color (pysubs2.Color instance)

bold = NoneBold

borderstyle = NoneBorder style

encoding = NoneCharset

fontname = NoneFont name

fontsize = NoneFont size (in pixels)

italic = NoneItalic

marginl = NoneLeft margin (in pixels)

marginr = NoneRight margin (in pixels)

marginv = NoneVertical margin (in pixels)

outline = NoneOutline width (in pixels)

outlinecolor = NoneOutline color (pysubs2.Color instance)



primarycolor = NonePrimary color (pysubs2.Color instance)

scalex = NoneHorizontal scaling (ASS only)

scaley = NoneVertical scaling (ASS only)

secondarycolor = NoneSecondary color (pysubs2.Color instance)

shadow = NoneShadow depth (in pixels)

spacing = NoneLetter spacing (ASS only)

strikeout = NoneStrikeout (ASS only)

tertiarycolor = NoneTertiary color (pysubs2.Color instance)

underline = NoneUnderline (ASS only)

pysubs2.time — time-related utilities

pysubs2.time.TIMESTAMP = <_sre.SRE_Pattern object>Pattern that matches both SubStation and SubRip timestamps.

pysubs2.time.frames_to_ms(frames, fps)Convert frame-based duration to milliseconds.

Parameters

• frames – Number of frames (should be int).

• fps – Framerate (must be a positive number, eg. 23.976).

Returns Number of milliseconds (rounded to int).

Raises ValueError – fps was negative or zero.

pysubs2.time.make_time(h=0, m=0, s=0, ms=0, frames=None, fps=None)Convert time to milliseconds.

See pysubs2.time.times_to_ms(). When both frames and fps are specified, pysubs2.time.frames_to_ms() is called instead.

Raises ValueError – Invalid fps, or one of frames/fps is missing.

Example

>>> make_time(s=1.5)1500>>> make_time(frames=50, fps=25)2000



pysubs2.time.ms_to_frames(ms, fps)Convert milliseconds to number of frames.

Parameters

• ms – Number of milliseconds (may be int, float or other numeric class).

• fps – Framerate (must be a positive number, eg. 23.976).

Returns Number of frames (int).

Raises ValueError – fps was negative or zero.

pysubs2.time.ms_to_str(ms, fractions=False)Prettyprint milliseconds to [-]H:MM:SS[.mmm]

Handles huge and/or negative times. Non-negative times with fractions=True are matched by pysubs2.time.TIMESTAMP.

Parameters

• ms – Number of milliseconds (int, float or other numeric class).

• fractions – Whether to print up to millisecond precision.

Returns str

pysubs2.time.ms_to_times(ms)Convert milliseconds to normalized tuple (h, m, s, ms).

Parameters ms – Number of milliseconds (may be int, float or other numeric class). Should benon-negative.

Returns Named tuple (h, m, s, ms) of ints. Invariants: ms in range(1000) and s inrange(60) and m in range(60)

pysubs2.time.times_to_ms(h=0, m=0, s=0, ms=0)Convert hours, minutes, seconds to milliseconds.

Arguments may be positive or negative, int or float, need not be normalized (s=120 is okay).

Returns Number of milliseconds (rounded to int).

pysubs2.time.timestamp_to_ms(groups)Convert groups from pysubs2.time.TIMESTAMP match to milliseconds.

Example

>>> timestamp_to_ms(TIMESTAMP.match("0:00:00.42").groups())420

pysubs2.exceptions — thrown exceptions

exception pysubs2.exceptions.FormatAutodetectionErrorSubtitle format is ambiguous or unknown.

exception pysubs2.exceptions.Pysubs2ErrorBase class for pysubs2 exceptions.

exception pysubs2.exceptions.UnknownFPSErrorFramerate was not specified and couldn’t be inferred otherwise.



exception pysubs2.exceptions.UnknownFileExtensionErrorFile extension does not pertain to any known subtitle format.

exception pysubs2.exceptions.UnknownFormatIdentifierErrorUnknown subtitle format identifier (ie. string like "srt").

pysubs2.formats — subtitle format implementations

Note: This submodule contains pysubs2 internals. It’s mostly of interest if you’re looking to implement a subtitleformat not supported by the library. In that case, have a look at pysubs2.formats.FormatBase.

pysubs2.formats.FILE_EXTENSION_TO_FORMAT_IDENTIFIER = {‘.ass’: ‘ass’, ‘.srt’: ‘srt’, ‘.sub’: ‘microdvd’, ‘.ssa’: ‘ssa’, ‘.json’: ‘json’}Dict mapping file extensions to format identifiers.

pysubs2.formats.FORMAT_IDENTIFIER_TO_FORMAT_CLASS = {‘ass’: <class ‘pysubs2.substation.SubstationFormat’>, ‘srt’: <class ‘pysubs2.subrip.SubripFormat’>, ‘mpl2’: <class ‘pysubs2.mpl2.MPL2Format’>, ‘json’: <class ‘pysubs2.jsonformat.JSONFormat’>, ‘microdvd’: <class ‘pysubs2.microdvd.MicroDVDFormat’>, ‘ssa’: <class ‘pysubs2.substation.SubstationFormat’>}Dict mapping format identifiers to implementations (FormatBase subclasses).

pysubs2.formats.autodetect_format(content)Return format identifier for given fragment or raise FormatAutodetectionError.

pysubs2.formats.get_file_extension(format_)Format identifier -> file extension

pysubs2.formats.get_format_class(format_)Format identifier -> format class (ie. subclass of FormatBase)

pysubs2.formats.get_format_identifier(ext)File extension -> format identifier

class pysubs2.formats.FormatBaseBase class for subtitle format implementations.

How to implement a new subtitle format:

1.Create a subclass of FormatBase and override the methods you want to support.

2.Decide on a format identifier, like the "srt" or "microdvd" already used in the library.

3.Add your identifier and class to pysubs2.formats.FORMAT_IDENTIFIER_TO_FORMAT_CLASS.

4.(optional) Add your file extension and class to pysubs2.formats.FILE_EXTENSION_TO_FORMAT_IDENTIFIER.

After finishing these steps, you can call SSAFile.load() and SSAFile.save() with your format, in-cluding autodetection from content and file extension (if you provided these).

classmethod from_file(subs, fp, format_, **kwargs)Load subtitle file into an empty SSAFile.

If the parser autodetects framerate, set it as subs.fps.

Parameters

• subs (SSAFile) – An empty SSAFile.

• fp (file object) – Text file object, the subtitle file.

• format (str) – Format identifier. Used when one format class implements multipleformats (see SubstationFormat).

• kwargs – Extra options, eg. fps.



Returns None

Raises pysubs2.exceptions.UnknownFPSError – Framerate was not provided andcannot be detected.

classmethod guess_format(text)Return format identifier of recognized format, or None.

Parameters text (str) – Content of subtitle file. When the file is long, this may be only itsfirst few thousand characters.

Returns format identifier (eg. "srt") or None (unknown format)

classmethod to_file(subs, fp, format_, **kwargs)Write SSAFile into a file.

If you need framerate and it is not passed in keyword arguments, use subs.fps.

Parameters

• subs (SSAFile) – Subtitle file to write.

• fp (file object) – Text file object used as output.

• format (str) – Format identifier of desired output format. Used when one format classimplements multiple formats (see SubstationFormat).

• kwargs – Extra options, eg. fps.

Returns None

Raises pysubs2.exceptions.UnknownFPSError – Framerate was not provided andsubs.fps is None.

Release Notes

0.2.2 — released on 2017-07-22

• Support for MPL2 subtitle format, patch by pannal (https://github.com/pannal)

• Dropped support for Python 3.2

0.2.1 — released on 2015-10-17

• CLI can now be invoked by python -m pysubs2 only; broken pysubs2.py script has been removed(Issue #1).

• Loading a SubStation file no longer swaps color channels (Issue #3).

• pysubs2 now preserves Aegisub 3.2+ project settings (the [Aegisub Project Garbage] section, storedin pysubs2.SSAFile.aegisub_project dict).

• SubStation version is now correctly declared in [Script Info] section as ScriptType (instead ofScriptInfo).

0.2.0 — released on 2014-09-09

• Initial release.

1.4. Release Notes 17

https://github.com/pannal



CHAPTER 2

License

Copyright (c) 2014-2017 Tomas Karabela

Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included inall copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS INTHE SOFTWARE.

19


20 Chapter 2. License

Python Module Index

ppysubs2, 7pysubs2.exceptions, 15pysubs2.formats, 16pysubs2.time, 14

21


22 Python Module Index

Index

Aaegisub_project (pysubs2.SSAFile attribute), 7alignment (pysubs2.SSAStyle attribute), 13alphalevel (pysubs2.SSAStyle attribute), 13angle (pysubs2.SSAStyle attribute), 13autodetect_format() (in module pysubs2.formats), 16

Bbackcolor (pysubs2.SSAStyle attribute), 13bold (pysubs2.SSAStyle attribute), 13borderstyle (pysubs2.SSAStyle attribute), 13

CColor (class in pysubs2), 7copy() (pysubs2.SSAEvent method), 11

Dduration (pysubs2.SSAEvent attribute), 12

Eeffect (pysubs2.SSAEvent attribute), 12encoding (pysubs2.SSAStyle attribute), 13end (pysubs2.SSAEvent attribute), 12equals() (pysubs2.SSAEvent method), 12equals() (pysubs2.SSAFile method), 11events (pysubs2.SSAFile attribute), 7

FFIELDS (pysubs2.SSAEvent attribute), 11FIELDS (pysubs2.SSAStyle attribute), 13FILE_EXTENSION_TO_FORMAT_IDENTIFIER (in

module pysubs2.formats), 16fontname (pysubs2.SSAStyle attribute), 13fontsize (pysubs2.SSAStyle attribute), 13format (pysubs2.SSAFile attribute), 7FORMAT_IDENTIFIER_TO_FORMAT_CLASS (in

module pysubs2.formats), 16FormatAutodetectionError, 15FormatBase (class in pysubs2.formats), 16

fps (pysubs2.SSAFile attribute), 7frames_to_ms() (in module pysubs2.time), 14from_file() (pysubs2.formats.FormatBase class method),

16from_file() (pysubs2.SSAFile class method), 9from_string() (pysubs2.SSAFile class method), 9

Gget_file_extension() (in module pysubs2.formats), 16get_format_class() (in module pysubs2.formats), 16get_format_identifier() (in module pysubs2.formats), 16guess_format() (pysubs2.formats.FormatBase class

method), 17

Iimport_styles() (pysubs2.SSAFile method), 11info (pysubs2.SSAFile attribute), 7is_comment (pysubs2.SSAEvent attribute), 12italic (pysubs2.SSAStyle attribute), 13

Llayer (pysubs2.SSAEvent attribute), 12load (in module pysubs2), 7load() (pysubs2.SSAFile class method), 8

Mmake_time() (in module pysubs2), 7make_time() (in module pysubs2.time), 14marginl (pysubs2.SSAEvent attribute), 12marginl (pysubs2.SSAStyle attribute), 13marginr (pysubs2.SSAEvent attribute), 12marginr (pysubs2.SSAStyle attribute), 13marginv (pysubs2.SSAEvent attribute), 12marginv (pysubs2.SSAStyle attribute), 13marked (pysubs2.SSAEvent attribute), 12ms_to_frames() (in module pysubs2.time), 14ms_to_str() (in module pysubs2.time), 15ms_to_times() (in module pysubs2.time), 15

23


Nname (pysubs2.SSAEvent attribute), 12

Ooutline (pysubs2.SSAStyle attribute), 13outlinecolor (pysubs2.SSAStyle attribute), 13

Pplaintext (pysubs2.SSAEvent attribute), 12primarycolor (pysubs2.SSAStyle attribute), 13pysubs2 (module), 7pysubs2.exceptions (module), 15pysubs2.formats (module), 16pysubs2.time (module), 14Pysubs2Error, 15

Rrename_style() (pysubs2.SSAFile method), 11

Ssave() (pysubs2.SSAFile method), 8scalex (pysubs2.SSAStyle attribute), 14scaley (pysubs2.SSAStyle attribute), 14secondarycolor (pysubs2.SSAStyle attribute), 14shadow (pysubs2.SSAStyle attribute), 14shift() (pysubs2.SSAEvent method), 12shift() (pysubs2.SSAFile method), 10sort() (pysubs2.SSAFile method), 11spacing (pysubs2.SSAStyle attribute), 14SSAEvent (class in pysubs2), 11SSAFile (class in pysubs2), 7SSAStyle (class in pysubs2), 13start (pysubs2.SSAEvent attribute), 12strikeout (pysubs2.SSAStyle attribute), 14style (pysubs2.SSAEvent attribute), 12styles (pysubs2.SSAFile attribute), 8

Ttertiarycolor (pysubs2.SSAStyle attribute), 14text (pysubs2.SSAEvent attribute), 12times_to_ms() (in module pysubs2.time), 15TIMESTAMP (in module pysubs2.time), 14timestamp_to_ms() (in module pysubs2.time), 15to_file() (pysubs2.formats.FormatBase class method), 17to_file() (pysubs2.SSAFile method), 10to_string() (pysubs2.SSAFile method), 9transform_framerate() (pysubs2.SSAFile method), 10type (pysubs2.SSAEvent attribute), 12

Uunderline (pysubs2.SSAStyle attribute), 14UnknownFileExtensionError, 15UnknownFormatIdentifierError, 16UnknownFPSError, 15

24 Index

Documents

pysubs2 Documentation - media.readthedocs.org · This tutorial will show you how to use most of what pysubs2 library has to offer. ... Aegisub, you will hopefully ﬁnd the API quite