Aegisub Docs on Aegisub

Main Page

Mon, 01 Jan 0001 00:00:00 +0000

Welcome to the Aegisub manual. See our about page for more information on the program, or browse the topics on the left bar.

Documentation related to development of Aegisub and building Aegisub is located at the bug tracker.

Starting points

Quick overview of Aegisub

Common tasks:

Timing a translated script to audio
Basic typesetting of on-screen signs
Putting your finished subtitles onto the video (for viewing or distribution)

What is Aegisub?

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub was originally created as a tool to make typesetting, particularly in anime fansubs, a less painful experience. At the time of the start of the project, many other programs that supported the Advanced Substation Alpha format lacked (and in many cases, still lack; development on several competing programs have since been dropped for various reasons completely unrelated to Aegisub) many vital functions, or were too buggy and/or unreliable to be really useful.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

This screenshot shows the Aegisub main window with everything open:

The two most important areas are the Subtitles Grid and Edit Box.

The grid shows all the subtitle lines in the file you’re working with. Lines are marked with different colours depending on their properties. For example, lines with green background are selected. Lines with blue background are marked as comments and won’t be shown on screen. Lines with a light yellow background are visible on the current video frame. Lines with red text overlap in time with a currently selected line. Click a line here to select it for editing.

Highlights

Mon, 01 Jan 0001 00:00:00 +0000

Some highlights of Aegisub:

Simple and intuitive yet powerful interface for editing subtitles

With help from such features as spell checking/thesaurus, a translation assistant, call tips for override tags, syntax highlighting and various macros, translating, editing and quality assuring subtitles is now easier than ever.
Made a mistake? Had a system crash? Don’t worry, Aegisub saves your .ass with features like multi-level undo/redo, auto saving, backups and emergency recovery saving in case of system or program crashes.

Support for many formats and character sets

Aegisub doesn’t lock you into using any specific format; importing and exporting from and to several different formats (ranging from MPEG-4 Timed Text to MicroDVD) is supported.
Multiple language subtitles? Legacy programs without Unicode support? No problem, Aegisub has full support for both Unicode and most common legacy encodings; both reading and writing.

Powerful video mode

Nearly all video formats are supported out of the box, but if that isn’t enough, Aegisub can also use your system’s DirectShow environment to open any format you can play in Windows Media Player.
Automatic live preview of subtitles updated as you type, showing you exactly what the subtitles will look like in the player.
Full support for variable framerate video and Matroska timecodes. Capable of reading timecodes directly from Matroska files for seamless VFR work.
Problems with anamorphic video? Overscan? Aegisub has the tools to handle it.

Visual typesetting tools

Typesetting on easy mode! No need to manually edit override tags; drag, rotate or clip the subtitles directly on the video frame using your mouse.
Want to re-use typesetting on a video of different resolution or aspect ratio? Can’t figure out what color that sign is using? Aegisub has the tools to help you deal with it.

Intuitive and customizable audio timing mode

Time dialogue or karaoke in any way you want with the heavily customizable audio interface; less painful than ever! Use features such as the spectrum analyzer mode or the automatic timing post-processor for even more efficient timing.
Support for nearly every audio format in existence, and DirectShow support for if you manage to find one too obscure for libavcodec.

Fully scriptable through the Automation module

Is all the above not enough? Extend the program with your own macros or export filters using scripting in Lua.
Comes with several ready-made scripts for quick and easy generation of your very own karaoke effects.

Credits

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub was originally written by Rodrigo Braz Monteiro with significant contributions from Niels Martin Hansen. Development was lead by Monteiro through 2008, Hansen through 2010, and by Thomas Goyne from 2011 onward.

Programming

Main Programmers:
- Rodrigo Braz Monteiro (ArchMage ZeratuL) - Lead developer, video system, audio system, subtitles I/O, tools
- Niels Martin Hansen (jfs) - Automation, Lua automation, audio system, tools
- Thomas Goyne (Plorkyeran) - Lead developer for 3.0 onwards.
Staff Contributors:
- Karl Blomster (TheFluff) - General code, FFmpegSource video provider
- Fredrik Mellbin (Myrsloik) - FFmpegSource and Avisynth-related code
- Amar Takhar (verm) - New unix build system
- David Lamparter (equinox) - Unix port
- Alysson Souza e Silva (demi_alucard) - General code
Other contributors:
- Dan Donovan (Dansolo) - Miscellaneous tools
- Patryk Pomykalski (Pomyk) - Miscellaneous patching
- ai-chan - ASSDraw3
- Evgeniy Stepanov (Azzy) - Some Linux patches, libass
- Mike Matsnev (Haali) - Some DirectShow code and Matroska Parser library
- 2points - Linux patches
- p-static - Linux patches
- David Conrad (Yuvi) - Mac patches
- Daniel Moscoviter (Mosc) - General patches
- Harukalover - Usability, various patches
- SAPikachu - General patches
- tophf - General patches
- nodame - General patches

Installer

2.x:
- Niels Martin Hansen (jfs)
- Fredrik Mellbin (Myrsloik)
- Rodrigo Braz Monteiro (ArchMage ZeratuL)
Previous:
- movax

Manual

3.x:
- Thomas Goyne (Plorkyeran)
2.x:
- Karl Blomster (TheFluff)
- Niels Martin Hansen (jfs)
- Rodrigo Braz Monteiro (ArchMage ZeratuL)
Previous:
- Motoko-chan
- Kobi
- movax
- Jcubed

Hosting

Current:
- DeathWolf: SVN repository for versions 2.1.2+
- Sigurd Tao Lyngse (Bot1): Forums and Main Wiki
- Niels Martin Hansen (jfs): Bug Tracker
- Marcello Bastéa-Forte: Documentation Wiki
- Rodrigo Braz Monteiro (ArchMage ZeratuL): Domain administration
Previous:
- David Lamparter (equinox): SVN repository for versions 2.00 - 2.1.2
- BerliOS: SVN repository for version 1.10
- Mentar: SVN repository up to version 1.09
- Bot1: Bug Tracker

Localization files

2.00 translations:
- ArchMage ZeratuL: Brazilian Portuguese
- Ereza: Catalan
- Yuri: Hungarian
- Hiroshi: Japanese
- Jeroi: Finnish
1.11 translations:
- Karasu: Traditional Chinese
1.10 translations:
- TechNiko: French
- Crysral: French
- thrash-sensei: Russian
- equinox: German
- Nesukun: Spanish
- EmBolo: Italian
- Mazinga: Italian
- oblisk: Korean
- mulrich: Danish

Additional thanks

Combined Community Codec Pack staff
Gabest for VSFilter
squid_80 for the x64 builds of Avisynth and CSRI-enabled VSFilter
Firebird for some of the toolbar icons
Kayle for help with Win32 VfW interface
ender for yawning a lot
Alpha testers: b0nk, Bot1, deathbygirl, DoGfOoD, grimlock, Jagobah, Jcubed, Kintaro, Kobi, kodachrome, maxx-, mASSIVe, Maya, Mentar, movax, msb, neo2sonic, nich, nwa, omgifos, SOzuken, TheFluff, thrash_sensei, Vincent, zegnat

About

Aegisub includes portions from the following other projects:

General Disclaimer

Mon, 01 Jan 0001 00:00:00 +0000

This manual is a work in progress. It is at present incomplete and no information in it can be taken for granted. We attempt to be accurate on every point, to a reasonable degree.

Aegisub is software under constant development. While it is a goal to provide up-to-date documentation there will almost always be cases where the actual functionality of the program has changed since this documentation was last updated.

Support Aegisub

Mon, 01 Jan 0001 00:00:00 +0000

Do you want to support Aegisub? Well, it’s easy!

Feedback

You can give us feedback - comments, critiques, suggestions, etc. Bug reports and feature requests are always welcome. Check out our Discord server and the bug tracker, or stop by for a chat in the IRC channel.

Spreading the word

Like Aegisub? Tell your friends about it! Spreading the word is a good way of helping Aegisub to be the best subtitle editor around.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

A small collection of Frequently Asked Questions about Aegisub - mostly stuff that didn’t fit anywhere else.

Karaoke effects?

See the Karaoke Templater tutorials.

Can I create DVD subtitles with Aegisub?

Not directly, but there’s a nifty program called MaestroSBT that can convert SSA to VOBSubs. It does have quite a bunch of restrictions on what tags and other things may be used, so reading its manual first is advised. Also note that it does not accept ASS - only SSA. You can use Aegisub’s File -> Export… dialog to save real SSA files.

Tutorials

Mon, 01 Jan 0001 00:00:00 +0000

The following tutorials are available for Aegisub:

Video Tutorials (Screencasts)

Dialogue Timing

Description: A video describing how to time using Aegisub.
By: Karl Blomster
Link: https://mod16.org/aegisub/timingtutorialimprovisation.mkv
Description: A video showing an experienced user timing at full speed in Aegisub.
By: Karl Blomster
Link: https://mod16.org/aegisub/timing-fullspeed.mkv

Karaoke Timing

TODO: Actually do this

By: Niels Martin Hansen

Text tutorials

Karaoke timing (work in progress) — Enter the words for a song and add time-codes to the words
Karaoke Inline effects Tutorial
Karaoke Furigana Tutorial
Karaoke Templater (incomplete) — Easy way to add special effects to karaoke, ranging from the most basic effects to very advanced ones.

Karaoke Timing Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial will teach you how to load a song into Aegisub, how to enter the words for the song and how to add time-codes to the words to synchronise them with the song.

You don’t need to have used Aegisub before to follow this tutorial.

Before we begin

There’s a few things you need to have ready before starting:

The song itself. This can for example be as an MP3 file or inside a video. Aegisub can read the sound from video files, you don’t need to create a separate sound file if the song is on a video.

The words for the song. It’s easiest if you have them in a plain text file (.txt file) broken into verses and stanzas already.

I am using an English song for demonstration here, but many of the more advanced functions in Aegisub are designed for use with songs in Japanese and other languages that often need transcription or transliteration into Latin script. I will show how to use those in a video tutorial.

Inline effects Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Karaoke inline-fx (inline effects) is a way of marking up timed karaoke to assign different effects to different parts of a line.

By itself, inline-fx markup doesn’t do anything, it only has an effect when a karaoke effect script that understands it is applied to the timed karaoke.

The markup

Inline-fx tags are (otherwise invalid) ASS override tags of the form \-effectname, where effectname is the name of the inline-fx defined.

Furigana Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Furigana (in Aegisub often shortened to furi) refers to little phonetic guide characters written along the main text in Japanese, specifically using the hiragana phonetic alphabet to describe how the ideographic kanji characters should be pronounced. Putting smaller text next to a main line of text is in general referred to as ruby text, but since the implementation discussed here is designed specifically with Japanese furigana in mind, the ruby text is also referred to as furigana everywhere.

Editing Subtitles

Mon, 01 Jan 0001 00:00:00 +0000

Editing subtitles is what Aegisub is made for. This page will deal with basic text editing of subtitle lines; for more information on the typography of subtitles, see typesetting. For information on the timing of subtitle lines, see working with audio.

Opening subtitles

In the File menu, there are four menu choices that relate to opening or creating subtitles:

New subtitles: Create a new, blank script (i.e. close the current file).
Open subtitles: Open an existing subtitles file or import subtitles from a Matroska container file.
Open subtitles with charset: Opens subtitles but lets you choose what character set Aegisub will use to interpret the file. Usually not needed, but if you have a file in an unusual charset Aegisub will occasionally misdetect it.
Open subtitles from video: Open the subtitles muxed into the currently open video file. This currently only works with Matroska video files.
Open Autosaved Subtitles: Open a file created by Aegisub’s autosave. Useful if Aegisub crashes when you had unsaved changes or just if you want to open an older version of a file.

When you open a subtitles file that is not detected as Unicode, Aegisub will attempt to guess what character set it is encoded with. If it is unsure, it will ask you to choose from two or more likely alternatives. If the result looks garbled or otherwise incorrect, try reopening it with another character set.

Exporting Subtitles

Mon, 01 Jan 0001 00:00:00 +0000

In addition to the normal “Save” and “Save as” functions, Aegisub also has an “Export” feature, which can transform the entire script through various export filters. This is used for a number of things ranging from framerate conversions over karaoke effect generation to just saving to other formats and/or character sets.

The export dialog

The upper half of the window contains the available filters. Ticking one or more of them will apply them in the order they are listed; use the move up/down buttons to change the order. The lower half contains a brief description of the selected filter.

Applying Subtitles

Mon, 01 Jan 0001 00:00:00 +0000

In digital encoding, there are two main ways of including subtitles in a video: softsubbing and hardsubbing. Both methods has unique advantages and disadvantages, along with various arguments both for and against each method.

Hardsubbing

Hardsubbing is a method that “burns in” subtitles into the actual video portion of a movie. Digital hardsubs are much like subtitled VHS tapes; the subtitles cannot be turned off.

Advantages of Hardsubbing

Hardsubbing is usually much less demanding on the playback device. Since the text is already part of the video, it will only take as much processing as the unsubtitled video would. You are also often able to make special effects that would be difficult to replicate in a soft subtitle format, because of the large amount of CPU usage required to renderer them. Even in softsubbed anime fansubs, the opening and closing karaoke are often hardsubbed because of the special effects used.

Spell Checker

Mon, 01 Jan 0001 00:00:00 +0000

To help you with quality assurance of your subtitle scripts, Aegisub features a complete spell checker. It uses the Hunspell library, which is based on OpenOffice.org’s MySpell, which means it’s at least as good as one you’d find in a sophisticated word processing program. It can be found in the Subtitles menu -> Spell Checker. It also spell-checks as you type and can to some degree be controlled from the subtitle edit box’s right-click menu (see editing subtitles).

Translation Assistant

Mon, 01 Jan 0001 00:00:00 +0000

The translation assistant is a valuable tool for translating subtitles from one language to the other. It allows you to translate in the most efficient possible manner, by letting you type the translated text without having to worry about selecting the original, or forgetting what was written in it. It also parses ASS override tags, and will skip over them.

Overview

The assistant window is simple: it shows you the original raw line, and a box where you can type the translation. There is also a list of hotkeys specific to this window, and a checkbox to enable previewing, if you have the corresponding video set up. Having this option enabled will automatically jump to the current line when you change it.

Paste Over

Mon, 01 Jan 0001 00:00:00 +0000

The paste over tool is a “smart” variant of the good old Ctrl+C & Ctrl+V combo. It allows you to paste any given field(s) of one or more lines to the corresponding fields of other lines, without affecting the other fields. It can be found under the Edit menu -> Paste lines over, or by right-clicking on the subtitles grid.

To use it, first copy one or more lines with the familiar copy function (right-click -> copy, or Ctrl+C). Then select the line(s) you want to paste to, and click paste lines over (or press Ctrl+Shift+V. You will then get a dialog box that looks like this:

Select Lines

Mon, 01 Jan 0001 00:00:00 +0000

The select lines tool is useful for finding and selecting all lines in the script that matches certain criteria. This can be useful from a number of things ranging from deleting all comment lines to finding all lines said by a certain actor. The tool can be found in the Subtitles menu -> Select lines.

Match

These controls what criteria will be used for selecting the lines.

Match: Select all lines that match the criteria.
Doesn’t match: Select all lines that don’t match the criteria.
Match case: Controls case sensitivity, i.e. if the tool should care about the difference between lower and upper case or not.
Exact match: Matches the lines that matches the given string exactly.
Contains: Matches the lines that contains the given string.
Regular Expression match: Treats the string as a regular expression or “regex”, and matches if said expression matches. For a regular expressions tutorial, try reading the perlretut manual page or googling. For a reference of the exact syntax supported by Aegisub, see the wxWidgets regular expressions reference page.

In field

This option controls what field of each line will be used for the matching mentioned above. Possible alternatives are:

Typesetting Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Wikipedia’s definition of typesetting: “Typesetting involves the presentation of textual material in graphic form on paper or some other medium.” In a subtitling context, this means three things:

Presenting (a translation of) the spoken dialogue to the viewer in an easily readable and visually pleasing form.
Translating any foreign-language background texts (such as episode titles, scene information like time/place and other plot-important writings on things in the background) and presenting the translation to the viewer, preferably so that it appears that the translation was there all along (yet retaining readability).
Designing other texts (logotypes, karaoke, etc. etc.) that should be displayed on the video.

Particularly in the fansub community, the word “typesetting” usually refers to the second or third of these three.

Working with Video

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub isn’t a video (or media) player, but it still supports loading and working with video in various ways. This page is a reference of how Aegisub’s loading and handling of video works; for a gentler introduction on how to just get things to display properly you may want to read the Visual_Typesetting pages.

Opening video

To load a video file, go to the Video menu and press Open video file. What video files you can open depends on your video provider. To use a dummy (mockup, blank) video, press Use dummy video.

Editing styles

Mon, 01 Jan 0001 00:00:00 +0000

A style in the ASS format is a set of typographic formatting rules that is applied to dialogue lines. The style parameters can be overridden with override tags; the styles exist so that you won’t have to type out all the overrides for each line.

The styles manager

Aegisub’s styles manager tool (accessed from the Subtitles menu) provides various means of organizing, saving and editing styles. It looks like this:

Visual Typesetting

Mon, 01 Jan 0001 00:00:00 +0000

TODO: Screenshots need to be updated

Overview

Play

Play the video and, starting at the currently displayed frame. See Video for comments on playing video in Aegisub.

Play line

Play the video starting at the first frame of the currently active line, stopping at the end of the line.

Video autoseek

Toggles automatic seeking of the video to the first frame of a line whenever a new line is selected.

ASS Override Tags

Mon, 01 Jan 0001 00:00:00 +0000

The following is a list of every tag supported by the Advanced Substation Alpha format. This is basically a detailed version of ass-quickref.txt. See the tutorial for an introduction to typesetting, using some basic tags.

Special characters

The following tags are written in the middle of the text, and not inside override blocks (i.e. not between { and }).

Soft line break

\n

Insert a forced line break, but only when in wrapping mode 2. (See the \q tag). Note that this is a lowercase n.

Colour Picker

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub introduces a more advanced color picker than the default Windows one. It allows you to enter color values using various color spaces, in both HTML and ASS hex, pick colors from a mini-screenshot and use three different color spectrums for graphically picking colors.

Overview

The color picker has the following components:

Color spectrum
Parametric settings for four color-spaces
HEX input for ASS and HTML formats
Pick-from-screen control, for taking a mini-screenshot and picking a color from it
List of 32 last picked colors

The last used mode of the color spectrum is remembered.

Styling Assistant

Mon, 01 Jan 0001 00:00:00 +0000

The Styling assistant is a powerful tool for subtitles that have multiple styles, such as cases when several actors have their own style, or for some other reason you have many different styles for dialog lines.

Overview

As seen from the image above, the assistant is composed of the following:

Current line field
Styles available field
Set style window
Keys field
Seek video to line start time checkbox
Play audio button
Play video button

The Current line field displays the line in the subtitles for which the style will be set. The text in it cannot be edited.

Resolution Resampler

Mon, 01 Jan 0001 00:00:00 +0000

The Resolution Resampler is a built-in tool designed to change the resolution of the script while transforming all affected tags so it ends up looking the same. It can also offset all margins (and absolute positions) by a specific value. Uses include merging two scripts with different resolutions, converting a script for a 4:3 video to its 16:9 equivalent, and converting between 1:1 and anamorphic pixel formats.

Overview

There are three main parts to the resolution resampler: the source resolution, destination resolution, and what to do if the source and destination have different aspect ratios.

Fonts Collector

Mon, 01 Jan 0001 00:00:00 +0000

The fonts collector is an automated tool that finds all fonts used in the current script, scans your system’s fonts folder(s) and copies all the relevant fonts to a destination of your choosing. The dialog box looks like so:

The collector can perform any of the following actions:

Check fonts for availability - Checks the fonts folder(s) to see if you have all the fonts used in the current script, and that all fonts contain all of the required glyphs. Do note that for technical reasons, the collector can’t detect or collect fonts that aren’t actually installed (like for example fonts temporarily loaded by a Matroska splitter or a font viewing program).
Copy fonts to folder - Copies all the fonts used on the current script to the given folder.
Copy fonts to subtitle file’s folder - Copies all the fonts used on the current script to the folder containing the subtitle file. This is equivalent to using the above option with the destination set to ?script.
Copy fonts to zipped archive - Copies all the fonts used on the current script to a compressed .ZIP archive.

The fonts collector will output diagnostic information about its doings in the lower half of the window.

Working with Audio

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub has a fairly advanced, customizable audio mode with both the traditional waveform display as well as an alternative spectrum display. Several different timing modes are available for both normal dialog timing and karaoke timing.

Opening audio

To load an audio file into Aegisub, just go to the Audio menu and press Open audio file. If you have a video file (with an included audio track) already loaded, you can use Open audio from video instead, which obviously will load the audio track from the video file you currently have loaded. You can open any type of audio file that your audio provider can decode (more on this below). In addition, if you simply wish to use the audio display without loading any real audio, you can choose Open 2h30 Blank Audio or Open 2h30 Noise Audio.

Timing subtitles to audio

Mon, 01 Jan 0001 00:00:00 +0000

The main audio view

When your audio file has loaded, Aegisub will transform into something like the screenshot below:

You can click and drag just below the audio timeline to change the height of the audio waveform/spectrum display.

Green and red buttons are toggle buttons. A green background indicates that the option is turned on, while a red background indicates that the option is turned off. The buttons and controls are as follows (many of these have keyboard shortcuts associated with them by default):

Shift times

Mon, 01 Jan 0001 00:00:00 +0000

The shift times tool is a batch processor for timestamps; it adjusts the start/end timestamps of many subtitle lines at once in various ways. It is located under Timing -> Shift Times.

It looks like this:

The left part of the window contain the options.

Shift by

These controls decide in which direction and by how much each timestamp will be modified.

Time: How much you want to adjust each timestamp, in hours:minutes:seconds.centiseconds.
Frames: If you have video loaded, you can specify the adjustment time as a number of frames instead. Note that shifting by zero frames will snap the timestamps to the frame times without doing any shifting.
Forward or Backward: Controls in which direction the timestamps are adjusted.

Affect

These controls decide what lines will be processed.

Timing Post-Processor

Mon, 01 Jan 0001 00:00:00 +0000

The timing postprocessor is a highly useful tool for automatically correcting timing in various ways.

Overview

As shown in the screenshot, there are three functions:

Add lead-in and/or lead-out
Make lines that start close to each other continuous by extending or contracting their start and/or end times
Snapping line starts/ends to video keyframes (only available if a video is loaded)

The processing gets applied in the order it is displayed in the dialogue box. That is to say, first lead-in/outs are added, then a check for adjascent lines is performed and lines that are closer than the given threshold are made continuous, and lastly, line start/ends get snapped to keyframes.

Kanji Timer

Mon, 01 Jan 0001 00:00:00 +0000

The kanji timer makes it easy to copy timed karaoke from one set of already karaoke timed lines to another set of yet untimed lines. Primarily intended for adding karaoke to Japanese songs.

Before you start

The kanji timer attempts to pair syllables in one (timed) input line with a given style with syllables in a corresponding (untimed) line with another style. In other words, the timed input lines should all have same style (“romaji” for example) and the untimed ones another (“kanji” for example). Having more timed source lines than untimed destination ones or vice versa can confuse the tool, but it’s usually possible to un-confuse it, see below. In order to correctly pair source lines with destination ones, both sets must be in the same order in the grid. For example, this works:

Automation Overview

Mon, 01 Jan 0001 00:00:00 +0000

The name Automation covers the entire scripting functionality of Aegisub.

About Automation

The single purpose of Automation is — as the name implies — to automate various aspects of subtitle creation and editing. This was originally used mainly for creating karaoke effects, but over time it has expanded in scope to support more general purpose macros which add arbitrary new functionaly to Aegisub.

Some of the goals of Automation:

Macros to automate complex subtitle editing tasks
Export filters to generate complex effects from simpler input
- Karaoke effects
- Translation note boxes
Probably several yet-undiscovered uses

Using Automation

Aegisub comes with several Automation scripts already packaged and ready to use. This includes the advanced Karaoke_Templater script and a collection of macros to simplify some editing tasks.

Karaoke Templater

Mon, 01 Jan 0001 00:00:00 +0000

Karaoke Templater is an Automation script that ships with Aegisub. Its primary purpose is to help creating karaoke effects with a specially designed template language. Karaoke Templater is already installed and ready to use along with Aegisub.

Tutorials: Introducing Karaoke Templater

TODO: Plan more tutorials. Also actually write those above.

Reference

Also see the Automation/Lua/Modules/karaskel.lua section for more information on what’s in the line and syl variables, and more.

Declaring templates

Mon, 01 Jan 0001 00:00:00 +0000

This page describes how a template line or code line is declared.

Template lines and code lines are always marked Comment.

The first space-separated word in the Effect field determines whether a line is a template line, a code line, a timed karaoke line, a styled karaoke line or something otherwise undetermined.

If the first word in the Effect field is template, the line is a template line.

If the first word in the Effect field is code, the line is a code line.

If the Effect field is exactly equal to fx, the line is a styled karaoke line. Styled karaoke lines are deleted during execution of Karaoke Templater.

If the Effect field is Karaoke, karaoke or empty, the line is a timed karaoke line.

If the Effect field contains anything else, the line is an undetermined type and is not touched by Karaoke Templater.

Template lines and code lines can have additional text after the template or code keywords. This text is parsed as a series of space-separated words and is called modifiers. See Template modifiers for more information on this.

Execution order

Mon, 01 Jan 0001 00:00:00 +0000

This page describes various technical details about how Karaoke Templater (kara-templater) works and will try to explain why various things work as they do and why some things can’t and won’t work.

Most of this is technical details you don’t need to know to use kara-templater, but if you see some behaviour you don’t understand this page might explain it.

Concepts

These are some terms and concepts used throughout the description. The names are close to or the same as those used in the actual script.

Modifiers

Mon, 01 Jan 0001 00:00:00 +0000

Template lines and code lines can take a number of modifiers.

This is a space-separated list of words in the Effect field following the template or code keyword.

While modifiers can be combined to some extent, not all are compatible, and not all work on both code lines and for templates.

There is a special set of modifiers that declare the class of the template line or code line.

Class declaring modifiers

Both template lines and code lines can be produced without having a class modifier. Having one is still recommended for clarity, however.

Inline-variables ($-variables)

Mon, 01 Jan 0001 00:00:00 +0000

This page describes the inline variables also known as dollar variables available in Karaoke Templater.

How to use inline variables

All inline variables start with a dollar-sign. They only work in template lines, not in code lines. You can, however, use them in code blocks on template lines.

Here is an example of how a template text using inline variables could look:

{\pos($x,$y)\t($start,$end,\bord0)}

The $x $y $start $end parts are the inline variables in the template.

Code lines and blocks

Mon, 01 Jan 0001 00:00:00 +0000

Code lines and blocks in Karaoke Templater allows you to create advanced effects by incorporating small snippets of Lua code. This can range from simple mathematical expressions adding two numbers to complex functions that for example could generate various shapes in cycling colours.

Both code lines and code blocks are run in a separate semi-closed execution environment, meaning they are mostly undisturbed by the primary Lua environment the Karaoke Templater script itself runs in. For an overview of what variables are available in the code line/block execution environment see: Code execution environment.

Execution environment

Mon, 01 Jan 0001 00:00:00 +0000

The Lua code in code blocks and on code lines is run in a separate global environment such that it won’t accidentally disturb the main script function.

You can store your own data in this environment for use later, for example pre-compute some values on code-lines and later insert them using code blocks, but it also contains several pre-defined variables and functions designed to make it easier writing effect templates.

Automation Tutorials

Mon, 01 Jan 0001 00:00:00 +0000

A simple example

Mon, 01 Jan 0001 00:00:00 +0000

Welcome to the first tutorial in using Karaoke Templater to create karaoke effects. We’ll start out with something simple and then continue on to more advanced effects throughout the series.

Finding Karaoke Templater

You can run Karaoke Templater in two different ways. For now we’ll just concentrate on one of them.

Look under the Automation menu in Aegisub.

You should see the option called Apply karaoke template, though it will be unavailable. This is what you’ll select to use the “templates” we’ll be writing throughout these tutorials. Right now it’s unavailable because you haven’t entered any templates. We’ll get to that in a moment.

Using math expressions

Mon, 01 Jan 0001 00:00:00 +0000

In the previous tutorial we saw how to use the basic features of Karaoke Templater to make simple karaoke effects. We’ll continue where we left off here, by expanding on the basics from last tutorial.

TODO: make and insert screenshots

Preparations

As before, you’ll still need some timed karaoke and a video to preview the effects. I won’t go into further details with that here.

Adding a fadeout

To recap, here’s the effect from the end of last tutorial:

Lua Reference

Mon, 01 Jan 0001 00:00:00 +0000

The Automation 4 Lua scripting engine is based on the version 5.1 series of the Lua scripting language.

This manual will not deal with the Lua language itself nor the standard libraries shipping with Lua, but only the additional functions and data structures provided by the Aegisub Automation 4 Lua interface. Please see the Lua 5.1 manual for details on the language itself and its standard libraries.

General overview of the organisation of Automation 4 Lua

The smallest legal Automation 4 Lua script is an empty file, but that won’t be able to do anything interesting.

Registration

Mon, 01 Jan 0001 00:00:00 +0000

Registration covers presenting your Automation 4 Lua script to Aegisub, providing information about it and registering what features it provides.

Features explained

One of the primary concepts in Automation 4 is the feature. A feature is something a script makes available for Aegisub to call back in response to a user action.

A feature is not a plain callback. Rather, it’s usually a set of several callback functions as well as some information on how they should be presented to the user in the GUI.

Subtitles object

Mon, 01 Jan 0001 00:00:00 +0000

This page describes the subtitle file interface use in Automation 4 Lua scripts to manipulate subtitle files.

There is one special object (the subtitles user data object) which has a number of functions, and a number of table formats defined.

The subtitles object

Most Automation 4 Lua feature functions are passed a subtitles object when called. This object is used to obtain data from and manipulate the subtitles the feature is being applied on.

Progress reporting

Mon, 01 Jan 0001 00:00:00 +0000

There functions are used to report various status and progress back to the GUI while a script is running.

Progress reporting

A progress dialogue box is always shown when an Automation 4 Lua script is running. You can use these functions to control what is displayed in it.

aegisub.progress.set

Synopsis: aegisub.progress.set(percent)

Set the position of the percent-done bar in the progress window.

percent (number): Number from 0 to 100.

aegisub.progress.task

Synopsis: aegisub.progress.task(msg, ...)

Dialogs

Mon, 01 Jan 0001 00:00:00 +0000

These functions are used to display dialogs for the user to interact with.

Display dialog functions

aegisub.dialog.display

Synopsis: button, result_table = aegisub.dialog.display(dialog, buttons, button_ids)

This function displays a configuration dialog to the user and waits for it to close. It then returns whether the user accepted or cancelled the dialog, and what values were input.

@dialog (table): A Dialog Definition table containing the controls to be in the dialog.
@buttons (table): Optional. This is an array of strings defining the buttons that appear in the dialog. If this is left out, empty or is otherwise not a table, the standard Ok and Cancel buttons appear. The strings in this table are used as labels on the buttons, and for identifying them in the return values of the function.
@button_ids (table): Optional. A table which specifies which buttons in the dialog correspond to which platform button IDs, making it possible to specify which button will be triggered if the user hits Enter or ESC.
button (boolean or string): If no custom buttons were specified, this is a boolean telling whether Ok (true) or Cancel (false) were clicked in the dialog. If custom buttons were specified, this is the text on the button clicked by the user. Even if custom buttons were specified, this can still be boolean false if the user closes the dialog without pressing any button.
result_table (table): The Dialog Result table corresponding to the values the user input in the dialog.

Example

config = {
{class="label", text="Times to frobulate", x=0, y=0},
{class="intedit", name="times", value=20, x=0, y=1}
}
btn, result = aegisub.dialog.display(config,
{"Frobulate", "Nevermind"},
{"ok"="Frobulate", "cancel"="Nevermind"})
if btn then
frobulate(result.times)
end

aegisub.dialog.open

Synopsis: file_name = aegisub.dialog.open(title, default_dir, default_file, wildcards, allow_multiple=false, must_exist=true)

Misc. APIs

Mon, 01 Jan 0001 00:00:00 +0000

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.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.

Lua Modules

Mon, 01 Jan 0001 00:00:00 +0000

A number of Lua modules are included with Aegisub. Some of these, such as karaskel.lua implement subtitle-specific functionality, while others such as re fill holes in the Lua standard library.

Using modules

Simply write modulename = require 'aegisub.modulename' at the top level of a script. For example, to include the re modules, re = require 'aegisub.re'.

Note that if you look at older scripts you will probably see several other methods for including modules, such as include. These have been deprecated in favor of following the modern lua module style introduced with Lua 5.2.

karaskel.lua

Mon, 01 Jan 0001 00:00:00 +0000

The Automation 4 karaskel.lua include file contains several functions intended to help the development of karaoke effects with Automation 4 Lua. It also defines several new data structures, and extensions to those defined by Automation 4 Lua itself.

karaskel.lua itself includes utils.lua and unicode.lua so you do not need to include those yourself when using karaskel.lua.

Using karaskel.lua is strongly recommended when creating karaoke effects, and it can also be useful for other tasks as it contains several text layouting functions.

utils.lua

Mon, 01 Jan 0001 00:00:00 +0000

The Automation 4 Lua include file utils.lua contains various support functions to aid writing Lua scripts. There is no general theme for the file.

Usage

Import this module with util = require 'aegisub.util'

Table functions

Duplicating tables in various ways is a common task. util provides some functions to handle the most common cases.

copy

Synopsis: newtable = util.copy(oldtable)

Makes a shallow copy of the table passed as parameter. Shallow here means that it does not dive into contained tables and copy those as well. For example, if oldtable.st refers to a table, newtable.st will refer to the same table, and changes made to newtable.st will also be reflected in oldtable.st and vice versa.

unicode.lua

Mon, 01 Jan 0001 00:00:00 +0000

The unicode module for Automation 4 Lua contains various helper functions for working with UTF-8 encoded text.

Usage

Import this module with unicode = require 'aegisub.unicode'.

unicode.charwidth

Synopsis: width = unicode.charwidth(instring, index=1)

Returns the number of bytes occupied by the UTF-8 encoded code points starting at position index in instring. The character pointed to is assumed to be a prefix byte (i.e. the first byte of the code points).

cleantags.lua

Mon, 01 Jan 0001 00:00:00 +0000

TODO: Write documentation

clipboard

Mon, 01 Jan 0001 00:00:00 +0000

The clipboard module supplies functions for reading from and writing to the clipboard.

Usage

Import this module with clipboard = require 'aegisub.clipboard'

clipboard.get()

Synopsis: text = clipboard.get()

Get the current contents of the clipboard as a string. Returns nil if the clipboard does not currently contain text or if an error occurs.

clipboard.get()

Synopsis: clipboard.set(new_text)

Set the clipboard contents to a string. Returns true if the clipboard could be set, and false if an error occurred.

re

Mon, 01 Jan 0001 00:00:00 +0000

The re module is a wrapper around boost::regex, intended as a full replacement for Lua’s built in regular expressions. It has two main advantages over Lua’s:

Full Unicode support. Lua regular expressions operate on bytes rather than characters, which frequently causes problems with multibyte characters.
A more powerful and flexible syntax. Properly speaking, Lua does not support regular expressions; rather it has a basic pattern matching language that supports a small subset of what can be done with regular expressions. boost::regex, on the other hand, supports perl-compatible regular expressions.

Usage

Import this module with re = require 'aegisub.re'.

Automation Manager

Mon, 01 Jan 0001 00:00:00 +0000

The Automation Manager window is used to view, load and unload Automation scripts.

The Automation Manager window is opened from the Automation menu or with the toolbar button.

The script list

The main area of the window is a list of all script files loaded. It’s important to remember that one script file can contain several features, for example one script file can define two macros and one export filter.

Scripts can be loaded in one of two ways. In the screenshot above, most of the scripts are global (autoloaded), as indicated by the “G” in the leftmost column. Global scripts are automatically loaded along with Aegisub. They are put in one of the Automation_autoload_folders. You can not unload global scripts; you must remove them from the autoload directory, and then rescan the autoload directory.

Running macros

Mon, 01 Jan 0001 00:00:00 +0000

Automation macros appear as options in the Automation menu.

The first option in the Automation menu, before the separator, always opens the Automation/Manager window.

Below the separator is a list of all macros loaded. In the example above seven macros are loaded. The third, Karaoke_Templater is unavailable though, because the macro has determined it can’t be run on the subtitles. In this case, because the subtitle file has no karaoke templates. Other macros might be unavailable for other reasons. The fourth has had a hotkey set in the preferences dialog

Standard macros

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub includes several macros. Here’s a line-up of them.

Apply karaoke template

This is the macro incantation of Karaoke Templater. See the page on Karaoke_Templater for how to use this.

This macro is only available when there is at least one template line in the subtitle file.

Make full-width

Converts all ASCII characters to Japanese “full-width” variations of them.

This can be useful if you need to typeset a sign translation vertically, such that the letters are “stacked”.

History of Automation

Mon, 01 Jan 0001 00:00:00 +0000

The Automation system in Aegisub has evolved from a very basic and hardly useful stand-alone system for creating basic karaoke effects into a very powerful extension mechanism. Here’s a short account of its history, from the principal author of the systems.

Automation 1, really just Karaoke Effector

The Karaoke Effector program was originally created for making karaoke effects for a small translation project, that later died. It was written in Borland Delphi and used Lua 5.0 for scripting. This use of Lua is the primary reason I even call it “Automation 1” today. It basically allowed creating effects similar to what the simple-k-replacer script from Automation 3 does, but in a more complicated and not as usable way.

Aegisub Options

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub is highly customizable and hence has a large amount of user-changeable options. These are available in the options dialog box, found in the View menu. This page is a reference of all the available options.

Aegisub stores all its configuration in a plain text file called config.json which by default is stored in the ?user directory. If you want to reset Aegisub to its default options without reinstalling the program, you can just delete config.json and restart Aegisub.

Autosave

Mon, 01 Jan 0001 00:00:00 +0000

By default Aegisub automatically saves a backup copy of every subtitle file you open, along with another copy every minute (if any changes have been made in the last minute). These copies can be found in %APPDATA%\Aegisub\autosave on Windows, ~/.aegisub/autosave on Linux, and ~/Library/Application Support/Aegisub/autosave on OS X. In addition, they can be browsed directly within Aegisub at File → Open Autosaved File…

Aegisub automatically cleans up old files in the autosave directory, so the automatic backups should not be used for long-term storage of files.

Path Specifiers

Mon, 01 Jan 0001 00:00:00 +0000

Aegisub uses a simple system for denoting file locations. Most pathnames in Aegisub can be written starting with special variables that each refer to specific locations. Note that path specifiers should always have a trailing slash unless they are the entire path (i.e. ?scripta doesn’t work).

?data: The location where application data are stored. On Windows this is the installation directory (the location of the .exe). On Mac OS X this is inside the application bundle. On other POSIX-like systems this is $prefix/share/aegisub/.
?user: The location for user data files, such as configuration files, automatic back-ups and some additional things. On Windows this %APPDATA%\Aegisub\, on Mac OS X this is $HOME/Library/Application Support/Aegisub/ and on other POSIX-like systems this is $HOME/.aegisub/. In portable mode this is changed to ?data.
?temp: The system temp directory. Audio cache and any required temporary subtitle files are stored here.
?local: The local user settings directory. Cache files which should be persisted across runs, such as FFMS2 indexes and the fontconfig cache are stored here. %LOCALAPPDATA%\Aegisub on recent versions of Windows, and equal to ?user everywhere else.
?script: Only defined if a subtitles file is open and saved somewhere, in which case it points to the directory the script is in.
?video: Only defined if a video file is loaded. Points to the directory the video file in is. Do note that this is not a good place to save things with dummy video loaded.
?audio: Only defined if an audio file is loaded. Points to the directory the audio file in is. Do note that this is not a good place to save things with dummy audio loaded.

Script Properties

Mon, 01 Jan 0001 00:00:00 +0000

The script properties are some headers and other options that affect the entire script in various ways. They can be accessed from the File menu -> Properties.

The properties are:

Title, Original script, Translation, Editing, Timing, Synch point, Updated by and Update details - These are for informational purposes only and do not affect rendering in any way. Set them to appropriate values if you find them useful.
Resolution, YCbCr Matrix, Scale border and shadow - See the Script Resolution page for the meaning of these fields.

Script Resolution

Mon, 01 Jan 0001 00:00:00 +0000

ASS subtitle files are, to some extent, video independant and can be used with video files other than the one they were created with. This is achieved by using a virtual video resolution which controls how font sizes and coordinates are interpreted, which is commonly known as the “script resolution”. Unfortunately, due to some bugs in the reference implementation of the subtitle format (VSFilter), rendering subtitles whose script resolution is not equal to the actual video resolution works poorly.

Attachment Manager

Mon, 01 Jan 0001 00:00:00 +0000

The attachment manager allows you to attach fonts and/or pictures to your script (by encoding them as text). This is occasionally useful for sharing fonts between everyone who is working on a script without having to send the fonts as separate files. However, it is quite limited and is prone to causing problems.

Overview

The entire dialogue is fairly self-explanatory. The two “Attach …” buttons add attachments, “Extract” extracts existing attachments into separate files, and “Delete” deletes attachments from the subtitles file.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

REDIRECT Audio#basicaudiotiming

Mon, 01 Jan 0001 00:00:00 +0000

REDIRECT Shift_Times

Mon, 01 Jan 0001 00:00:00 +0000

REDIRECT Options#hotkeys

Automation script feature

Mon, 01 Jan 0001 00:00:00 +0000

In Automation 4 a feature is a function a script makes available to Aegisub. Currently two kinds of features are specified: Export filters and macros.

If a script defines two macros and one export filter, it is said to have defined three features in total.

Karaoke Effect

Mon, 01 Jan 0001 00:00:00 +0000

Karaoke is (amateur) singing along to a song, usually a version of the song with the main vocals removed. When singing karaoke the lyrics to the song are usually presented on a TV screen and highlighted as they are to be sung.

In subtitling however, karaoke usually refers to those lyrics themselves. The karaoke effect refers to the way they are highlighted.

So, a karaoke effect is a visual effect synchronised with a song, used to help singing karaoke.

Macro

Mon, 01 Jan 0001 00:00:00 +0000

In computer programs, a macro is a (usually relatively small) snippet of program code that can easily be added to the program, to add a new function or such, intended to automate some aspect of using the program.

Aegisub Docs on Aegisub

Main Page

Starting points #

What is Aegisub?

Overview

Highlights

Credits

Programming #

Installer #

Manual #

Hosting #

Localization files #

Additional thanks #

About #

General Disclaimer

Support Aegisub

Feedback #

Spreading the word #

FAQ

Karaoke effects? #

Can I create DVD subtitles with Aegisub? #

Tutorials

Video Tutorials (Screencasts) #

Dialogue Timing #

Karaoke Timing #

Text tutorials #

Karaoke Timing Tutorial

Before we begin #

Inline effects Tutorial

The markup #

Furigana Tutorial

Editing Subtitles

Opening subtitles #

Exporting Subtitles

The export dialog #

Applying Subtitles

Hardsubbing #

Advantages of Hardsubbing #

Spell Checker

Translation Assistant

Overview #

Paste Over

Select Lines

Match #

In field #

Typesetting Introduction

Working with Video

Opening video #

Editing styles

The styles manager #

Visual Typesetting

Overview #

Play #

Play line #

Video autoseek #

ASS Override Tags

Special characters #

Soft line break

Colour Picker

Overview #

Styling Assistant

Overview #

Resolution Resampler

Overview #

Fonts Collector

Working with Audio

Opening audio #

Timing subtitles to audio

The main audio view #

Shift times

Shift by #

Affect #

Timing Post-Processor

Overview #

Kanji Timer

Before you start #

Automation Overview

About Automation #

Using Automation #

Karaoke Templater

Starting points

Programming

Installer

Manual

Hosting

Localization files

Additional thanks

About

Feedback

Spreading the word

Karaoke effects?

Can I create DVD subtitles with Aegisub?

Video Tutorials (Screencasts)

Dialogue Timing

Karaoke Timing

Text tutorials

Before we begin

The markup

Opening subtitles

The export dialog

Hardsubbing

Advantages of Hardsubbing

Overview

Match

In field

Opening video

The styles manager

Overview

Play

Play line

Video autoseek

Special characters

Overview

Overview

Overview

Opening audio

The main audio view

Shift by

Affect

Overview

Before you start

About Automation

Using Automation

Tutorials: Introducing Karaoke Templater

Reference

Concepts

Class declaring modifiers

How to use inline variables

Finding Karaoke Templater

Preparations

Adding a fadeout

General overview of the organisation of Automation 4 Lua

Features explained

The subtitles object

Progress reporting

aegisub.progress.set

aegisub.progress.task

Display dialog functions

aegisub.dialog.display

aegisub.dialog.open

aegisub.cancel

aegisub.text_extents

Using modules

Usage

Table functions

copy

Usage

unicode.charwidth

Usage

clipboard.get()

clipboard.get()

Usage

The script list

Apply karaoke template

Make full-width

Automation 1, really just Karaoke Effector

Overview