|
Advanced SubStation Alpha python library
Easy macro commands for modifying .ass files
|
view on
github
|
ass.py is a python library that handles (Advanced) SubStation Alpha subtitle files. Its functionality includes reading, writing, and editing of subtitle lines.
Its public interface provides several macro commands, and also allows for more fine-grain editing of specific lines, styles, and metadata.
ass.py's usage paradigm is designed to make it quick and easy to use, with method design similar to that of jQuery. That is, a single command provides many options for what and how it should perform, and multiple commands can be chained easily.
The extended descriptions are minimized by default for ease of locating functions by name. Click the +/− or the function name to expand/shrink the description. (expand all | shrink all)
The following members are accessable at the module level:
version_info(1, 0) represents version "1.0". The length of this array is arbitrary and subject to change.
ASSASS are described below.
The ASS class contains values, methods, and classes related to subtitle file data. When instantiated, it represents a subtitles file which can then be modified.
The following are constants defined on the ASS class:
The following are @classmethods defined on the ASS class:
ASS.(text, modify_text=None, modify_special=None, modify_tag_block=None, modify_tag=None, modify_comment=None, modify_geometry=None...) : stringreturn : stringtext : stringmodify_text : functionmodified_text = modify_text(original_text);modify_special : function\h, \n, \N). The function should perform the following:modified_text = modify_special(original_text);None, these tags will be captured along with text using modify_textmodify_tag_block : function{} brackets. The function should perform the following:modified_text = modify_tag_block(original_text);modify_tag : function{} brackets. The function should perform the following:array_of_tag_args = modify_tag(tag_args);tag_args – an array in the form [ tag_name, tag_arg1, tag_arg2, ... ]array_of_tag_args – an array of tag arguments in the same form as the tag_args.(lambda tag: [ tag ])modify_comment : function{} brackets. The function should perform the following:modified_text = modify_comment(original_text);modify_geometry : function{} brackets. The function should perform the following:modified_text = modify_geometry(original_text);ASS.(text, modify_tag=None, modify_comment=None, next_geometry_scale=0...) : 2-tuple{} brackets.return : 2-tuple\p# tag found, or next_geometry_scale if none are found.text : string{} bracketsmodify_tag : functionmodify_comment : functionnext_geometry_scale : anyASS.(text, space=' ', min_whitespace_length=1, max_whitespace_length=1...) : string\h, \n, \N) with space. If the length of the new space and surrounding whitespace is outside the range [min_whitespace_length, max_whitespace_length], the total whitespace is replace with a single space.return : stringspace : stringmin_whitespace_length : integerspacemax_whitespace_length : integerspace
The following are members of instances of the ASS class. Not all of them should be modified directly.
The following are methods performable on instances of the ASS class:
ASS.(filename, comments=None...) : selfreturn : selffilename : string.ass subtitles tocomments : None | listNone, a single comment will be added indicating script was generated by ass.py.ASS.(filename, overlap=True, newlines=False, remove_identical=True, join=True, filter_function=None...) : selfreturn : selffilename : string.srt subtitles tooverlap : booleanTrue, overlapping timecodes are unchanged.False, overlapping time codes are merged into groups of concurrent times.overlap=False is useful for things which don't support overlapping timecodes, such as YouTube.newlines : booleanTrue, .ass newlines (\n, \N) are preserved.False, newlines are replaced with spaces.remove_identical : booleanTrue, identical lines (after removing formatting tags) are removed.False, they are not removed.join : booleanTrue, identical sequential lines are joined into a single line.False, they are not joined.filter_function : None | functionNone, this is a function that specifies to modify or remove subtitle lines.ASS.Event instance and its formatted text.text string, or None if the line should be removed.ASS.(alias=False...) : selfreturn : selfalias : booleanASS.reformat_stylesASS.(sort=False, join=False, join_naive=False, remove_unseen=True, snap_start=0.0, snap_end=0.0, snap_together=0.0...) : selfASS instance.return : selfsort : booleanTrue, events are sorted by starting timecodejoin : booleanTrue, sequential events that would appear as one are joined into a single eventjoin_naive : booleanTrue, event joining will ignore any animated tags and join them anywayremove_unseen : booleanTrue, events with Start >= End will be removed since they will not be visiblesnap_start : floatsnap_end : floatsnap_together : floatASS.(sort=False, join=False, join_if_names_differ=False, rename=False, rename_function=None, remove_unused=False...) : selfASS instance.return : selfsort : booleanTrue, styles are sorted by namejoin : booleanTrue, duplicate styles joined into a single stylejoin_if_names_differ : booleanTrue, duplicate styles that have different names are also joinedrename : booleanTrue, styles with identical names are renamedrename_function : functionNone, this function modifies the duplicate names. This is only called on duplicate named styles, and is called as:new_name = rename_function(old_name, index); # index starts at 0remove_unused : booleanTrue, unused styles are removedASS.(start=None, end=None, full_inclusion=False, inverse=False, split=False, split_naive=False, filter_types=None, time_scale=1.0, time_scale_origin=0.0, time_offset=0.0, time_clip_start=None, time_clip_end=None, geometry_resolution=None, geometry_scale=None, geometry_scale_origin=(0.0, 0.0), geometry_offset=(0.0, 0.0), geometry_new_styles=True...) : selftc = (tc - scale_origin) * scale + scale_origin + offsetgx = (gx - scale_origin[0]) * scale[0] + scale_origin[0] + offset[0]gy = (gy - scale_origin[1]) * scale[1] + scale_origin[1] + offset[1]return : selfstart : None | floatNone for no lower boundend : None | floatNone for no upper boundfull_inclusion : booleanTrue, event must be completely contained within specified timecode range; i.e.:event.Start >= start and event.End <= endFalse, event must be partially contained within specified timecode range; i.e.:not (event.Start >= end or event.End <= start)inverse : booleanTrue, the operation is performed on all events not contained in the timecode rangesplit : booleanTrue, timecodes that are partially contained in the timecode range are split into multiple eventssplit_naive : booleanTrue, timecode splitting ignores any animation tags in the text and naïvely copies the original text.False, animation tags are properly split. (not implemented yet)filter_types : list | dict | ...in operator.None, no filtering is performed; else, events satisfying event.type in filter_types are included.time_scale : floattime_scale_origin : floattime_offset : floattime_clip_start : None | floatNone for no lower bound. Applied after new timecodes are computed.time_clip_end : None | floatNone for no lower bound. Applied after new timecodes are computed.geometry_resolution : None | 2-tuple(width, height) tuple specifying the new resolution.geometry_scale is not specified, all geometry values are scaled to the new resolution.geometry_scale is specified, this acts as the new bounds for the subtitles.geometry_scale : None | 2-tuple(xscale, yscale) tuple specifying the values to scale geometry coordinates by.None, no scaling is performed unless geometry_resolution is set.geometry_resolution appropriately and set geometry_scale to (1, 1).geometry_scale_origin : 2-tuple(xcenter, ycenter) tuple specifying the coordinate at which geometry is scaled aroundgeometry_offset : 2-tuple(xoffset, yoffset) tuple specifying values to be added to geometry coordinatesgeometry_new_styles : booleanTrue, new styles will be generated for any changes in margins and geometric values.False, margins and values will be updated inside their events.ASS.(time=None, start=time, end=time, filter_types=None, length=None, count=None...) : self(time, start, end) must be specified.return : selftime : None | floatNone to use start and end insteadstart : None | floatNone for the minimum timecodeend : None | floatNone for the maximum timecodefilter_types : list | dict | ...in operator.None, no filtering is performed; else, events satisfying event.type in filter_types are included.length : None | floatcount : None | floatstart == end, this value is ignored and length must be used. Must be greater than 0.ASS.(start=None, end=None, full_inclusion=False, inverse=False, split=False, split_naive=False, filter_types=None, filter_function=None, remove=True, other=None...) : selfASS instance and/or copy them into another instance.return : selfstart : None | floatNone for no lower boundend : None | floatNone for no upper boundfull_inclusion : booleanTrue, event must be completely contained within specified timecode range; i.e.:event.Start >= start and event.End <= endFalse, event must be partially contained within specified timecode range; i.e.:not (event.Start >= end or event.End <= start)inverse : booleanTrue, the operation is performed on all events not contained in the timecode rangesplit : booleanTrue, timecodes that are partially contained in the timecode range are split into multiple eventssplit_naive : booleanTrue, timecode splitting ignores any animation tags in the text and naïvely copies the original text.False, animation tags are properly split. (not implemented yet)filter_types : list | dict | ...in operator.None, no filtering is performed; else, events satisfying event.type in filter_types are included.filter_function : None | functionNone, no additional filtering is performed. Else, this function takes an ASS.Event instance as an input and should return a boolean value: True if it should be processed for extraction, False to skip; i.e.:process_event = filter_function(event);remove : booleanTrue, events are removed from self; otherwise they are keptother : None | ASS instanceNone, events are removed/copied into this objectASS.(filter_types=None, remove=True, other=None, time_offset=0.0...) : selfreturn : selffilter_types : list | dict | ...in operator.None, no filtering is performed; else, events satisfying event.type in filter_types are included.remove : booleanTrue, events are removed from the other object; otherwise they are copied.other : ASS instanceself objecttime_offset : floatASS.(start=None, end=None, full_inclusion=False, inverse=False, split=False, split_naive=False, filter_types=None, tags=True, comments=True, geometry=True, special=False...) : selfreturn : selfstart : None | floatNone for no lower boundend : None | floatNone for no upper boundfull_inclusion : booleanTrue, event must be completely contained within specified timecode range; i.e.:event.Start >= start and event.End <= endFalse, event must be partially contained within specified timecode range; i.e.:not (event.Start >= end or event.End <= start)inverse : booleanTrue, the operation is performed on all events not contained in the timecode rangesplit : booleanTrue, timecodes that are partially contained in the timecode range are split into multiple eventssplit_naive : booleanTrue, timecode splitting ignores any animation tags in the text and naïvely copies the original text.False, animation tags are properly split. (not implemented yet)filter_types : list | dict | ...in operator.None, no filtering is performed; else, events satisfying event.type in filter_types are included.tags : booleanTrue, groups of tags are removed (along with any relevant drawing commands)comments : booleanTrue, comments are removedgeometry : booleanTrue, geometry drawing commands (outside of tag groups) are removedspecial : booleanTrue, groupless tags (\h, \n, \N) are replaced with whitespaceMembers of this class are primarily used internally for decoding/encoding subtitle file information, but a few methods can also be useful externally:
Formatters.(timecode, decimal_length=2, seconds_length=2, minutes_length=2, hours_length=1...) : stringreturn : stringtimecode : floatdecimal_length : integerseconds_length : integerminutes_length : integerhours_length : integer
An instance of ASS.Info represents a line found in the [Script Info] section of an .ass file. It should be obvious what the key and value members refer to.
This class contains info about a certain style found in a subtitles file. Data is loaded from the [V4+ Styles] section of a file.
Style.(other=None...) : ASS.Stylereturn : ASS.Styleother was None, a copy of self is returned.other was not None, self is returned.other : None | ASS.StyleNone, self is copied into a new instance and that instance is returned.other are copied into self. (self is modified, not other)
This class represents a single event found in a subtitles file. Data is loaded from the [Events] section of a file.
Event.(other=None...) : ASS.Eventreturn : ASS.Eventother was None, a copy of self is returned.other was not None, self is returned.other : None | ASS.EventNone, self is copied into a new instance and that instance is returned.other are copied into self. (self is modified, not other)