How myaamori/subkt works
1. What this repository is
SubKt is a Gradle-based Kotlin DSL plugin/library for automating fansubbing release workflows. It is not a standalone app; the main runtime is a user’s build.gradle.kts, where SubKt generates episode- and batch-scoped Gradle tasks that transform subtitle assets and package/release outputs.
2. Main architectural boundary
The central boundary is between the consumer build script and the SubKt plugin. The plugin exposes a subs { ... } configuration block, task-group helpers, external property access, and template evaluation. Everything else hangs off that entry point.
3. Task graph model
SubKt models work as task groups rather than isolated tasks. A single declaration can generate one task per episode, and optionally batch tasks. The key routing concepts are episode, batch, entry, item(), and batchItems(), which connect task outputs to downstream inputs and let Gradle infer execution order from file/task dependencies.
4. Configuration and templating layer
Inputs are usually not hardcoded. The repo uses external property files plus lazy Gradle Provider/Property values, and Velocity-based template evaluation for strings and file contents. This layer lets tasks reference per-episode/per-batch values, shared secrets, filenames, and generated metadata without eagerly resolving them.
5. ASS subtitle domain layer
The myaa.subkt.ass package is the subtitle model/parser/serializer core. It knows how to parse and serialize ASS files, including sections such as script info, styles, events, project garbage, and extra data. It also exposes typed accessors for styles, events, colors, durations, wrap styles, collisions, and related ASS-specific concepts.
6. Subtitle-processing tasks
The myaa.subkt.tasks side builds on the ASS model to provide release-prep operations like merge, swap, chapter generation, automation execution, and other subtitle transformations. These tasks typically read ASS sources, normalize or modify lines/styles/metadata, and emit new ASS files that can be consumed by later tasks.
7. Muxing and packaging layer
The Mux subsystem is the packaging hub: it combines video, audio, subtitle tracks, chapters, and attachments into MKV/WebM outputs. Its data model includes tracks, track metadata, file options, compression, dimensions, attachments, chapters, and default/forced/language flags. This layer is backed by helper code around mkvmerge, so the external mkvtoolnix toolchain is a real architectural dependency.
8. Validation and metadata utilities
There is a dedicated utilities package for font validation and MKV inspection. Font validation checks the subtitle set against available fonts/glyphs and reports problems before muxing or release. The MKV helper code models container/track/attachment metadata and bridges the plugin to the external container inspection tools.
9. Release and distribution integrations
Beyond local file generation, the task library includes outbound integrations for publishing and transfer: FTP/SFTP, HTTP-based posting, Discord notifications, torrent generation, and tracker-site uploads such as Nyaa/Anidex as documented in the repo. These are downstream “export” edges in the workflow graph and generally consume the artifact produced by muxing or torrent creation.
10. Supporting artifacts
The template/ directory is a starter project layout for consumers, while src/samples/ shows example usage. The large docs/ tree is API documentation generated from the public surface of the packages, and it mirrors the architecture: core DSL, ASS model, task types, and utilities.
11. External dependencies that materially shape the design
The plugin expects Gradle, Kotlin, and a JDK at build time; mkvmerge is required for muxing; and the torrent functionality is supported by the included ttorrent submodule. Those external tools are not incidental—they define the boundaries of the packaging and release subsystems.
12. End-to-end data flow
A typical flow is: source ASS/video/fonts/properties enter the DSL; subtitle tasks transform ASS assets; mux consumes those task outputs plus media/attachments; torrent/upload/publish tasks consume the muxed artifact; and notification tasks can post final links or status. The whole system is file-artifact driven, with Gradle’s dependency graph coordinating execution.
Main entry points: asstasks.kt Subtitle tasks · parser.kt ASS parser · muxtask.kt Mux engine · plugin.kt SubKt plugin
Components 21
Consumer build
Where SubKt is configured and invoked by downstream projects.
- build.gradle.kts · Host build script that applies and configures SubKt.
build.gradle.kts
DSL core
Plugin entry points, property access, and task-group orchestration.
- SubKt plugin · Entry point that exposes the `subs { ... }` DSL and wires task registration.
src/main/kotlin/myaa/subkt/tasks/plugin.kt - Task runtime · Shared task and task-group infrastructure for episode/batch item creation.
src/main/kotlin/myaa/subkt/tasks/tasks.kt - Subs DSL · Configuration surface for properties, template evaluation, task groups, and release context.
src/main/kotlin/myaa/subkt/tasks/asstasks.kt - Property access · External properties and Gradle Provider/Property access bridged into the DSL.
src/main/kotlin/myaa/subkt/tasks/tasks.kt - Template eval · Deferred string and file-content rendering for per-entry and per-batch values.
src/main/kotlin/myaa/subkt/tasks/tasks.kt - Item routing · Episode, batch, entry, item(), and batchItems() routing that links task outputs to downstream inputs.
src/main/kotlin/myaa/subkt/tasks/tasks.kt
Subtitle model
ASS parsing, serialization, and typed subtitle structures.
- ASS parser · Reads and writes ASS files with section-aware parsing and serialization.
src/main/kotlin/myaa/subkt/ass/parser.kt - Script info · ASS script metadata such as title, timing, wrap style, and resolution.
src/main/kotlin/myaa/subkt/ass/parser.kt - Styles & events · Style and dialogue/event line models with typed accessors and serializers.
src/main/kotlin/myaa/subkt/ass/parser.kt - Extra ASS data · Project garbage, extra data, comments, and other non-core ASS sections.
src/main/kotlin/myaa/subkt/ass/parser.kt
Processing tasks
Subtitle transforms and release-prep task families.
- Subtitle tasks · Merge, swap, chapters, automation, and related subtitle-prep operations.
src/main/kotlin/myaa/subkt/tasks/asstasks.kt - Merge · Combines ASS sources and resolves style/script-info conflicts and timestamp handling.
src/main/kotlin/myaa/subkt/tasks/asstasks.kt - Swap · Rewrites dialogue/style mappings through delimiter- and marker-based substitution.
src/main/kotlin/myaa/subkt/tasks/asstasks.kt - Chapters · Generates chapter metadata and intro markers for release packages.
src/main/kotlin/myaa/subkt/tasks/asstasks.kt
Packaging/export
Muxing, torrent generation, and outbound publishing integrations.
- Mux engine · Assembles video, audio, subtitles, chapters, and attachments into MKV/WebM outputs.
src/main/kotlin/myaa/subkt/tasks/muxtask.kt - mkvmerge bridge · Helper layer around mkvmerge and MKV inspection data models.
src/main/kotlin/myaa/subkt/tasks/utils/mkvmerge.kt - Font validator · Checks fonts and glyph coverage before muxing or release.
src/main/kotlin/myaa/subkt/tasks/utils/fontvalidator.kt - Transfers · FTP, SFTP, SSH, HTTP, Discord, Nyaa, Anidex, and torrent release integrations.
src/main/kotlin/myaa/subkt/tasks/discordtask.kt
Supporting artifacts
Samples, template project, and generated docs.
- Template project · Starter build layout for downstream users configuring SubKt.
template/build.gradle.kts - Samples & docs · Example usage and generated API documentation for the public surface.
src/samples/kotlin/tasks.kt
Connections 21
- build.gradle.kts → SubKt plugin: applies · The consumer build applies the plugin to get the SubKt DSL.
- SubKt plugin → Subs DSL: exposes · The plugin exposes the `subs { ... }` configuration block.
- Subs DSL → Property access: reads · DSL values are resolved through property access helpers.
- Subs DSL → Template eval: renders · Configuration strings and file bodies are template-evaluated lazily.
- Subs DSL → Item routing: registers · The DSL declares task groups and item-scoped work.
- Item routing → Task runtime: creates · Item routing drives the underlying Gradle task graph.
- Task runtime → Subtitle tasks: hosts · Task runtime hosts subtitle-processing task types.
- Subtitle tasks → Merge: includes · Merge is one of the central subtitle transforms.
- Subtitle tasks → Swap: includes · Swap rewrites ASS content for release prep.
- Subtitle tasks → Chapters: includes · Chapter generation feeds packaging metadata.
- Subtitle tasks → ASS parser: uses · Subtitle tasks consume and emit ASS structures.
- ASS parser → Script info: contains · The ASS core models script information.
- ASS parser → Styles & events: contains · The ASS core models styles and events.
- ASS parser → Extra ASS data: contains · The ASS core preserves extra sections and project garbage.
- Subtitle tasks → Mux engine: feeds · Processed subtitle outputs are consumed by muxing.
- Font validator → Mux engine: guards · Font validation is a pre-mux check for the final package.
- Mux engine → mkvmerge bridge: depends on · Muxing is backed by mkvmerge and MKV metadata helpers.
- Mux engine → Transfers: produces · Muxed artifacts are handed off to release and transfer integrations.
- Transfers → Samples & docs: documented by · The docs mirror the public task and utility surface.
- Template project → build.gradle.kts: starter for · The template project shows how consumers set up a build.
- Samples & docs → SubKt plugin: describes · Documentation reflects the plugin and DSL entry points.