Utils

class pyonfx.utils.Utils[source]

This class is a collection of static methods that will help the user in some tasks.

static all_non_empty(lines_chars_syls_or_words)[source]

Helps to not check everytime for text containing only spaces or object’s duration equals to zero.

Parameters

lines_chars_syls_or_words (list of Line, Char, Syllable or Word) –

Returns

A list containing lines_chars_syls_or_words without objects with duration equals to zero or blank text (no text or only spaces).

static interpolate(pct, val1, val2, acc=1.0)[source]
Interpolates 2 given values (ASS colors, ASS alpha channels or numbers) by percent value as decimal number.
You can also provide a http://cubic-bezier.com to accelerate based on bezier curves. (TO DO)

You could use that for the calculation of color/alpha gradients.
Parameters

  • pct (float) – Percent value of the interpolation.

  • val1 (int, float or str) – First value to interpolate (either string or number).

  • val2 (int, float or str) – Second value to interpolate (either string or number).

  • acc (float, optional) – Optional acceleration that influences final percent value.

Returns

Interpolated value of given 2 values (so either a string or a number).

Examples

print( Utils.interpolate(0.5, 10, 20) )
print( Utils.interpolate(0.9, "&HFFFFFF&", "&H000000&") )

>>> 15
>>> &HE5E5E5&
class pyonfx.utils.FrameUtility(start_ms, end_ms, fps=Fraction(24000, 1001), n_fr=1)[source]

This class allows to accurately work in a frame per frame environment.

You can use it to iterate over the frames going from start_ms to end_ms and perform operations easily over multiple frames.

BACKGROUND KNOWLEDGE:

When reproducing a video+sub in a player, a line is rendered on the current frame if the current time of the player is in between the line’s start and end time.

The frame’s duration can be determined by the fps value.

Let’s now walk through an example: fps = 20 -> frame_duration = 50 ms.

The player will then seek for frames at the following times: 0, 50, 100, 150, …

To accomodate this fact, frames’ start and end times are positioned as follows: - Frame 0: 0-25 - Frame 1: 25-75 - Frame 2: 75-125 - Frame 3: 125-175 - …

This way, the frames’ mid time will always be one of the player’s seek times. The only exception is the first frame, since we can’t have negative times.

Parameters

  • start_ms (positive int) – Initial time in ms.

  • end_ms (positive int) – Final time in ms.

  • fps (positive int, float or Fraction, optional) – Frames per second.

  • n_fr (positive int, optional) – Number of frames covered by each iteration.

Returns

Returns a Generator yielding start_ms, end_ms, current frame index and total number of frames at each step.

Example

>>> FU = FrameUtility(0, 110, 20)
>>> for s, e, i, n in FU:
>>>     print(f"Frame {i}/{n}: {s} - {e}")
>>>
>>> Frame 1/3: 0 - 25
>>> Frame 2/3: 25 - 75
>>> Frame 3/3: 75 - 125
reset()[source]

Resets the FrameUtility object to its starting values. It is a mandatory operation if you want to reuse the same object.

add(start_time, end_time, end_value, accelerator=1.0)[source]

You can see this function as a “t” tag usable in frame per frame operations. It must be used inside a for loop which iterates a FrameUtility object.

Parameters

  • start_time (int) – Initial time.

  • end_time (int) – Final time.

  • end_value (int or float) – Value reached at end_time.

  • accelerator (float) – Accelerator value.

Examples

>>> FU = FrameUtility(25, 225, 20)
>>> for s, e, i, n in FU:
>>>     fsc = 100
>>>     fsc += FU.add(0, 100, 50)
>>>     fsc += FU.add(100, 200, -50)
>>>     print(f"Frame {i}/{n}: {s} - {e}; fsc: {fsc}")
>>>
>>> Frame 1/4: 25 - 75; fsc: 112.5
>>> Frame 2/4: 75 - 125; fsc: 137.5
>>> Frame 3/4: 125 - 175; fsc: 137.5
>>> Frame 4/4: 175 - 225; fsc: 112.5
class pyonfx.utils.ColorUtility(lines, offset=0)[source]

This class helps to obtain all the color transformations written in a list of lines (usually all the lines of your input .ass) to later retrieve all of those transformations that fit between the start_time and end_time of a line passed, without having to worry about interpolating times or other stressfull tasks.

It is highly suggested to create this object just one time in your script, for performance reasons.

Note

A few notes about the color transformations in your lines:

  • Every color-tag has to be in the format of c&Hxxxxxx&, do not forget the last &;

  • You can put color changes without using transformations, like {\1c&HFFFFFF&\3c&H000000&}Test, but those will be interpreted as {\t(0,0,\1c&HFFFFFF&\3c&H000000&)}Test;

  • For an example of how color changes should be put in your lines, check this.

Also, it is important to remember that color changes in your lines are treated as if they were continuous.

For example, let’s assume we have two lines:

  1. {\1c&HFFFFFF&\t(100,150,\1c&H000000&)}Line1, starting at 0ms, ending at 100ms;

  2. {}Line2, starting at 100ms, ending at 200ms.

Even if the second line doesn’t have any color changes and you would expect to have the style’s colors, it will be treated as it has \1c&H000000&. That could seem strange at first, but thinking about your generated lines, the majority will have start_time and end_time different from the ones of your original file.

Treating transformations as if they were continous, ColorUtility will always know the right colors to pick for you. Also, remember that even if you can’t always see them directly on Aegisub, you can use transformations with negative times or with times that exceed line total duration.

Parameters

  • lines (list of Line) – List of lines to be parsed

  • offset (integer, optional) – Milliseconds you may want to shift all the color changes

Returns

Returns a ColorUtility object.

Examples

# Parsing all the lines in the file
CU = ColorUtility(lines)
# Parsing just a single line (the first in this case) in the file
CU = ColorUtility([ line[0] ])
get_color_change(line, c1=None, c3=None, c4=None)[source]

Returns all the color_changes in the object that fit (in terms of time) between line.start_time and line.end_time.

Parameters

  • line (Line object) – The line of which you want to get the color changes

  • c1 (bool, optional) – If False, you will not get color values containing primary color

  • c3 (bool, optional) – If False, you will not get color values containing border color

  • c4 (bool, optional) – If False, you will not get color values containing shadow color

Returns

A string containing color changes interpolated.

Note

If c1, c3 or c4 is/are None, the script will automatically recognize what you used in the color changes in the lines and put only the ones considered essential.

Examples

# Assume that we have l as a copy of line and we're iterating over all the syl in the current line
# All the fun stuff of the effect creation...
l.start_time = line.start_time + syl.start_time
l.end_time   = line.start_time + syl.end_time

l.text = "{\\an5\\pos(%.3f,%.3f)\\fscx120\\fscy120%s}%s" % (syl.center, syl.middle, CU.get_color_change(l), syl.text)
get_fr_color_change(line, c1=None, c3=None, c4=None)[source]

Returns the single color(s) in the color_changes that fit the current frame (line.start_time) in your frame loop.

Note

If you get errors, try either modifying your \t values or set your fr parameter in FU object to 10.

Parameters

  • line (Line object) – The line of which you want to get the color changes

  • c1 (bool, optional) – If False, you will not get color values containing primary color.

  • c3 (bool, optional) – If False, you will not get color values containing border color.

  • c4 (bool, optional) – If False, you will not get color values containing shadow color.

Returns

A string containing color changes interpolated.

Examples

# Assume that we have l as a copy of line and we're iterating over all the syl in the current line and we're iterating over the frames
l.start_time = s
l.end_time   = e

l.text = "{\\an5\\pos(%.3f,%.3f)\\fscx120\\fscy120%s}%s" % (syl.center, syl.middle, CU.get_fr_color_change(l), syl.text)