User:PhosCity/Assf

ASSFoundation is a module that aims to make working with subtitle objects efficient. It does most of the heavy lifting so that we can do more with less lines of code in our script. It provides various functions that allows us to work with lines, tags, drawings, text and comments. This makes it unnecessary to reinvent the wheel and write your own functions to do most of the common task while still allowing you to do complex tasks more easily.

This guide assumes that you already know how to write Aegisub scripts and know the basics of Moonscript.

Skeleton of Aegisub Scripts
This is the framework that all your scripts will have. Here we import LineCollection and ASSFoundation. We also import Logger for logging purposes but if you don't need to log anything, you can remove that line. Finally, we define a function called `functionName`. This function name is what we register in Aegisub in the last line and it gets executed as soon as we run the script. Everything we do in the guide below will go inside the function where `--stuff goes here` is written.

LineCollection
LineCollection is not a part of ASSFoundation but almost anything that ASSFoundation does will act on the line table generated by LineCollection. The line table generated by LineCollection will have all the fields of a normal line table but it also adds other fields. Some of the new fields that are useful for writing Aegisub automations are:

Some of the methods LineCollection provides to us to modify subtitles are:

You can actually work in the line table generated by LineCollection without using ASSFoundation as shown in an example below where we change the effect of the line to "Actor".

However, we'll use LineCollection alongside ASSFoundation to get the most out of both modules.

Logger
Logger is a logging module from DependencyControl that you can use to log messages. If you do not pass log level, default log level is 2. By default, Aegisub's log level is set to 3 which means that the message above 3 wont be seen by end user unless they set the log level higher themself. The script exits after showing message if the log level is below 2.

Loop through all lines using LineCollection
This is usually how you'd loop through all the selected lines. By default, it skips all the commented lines and loops in reverse order. So the last selected line would be the first one you work on. Generally if your script is supposed to work on all selected lines, this is what you'd use.

If the order matters to you, you'd loop through selected lines in the following way.

If you don't like that it skips over commented lines and want it to be included, collect lines as shown below.

In fact you can give any condition here and if that condition is fulfilled, only those lines can be collected. For example, if you want to only collect commented lines:

As a final example, if you want to only collect lines whose layer is 1:

Until now, we've only looped over the selected lines but what if we want to loop over all the dialogue lines. Naturally I assumed,  would be the way but it didn't work. So I've come up with a bit of a hacky way:

This will loop over all the dialogue lines in your file. You can obviously modify the last line above to change the order of looping as well as the condition which a line has to fulfill to be collected.

Line Data
When we loop through each line, we need to create something called line data. This is a huge table that ASSFoundation creates after it parses a line and consists of all the information about your line. All we'll do when we use ASSFoundation is make changes to this table which will in turn make changes to the acutal line. In the following example, we parse a line and save it's line data to a variable named `data`.

The information that line data contains are:


 * line
 * line table with all the fields


 * scriptInfo
 * info about your subtitle like resolution, color-matrix etc.


 * styles
 * list of all the styles in your subtitle with their parameters


 * sections
 * different sections of a line. It is explained below.

Sections
In ASSFoundation, a line can have four different types of sections. Their names make them self-explanatory so they're only listed here.


 * 1) ASS.Section.Text
 * 2) ASS.Section.Tag
 * 3) ASS.Section.Drawing
 * 4) ASS.Section.Comment

callback
A function that can be used to loop through all or specific sections of a line.

If you want to work in an individual section, you can do the following:

In the example below, we loop through text section only. You can replace `ASS.Section.Text` with any other section to loop through those sections only.

Loop through first five sections:

Loop through first tag sections within the index 1 and 5:

Loops through tag sections within the last five sections:

Using relative, the following will start from the '-2' index and loop backwards 5 times and loops through all the tag sections it finds.

getEffectiveTags
You can use this method to obtain the effective value of any tag for a particular section. If the tag is not present as an override tag, you can also get default value from style.

insertTags
This method can be used to insert a tag to the line. The tag you're inserting must be a tag object as AssFoundation understands it. You can define the tag block where you want to insert the tag and you also can define the order in which tag will be inserted. In order to get a proper idea of how 'index' and 'sectionPosition' works, take a look at the following picture.