DOCSEARCHbyAlgolia
Submit Docs

Aegisub Documentation

repository·master·Indexed 23 days ago

https://github.com/typesettingtools/aegisub

A subtitle typesetting tool. This documentation provides comprehensive guides for building Aegisub from source on Windows, macOS, and Linux, as well as developer instructions for releasing new versions, generating API documentation with Doxygen, and managing translations. It also includes technical details on the AssDialogue class for parsing ASS tags and the luabins library for Lua binary serialization.

Tokens
17.7K
Snippets
38
Records
122
Agent score
84%

What's inside Aegisub

  1. Serialize and deserialize Lua data with luabins

    master

    Luabins is a Lua Binary Serialization Library that allows you to save tuples of primitive Lua types into binary chunks and load them back.

    Supported Types

    Luabins works with:

    • nil
    • boolean
    • number
    • string
    • table

    Unsupported Types

    Luabins cannot save:

    • function
    • thread
    • userdata

    Table Serialization Rules

    1. Metatables are ignored: Only the table data is serialized.
    2. Nesting Limit: Table nesting depth must not exceed LUABINS_MAXTABLENESTING.
    3. References are not honored: On save, table references are not preserved. Each encountered reference becomes an independent object upon loading. For example, a table { t, t } where t = { 42 } will become { { 42 }, { 42 } } (three separate tables) instead of two.

  2. Build Aegisub on Windows

    master

    To build Aegisub on Windows, you need Visual Studio (with Windows SDK), Python 3, Meson, and CMake.

    Optional dependencies for full functionality:

    • msgfmt (via gettext-iconv-windows) for translations.
    • InnoSetup (iscc.exe) for creating installers.
    • 7zip (7z.exe) for creating installers.
    • Moonscript (moonc.exe) for creating installers.

    Steps:

    1. Clone the repository: git clone https://github.com/TypesettingTools/Aegisub.git.
    2. Open the "x64 Native Tools Command Prompt" from Visual Studio.
    3. Generate the build directory: meson build -Ddefault_library=static (add --buildtype=release for release builds).
    4. Build: cd build and then run ninja.

    This produces aegisub.exe.

    To generate installers or portable versions:

    • Installer: ninja win-installer (requires internet and optional dependencies).
    • Portable zip: ninja win-portable.
    git clone https://github.com/TypesettingTools/Aegisub.git
meson build -Ddefault_library=static
cd build
ninja

  3. Update Moonscript for Aegisub automation

    master

    To update the Moonscript dependency used in Aegisub's automation, follow these steps from within the Moonscript repository:

    1. Compile the Lua file: Run the following command to generate bin/moonscript.lua:

      bin/moon bin/splat.moon -l moonscript moonscript/ > bin/moonscript.lua

    2. Modify bin/moonscript.lua:

      • Prepend the final line of the file, package.preload["moonscript"](), with a return so it becomes return package.preload["moonscript"]().
      • Inside the function at package.preload['moonscript.base'], remove all references to moon_loader, insert_loader, and remove_loader (including declarations, definitions, and table entries).
      • Inside the function at package.preload['moonscript'], remove the line _with_0.insert_loader().

    3. Install: Place the modified bin/moonscript.lua into automation/include within the Aegisub repository.

    bin/moon bin/splat.moon -l moonscript moonscript/ > bin/moonscript.lua

  5. Build Aegisub on Linux (Debian-based)

    master

    To build on Ubuntu 24.04 or similar Debian-based systems, install the required build dependencies first:

    sudo apt install build-essential pkg-config meson ninja-build gettext intltool libfontconfig1-dev libass-dev libboost-chrono-dev libboost-locale-dev libboost-regex-dev libboost-system-dev libboost-thread-dev zlib1g-dev wx3.2-headers libwxgtk3.2-dev icu-devtools libicu-dev libpulse-dev libasound2-dev libopenal-dev libffms2-dev libfftw3-dev libhunspell-dev libuchardet-dev libcurl4-gnutls-dev libgl1-mesa-dev libgtest-dev libgmock-dev libportal-gtk3-dev

    Standard Build:

    meson setup build --prefix=/usr/local --buildtype=release --strip -Dsystem_luajit=false -Ddefault_library=static
meson compile -C build
meson install -C build --skip-subprojects luajit

    Packaging for Distribution: If you are creating a package for a Linux distribution, use the following workflow to ensure LuaJIT is correctly handled (Aegisub requires LuaJIT with Lua 5.2 compatibility enabled):

    meson subprojects download luajit
meson subprojects packagefiles --apply luajit

meson setup builddir --wrap-mode=nodownload --prefix=/usr --buildtype=release -Dsystem_luajit=false -Ddefault_library=static -Dtests=false

meson compile -C builddir
meson install -C builddir --skip-subprojects luajit

    Packaging Constraints:

    • LTO: Aegisub cannot be built with Link Time Optimization (LTO).
    • LuaJIT: Requires Lua 5.2 compatibility. It is recommended to use the Meson subproject to statically link a compatible version.
    • libstdc++: Requires version 6.0.32 or later.
    • Wayland: To work directly on Wayland (instead of Xwayland), wxWidgets must be built with EGL enabled. Aegisub will fall back to X11 if EGL is missing.

  6. Build Aegisub on OS X

    master

    Requires Xcode and command-line tools. You can install dependencies using pip3 and homebrew.

    Dependency Installation:

    pip3 install meson
brew install cmake ninja pkg-config libass boost zlib ffms2 fftw hunspell uchardet

# Set environment variables for icu4c
export LDFLAGS="-L/usr/local/opt/icu4c/lib"
export CPPFLAGS="-I/usr/local/opt/icu4c/include"
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig"

    Note: On Apple Silicon, replace /usr/local with /opt/homebrew in the export commands.

    Standard Build:

    meson build && meson compile -C build

    Building a DMG Bundle:

    meson build_static -Ddefault_library=static -Dbuildtype=debugoptimized -Dbuild_osx_bundle=true -Dlocal_boost=true
meson compile -C build_static
meson test -C build_static --verbose
meson compile osx-bundle -C build_static
meson compile osx-build-dmg -C build_static

  7. Release a new Aegisub version

    master

    To release a new version of Aegisub, follow these steps:

    1. Bump version numbers in:
      • meson.build
      • packages/win_installer/portable-comment.txt (two occurrences)
      • po/make_pot.sh (two occurrences)
    2. Create a release candidate build (including a string/feature freeze) and notify translators to update translations.
    3. Update the manual (for large updates): Create a new version of the manual on the website and update the link in src/help_button.cpp.
    4. Update metainfo: Add the new version and release date to aegisub.metainfo.xml.in.in.
    5. Tag and Push: Create and push a new version tag.
    6. Distribute: Upload CI builds to a GitHub release.
    7. Finalize: Link the release on the Aegisub website and add it to the update checking server.
    8. Maintenance: If necessary, create a support branch for backports to keep the master branch available for major changes.

  8. How to change the display language in Aegisub

    master

    To change the language used by the Aegisub interface:

    1. Open the Language menu in Aegisub.
    2. Select your desired language from the list.
    3. If prompted with "Restart Aegisub?", select Yes to apply the changes. Aegisub must be restarted for the new language to take effect.

  9. How to add translations to Aegisub

    master

    Aegisub uses .po files for translation source and .mo files for the compiled binary format used by the application. To add or update a translation, follow these steps:

    1. Prepare the source files: Use aegisub.po for Aegisub-specific strings and wxstd.po for standard wxWidgets strings.
    2. Edit translations: Use a tool like poEdit to open and edit the .po files.
    3. Compile to binary: Once editing is complete, compile the .po files into .mo files.
    4. Install the translation: Place the resulting .mo files in the Aegisub locale directory.

    File Types Reference:

    • *.po: Text-based translation source files (editable).
    • *.mo: Compiled binary translation files (used by Aegisub).

    Note: Ensure you use UTF-8 encoding for all translation files.

  10. Implement a custom Command in Aegisub

    master

    To implement a new command within the Aegisub framework, you must inherit from the cmd::Command class and override the following methods:

    • CMD_NAME(name): Defines the internal command identifier (e.g., app/my_command).
    • operator()(agi::Context *c): The primary execution logic. It receives an agi::Context pointer providing access to the frame, project, dialog, and parent window.
    • Validate(const agi::Context *c): (Optional) Returns true if the command is currently valid to execute (e.g., checking if a provider exists).
    • IsActive(const agi::Context *c): (Optional) Returns true if the command should appear as 'selected' or 'active' in the UI (used for radio buttons or toggles).
    • StrMenu(const agi::Context *c): (Optional) Returns the string to display in the menu.
    • StrDisplay(const agi::Context *c): (Optional) Returns the string to display in the UI status/help area.
    • CMD_TYPE(type): (Optional) Sets the command behavior, such as COMMAND_RADIO for mutually exclusive options or COMMAND_TOGGLE for on/off states.

  11. Aegisub Application Lifecycle and Entrypoint

    master

    Aegisub is built using the wxWidgets framework. The main application class is AegisubApp, which manages the application lifecycle, including initialization (OnInit), the main event loop (OnRun), and cleanup (OnExit).

    Key lifecycle stages include:

    • Initialization (OnInit): Sets up locales, logging, configuration (agi::Options), command systems, hotkeys, and automation script managers. It also initializes the agi::dispatch system for thread-safe event dispatching.
    • Execution (OnRun): Runs the main event loop. If an unhandled exception occurs during execution, it attempts to write a crash report via crash_writer and triggers the exception handling logic.
    • Cleanup (OnExit): Cleans up global resources including frames, clipboard state, configuration objects, hotkeys, commands, and the automation script manager.

  12. Understand AssDialogueBlock and its types

    master

    In Aegisub's ASS processing, an AssDialogue line's text field is conceptually divided into several AssDialogueBlock objects. These blocks represent the different segments of a line, such as plain text, override tags (like {\i1}), comments, or drawing commands.

    Supported block types (via AssBlockType):

    • PLAIN: Standard text without tags.
    • COMMENT: Text wrapped in curly braces {}.
    • OVERRIDE: ASS override tags (e.g., \i1). These blocks contain a collection of AssOverrideTag objects.
    • DRAWING: Drawing commands, which include a Scale integer.

    Example breakdown of Yes, I {\i1}am{\i0} here.:

    1. "Yes, I " (Plain)
    2. "\i1" (Override)
    3. "am" (Plain)
    4. "\i0" (Override)
    5. " here." (Plain)