Misc. APIs

This page documents miscellaneous APIs useful for working with subtitles. These can’t be clearly placed into any of the other main categories and there’s too few of each kind to warrant a separate category.

aegisub.cancel #

Synopsis: aegisub.cancel()

Immediately end execution of the current script, rolling back any changes that have been made in it.

This function never returns.

aegisub.set_status_text #

Synopsis: aegisub.set_status_text(text)

Show text in the main window’s status bar. It’s cleared again after ten seconds.

@text (string)

The text to show.

This does nothing when there’s no main window to show the text in.

aegisub.text_extents #

Synopsis: width, height, descent, ext_lead = aegisub.text_extents(style, text)

Obtain system font metrics and determine the rendered size in pixels of the given text when using the style.

@style (table)

A style table as defined by the subtitle interface. The font name, size, weight, style, spacing and encoding is used to determine the size of the text.

@text (string)

The text the extents should be determined for. This should not contain line breaks (\n or \r\n) nor should it contain formatting codes of any kind. Formatting codes are not interpreted and will be taken as verbatim text.

width (number)

Width in pixels of text. This may be non-integer.

height (number)

Height in pixels of the text. This may be non-integer.

descent (number)

Length of descenders in the font. This may be non-integer.

ext_lead (number)

External leading for the font. This may be non-integer.

You should only feed plain text strings without line breaks into this function. It cannot handle any kind of formatting codes or text layout. Rather, it is intended as a helper to create text layouts by determining rendered sizes of bits and pieces of a longer text, which can then be laid out by the script.

aegisub.gettext #

Synopsis: translation = aegisub.gettext(untranslated)

Get the translation for a string. This is mostly only intended for scripts bundled with Aegisub (as there’s no way for you to add your own translations), but if you happen to be using strings that are present in Aegisub it may be useful.

Note that in the bundled macros this is always aliased to tr for the sake of the string extractor.

Getting information on the video #

Automation 4 Lua offers two functions designed to be able to work with frame-based timing without having to consider whether the video source is VFR or CFR.

The primary purpose of these functions is to be able to generate per-frame effects, i.e. get the timestamps of a number of sequential frames and calculate coordinates, sizes etc. for an object for each of those frames.

One thing to remember when using these functions is that, considering a one-dimensional time line, a time stamp is a point on the time line, while a video frame spans a range of the time line, from its beginning time to its ending time. The ending time of a frame is the beginning time of the next. The beginning time of a frame is included in the range while the ending time is excluded from the range.

These functions convert between frames and subtitle times rather than exact frame timestamps. A line is displayed on every frame that begins within the line, so a line that starts after the beginning of the previous frame, up to and including the beginning of a frame, first appears on that frame. This is the same conversion Aegisub itself uses when timing lines to video.

aegisub.frame_from_ms #

Synopsis: frame = aegisub.frame_from_ms(ms)

Use loaded frame rate data to convert an absolute time given in milliseconds into a frame number.

@ms (number)

Absolute time from the beginning of the video, for which to determine the frame number.

frame (number)

The first frame a line starting at ms is displayed on, i.e. the first frame that begins at or after ms, or nil if there is no frame rate data loaded.

If the time is in the middle of a frame it is rounded up to the next frame. For a line’s end time, this gives the first frame the line is no longer displayed on.

aegisub.ms_from_frame #

Synopsis: ms = aegisub.ms_from_frame(frame)

Use loaded frame rate data to convert a frame number of the video into an absolute time in milliseconds.

@frame (number)

Frame to obtain a time for.

ms (number)

The start time that a subtitle line should have if it is supposed to first become visible at the frame frame. This is also the end time that a subtitle line should have if it is supposed to first become invisible at the frame frame. If no frame rate data is loaded, returns nil.

This is halfway between the beginnings of the previous frame and of frame, not the beginning of frame itself. For example, at 23.976 fps frame 24 begins at 1001 ms, but aegisub.ms_from_frame(24) returns 980. The margin means the time still lands on the right frame after being rounded to the centiseconds subtitle files store, at frame rates up to 100 fps (above that, frames are shorter than a centisecond). The two functions also round-trip: aegisub.frame_from_ms(aegisub.ms_from_frame(frame)) is always frame.

aegisub.video_size #

Synopsis: xres, yres, ar, artype = aegisub.video_size()

Get information about the resolution and aspect-ratio of the loaded video, if any.

xres (number)

Coded width of the video in pixels, or nil if there is no video loaded.

yres (number)

Coded height of the video in pixels, or nil if there is no video loaded.

ar (number)

Custom display aspect ratio override. Meaningless unless artype is 4.

artype (number)

There are 5 values that artype can take:

• 0: The video has square pixels, i.e. PAR is 1.00 and DAR is xres/yres.
• 1: The video is 4:3, i.e. DAR is 1.33.
• 2: The video is 16:9, i.e. DAR is 1.78.
• 3: The video is 2.35 format, i.e. DAR is 2.35.
• 4: The DAR is whatever the ar return value contains.

aegisub.keyframes #

Synopsis keyframes = aegisub.keyframes()

Get a list of what video frames are keyframes.

keyframes (table)

A sorted table where each entry is the frame number of a keyframe. If no keyframe data is loaded, the table will be empty.

aegisub.decode_path #

Synopsis path = aegisub.decode_path(encoded_path)

Convert a path beginning with a path specifier to an absolute path.

@encoded_path (string)

A string which may optionally begin with an Aegisub path specifier.

@path (string)

If encoded_path began with a valid path specifier, an absolute path. If it began with an invalid path specifier (such as if ?video was used when no video is open), a string that is unlikely to be useful in any way. Any other strings are passed through untouched.

aegisub.project_properties #

Synopsis properties = aegisub.project_properties()

Get a table containing information about what files the user currently has open. The exact contents of this table are deliberately undocumented, and may change without warning.