# myaamori/subkt architecture

> Architecture diagram of the GitHub repository myaamori/subkt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/myaamori/subkt
- Repository: https://github.com/myaamori/subkt

## Overview

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: [`src/main/kotlin/myaa/subkt/tasks/asstasks.kt`](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt) (Subtitle tasks), [`src/main/kotlin/myaa/subkt/ass/parser.kt`](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt) (ASS parser), [`src/main/kotlin/myaa/subkt/tasks/muxtask.kt`](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/muxtask.kt) (Mux engine), [`src/main/kotlin/myaa/subkt/tasks/plugin.kt`](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/plugin.kt) (SubKt plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Consumer build"]
  node_n1["build.gradle.kts<br/>consumer build<br/>[build.gradle.kts]"]
end

subgraph group_g2["DSL core"]
  node_n2["SubKt plugin<br/>gradle plugin<br/>[plugin.kt]"]
  node_n3["Task runtime<br/>task orchestration<br/>[tasks.kt]"]
  node_n4["Subs DSL<br/>build config<br/>[asstasks.kt]"]
  node_n5(("Property access<br/>lazy values<br/>[tasks.kt]"))
  node_n6(("Template eval<br/>velocity templating<br/>[tasks.kt]"))
  node_n7["Item routing<br/>episode/batch graph<br/>[tasks.kt]"]
end

subgraph group_g3["Subtitle model"]
  node_n8[("ASS parser<br/>subtitle core<br/>[parser.kt]")]
  node_n9["Script info<br/>ass section<br/>[parser.kt]"]
  node_n10["Styles & events<br/>ass sections<br/>[parser.kt]"]
  node_n11["Extra ASS data<br/>ass metadata<br/>[parser.kt]"]
end

subgraph group_g4["Processing tasks"]
  node_n12["Subtitle tasks<br/>ass transforms<br/>[asstasks.kt]"]
  node_n13["Merge<br/>[asstasks.kt]"]
  node_n14["Swap<br/>[asstasks.kt]"]
  node_n15["Chapters<br/>chapter task<br/>[asstasks.kt]"]
end

subgraph group_g5["Packaging/export"]
  node_n16[("Mux engine<br/>mkv packaging<br/>[muxtask.kt]")]
  node_n17["mkvmerge bridge<br/>external tool bridge<br/>[mkvmerge.kt]"]
  node_n18["Font validator<br/>pre-mux validation<br/>[fontvalidator.kt]"]
  node_n19["Transfers<br/>upload/publish<br/>[discordtask.kt]"]
end

subgraph group_g6["Supporting artifacts"]
  node_n20["Template project<br/>consumer starter<br/>[build.gradle.kts]"]
  node_n21["Samples & docs<br/>reference material<br/>[tasks.kt]"]
end

node_n1 -->|"applies"| node_n2
node_n2 -->|"exposes"| node_n4
node_n4 -->|"reads"| node_n5
node_n4 -->|"renders"| node_n6
node_n4 -->|"registers"| node_n7
node_n7 -->|"creates"| node_n3
node_n3 -->|"hosts"| node_n12
node_n12 -->|"includes"| node_n13
node_n12 -->|"includes"| node_n14
node_n12 -->|"includes"| node_n15
node_n12 -->|"uses"| node_n8
node_n8 -->|"contains"| node_n9
node_n8 -->|"contains"| node_n10
node_n8 -->|"contains"| node_n11
node_n12 -->|"feeds"| node_n16
node_n18 -->|"guards"| node_n16
node_n16 -->|"depends on"| node_n17
node_n16 -->|"produces"| node_n19
node_n19 -.->|"documented by"| node_n21
node_n20 -.->|"starter for"| node_n1
node_n21 -.->|"describes"| node_n2

click node_n1 "https://github.com/myaamori/subkt/blob/master/build.gradle.kts"
click node_n2 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/plugin.kt"
click node_n3 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt"
click node_n4 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt"
click node_n5 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt"
click node_n6 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt"
click node_n7 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt"
click node_n8 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt"
click node_n9 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt"
click node_n10 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt"
click node_n11 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt"
click node_n12 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt"
click node_n13 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt"
click node_n14 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt"
click node_n15 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt"
click node_n16 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/muxtask.kt"
click node_n17 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/utils/mkvmerge.kt"
click node_n18 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/utils/fontvalidator.kt"
click node_n19 "https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/discordtask.kt"
click node_n20 "https://github.com/myaamori/subkt/blob/master/template/build.gradle.kts"
click node_n21 "https://github.com/myaamori/subkt/blob/master/src/samples/kotlin/tasks.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1 toneBlue
class node_n2,node_n3,node_n4,node_n5,node_n6,node_n7 toneAmber
class node_n8,node_n9,node_n10,node_n11 toneMint
class node_n12,node_n13,node_n14,node_n15 toneRose
class node_n16,node_n17,node_n18,node_n19 toneIndigo
class node_n20,node_n21 toneTeal
```

## Components

### Consumer build

Where SubKt is configured and invoked by downstream projects.

- [build.gradle.kts](https://github.com/myaamori/subkt/blob/master/build.gradle.kts): consumer build · Host build script that applies and configures SubKt. · `build.gradle.kts`

### DSL core

Plugin entry points, property access, and task-group orchestration.

- [SubKt plugin](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/plugin.kt): gradle plugin · Entry point that exposes the `subs { ... }` DSL and wires task registration. · `src/main/kotlin/myaa/subkt/tasks/plugin.kt`
- [Task runtime](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt): task orchestration · Shared task and task-group infrastructure for episode/batch item creation. · `src/main/kotlin/myaa/subkt/tasks/tasks.kt`
- [Subs DSL](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt): build config · Configuration surface for properties, template evaluation, task groups, and release context. · `src/main/kotlin/myaa/subkt/tasks/asstasks.kt`
- [Property access](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt): lazy values · External properties and Gradle Provider/Property access bridged into the DSL. · `src/main/kotlin/myaa/subkt/tasks/tasks.kt`
- [Template eval](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt): velocity templating · Deferred string and file-content rendering for per-entry and per-batch values. · `src/main/kotlin/myaa/subkt/tasks/tasks.kt`
- [Item routing](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/tasks.kt): episode/batch graph · 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](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt): subtitle core · Reads and writes ASS files with section-aware parsing and serialization. · `src/main/kotlin/myaa/subkt/ass/parser.kt`
- [Script info](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt): ass section · ASS script metadata such as title, timing, wrap style, and resolution. · `src/main/kotlin/myaa/subkt/ass/parser.kt`
- [Styles & events](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt): ass sections · Style and dialogue/event line models with typed accessors and serializers. · `src/main/kotlin/myaa/subkt/ass/parser.kt`
- [Extra ASS data](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/ass/parser.kt): ass metadata · 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](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt): ass transforms · Merge, swap, chapters, automation, and related subtitle-prep operations. · `src/main/kotlin/myaa/subkt/tasks/asstasks.kt`
- [Merge](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt): ass merge · Combines ASS sources and resolves style/script-info conflicts and timestamp handling. · `src/main/kotlin/myaa/subkt/tasks/asstasks.kt`
- [Swap](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt): ass swap · Rewrites dialogue/style mappings through delimiter- and marker-based substitution. · `src/main/kotlin/myaa/subkt/tasks/asstasks.kt`
- [Chapters](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/asstasks.kt): chapter task · 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](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/muxtask.kt): mkv packaging · Assembles video, audio, subtitles, chapters, and attachments into MKV/WebM outputs. · `src/main/kotlin/myaa/subkt/tasks/muxtask.kt`
- [mkvmerge bridge](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/utils/mkvmerge.kt): external tool bridge · Helper layer around mkvmerge and MKV inspection data models. · `src/main/kotlin/myaa/subkt/tasks/utils/mkvmerge.kt`
- [Font validator](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/utils/fontvalidator.kt): pre-mux validation · Checks fonts and glyph coverage before muxing or release. · `src/main/kotlin/myaa/subkt/tasks/utils/fontvalidator.kt`
- [Transfers](https://github.com/myaamori/subkt/blob/master/src/main/kotlin/myaa/subkt/tasks/discordtask.kt): upload/publish · 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](https://github.com/myaamori/subkt/blob/master/template/build.gradle.kts): consumer starter · Starter build layout for downstream users configuring SubKt. · `template/build.gradle.kts`
- [Samples & docs](https://github.com/myaamori/subkt/blob/master/src/samples/kotlin/tasks.kt): reference material · Example usage and generated API documentation for the public surface. · `src/samples/kotlin/tasks.kt`

## Connections

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