samaku

samaku is an editor for non-destructive visual typesetting of ASS subtitles. It aims to solve the primary problem of Lua macro-based typesetting workflows, where once a sign has been typeset, it is very hard to make even minor changes without redoing the sign entirely. Instead of destructive Lua macros, samaku includes a Blender-like node editor for non-destructive editing, where a node graph corresponds to a chain of transformations that are instantly, automatically rerun when the inputs are changed.

A secondary goal of samaku is to be an extremely high-performance ASS subtitle editor, effortlessly supporting giant subtitle files (several hundred megabytes or more, hundreds of thousands of events or more).

Note that samaku is currently in a pre-alpha state. It is very incomplete and not yet ready for production use. Most of the foundational work has been done and the app can be used for basic subtitle editing, and the node editor with its NDE paradigm works in principle. However, so far the selection of nodes is very limited, with no way to do most of the important tasks in typesetting. Also, there will be many bugs and other inconveniences. The app is still lacking significant polish in most areas.

I make no promises that I will continue to develop samaku into a usable tool. I tend to work on it in short bursts every now and then, with significant latency periods in between. Nevertheless, I am glad if it can be of interest for someone, even educationally.

Project structure

Technology-wise, samaku uses

• Rust,
• iced for the UI,
• libass for subtitle rendering,
• ffms2 + ffms2-sys for audio and video decoding,
• and libmv + libmv-capi-sys for motion tracking.

See the Cargo.toml for a full list of dependencies.

To understand the project structure, you should have a basic idea of how iced projects are structured in general. The application lives in src/lib.rs, with the Samaku struct containing the state; the messages are defined in src/message.rs. The global update method is in src/update.rs. For the most part, the application consists of a pane grid, containing panes with their own view and update logic; these live in the pane module. Apart from that, there are the following modules in src:

• media/bindings: Thin but safe bindings around the various media libraries.
• media: More integrated bindings to provide specifically the features samaku needs.
• model: Various specific state structs to avoid too much clutter in lib.rs.
• nde/node: The different nodes that can be used in the node editor.
• nde/tags: Code for parsing, manipulating, and emitting ASS override tags. (I intend to eventually extract this module into its own crate, for use by others.)
• nde: Other glue code for non-destructive editing.
• pane: Panes of the pane grid (as mentioned above).
• resources: Static resources needed for the UI.
• subtitle: samaku's internal representations of ASS subtitle data.
• view: UI utilities and custom widgets.
• workers: Any code that needs to run in its own thread.

Apart from samaku's own code, there are the following modules in the root folder:

• benches: Criterion benchmarks for ASS tag handling code.
• tests: Integration tests, mainly also for ASS tag handling code.
• test_files: Static files used for tests.
• libass-sys: Unsafe FFI bindings for libass.
• packaging: Utilities for packaging samaku for distribution.

How to run

Tested on Linux and Windows.

Linux

• Install dependencies:
  • libass (including headers)
  • ffms2 (including headers)
• Run cargo test to ensure the dependencies have been installed correctly.
• Then, start the program using cargo run (debug mode) or cargo run --release (release mode).

It is also possible to build samaku as an AppImage using the packaging/build-appimage.sh script.

Windows

See WINDOWS_BUILD.md.

Usage

For actually using samaku, please also take a look at src/keyboard.rs, which defines global keyboard shortcuts for functionality that is not yet mapped to any buttons or the like in the UI.

License notes

samaku as a whole is licensed under the GPLv3, whose text is available in the LICENSE-GPL file in the project root.

I plan to eventually extract parts of the code (in particular, the ASS override tag processing code) and make it available under more permissive licenses.