The Kaleido SubKt Project template

Clone this repo and copy all the files over when making a new fansubbing project.

This template is designed to streamline the process of creating and maintaining subtitles for Kaleido-subs projects.

Dependencies

• SubKt
• mkvmerge
• JDK SE 14, 15, or 16

Important

Ensure all tools are properly added to your system's PATH:

• Windows: Edit System Environment Variables → Path → Add the installation directories
• Unix: Add export PATH="$PATH:/path/to/tool" to your ~/.bashrc or ~/.zshrc

Caution

Currently, only JDK 14, and 15 appear to work out-of-the-box with SubKt, but support has been added to this template for 16 too. Please ensure Gradle uses the correct version if you run into any issues.

Directory Structure

project-root/
├── build.gradle.kts                      # SubKt Gradle build script
├── sub.properties                        # Project configuration
├── common/                               # Shared resources
│   ├── warning.ass                       # Optional player warning
│   └── fonts/                            # Common fonts
├── 01/                                   # Episode directory
│   ├── NewShow - 01 - (Premux) [ABCDEF01].mkv
│   ├── NewShow - 01 - Dialogue.ass
│   ├── NewShow - 01 - TS.ass
│   ├── NewShow - 01 - TS (Author).ass    # Multiple TS allowed
│   ├── NewShow - 01 - INS (OP).ass       # Optional
│   ├── NewShow - 01 - INS (ED).ass       # Optional
│   ├── NewShow - 01 - Extra.ass          # Optional
│   └── fonts/                            # Episode-specific fonts
├── NCED1/                                # NCED1 directory
│   ├── NewShow - NCED1 - Lyrics.ass
│   ├── NewShow - NCED1 - TS.ass          # Optional
│   └── fonts/                            # NCED-specific fonts
├── NCOP1/                                # NCOP1 directory
│   ├── NewShow - NCOP1 - Lyrics.ass
│   ├── NewShow - NCOP1 - TS.ass          # Optional
│   └── fonts/                            # NCOP-specific fonts
└── build/                                # Generated output
    └── ...                               # Episode build artifacts

File Naming Requirements

Episode files

• Video files: ShowName - XX - (Premux) [CRC32].mkv
• Dialogue: ShowName - XX - Dialogue.ass
• Typesetting: ShowName - XX - TS.ass or ShowName - XX - TS (Author).ass
• Insert Songs: ShowName - XX - INS (Song Name).ass
• Extra: ShowName - XX - Extra.ass

Note

• Replace XX with the episode number (zero-padded)
• CRC32 in the premux file is optional but recommended
• Author tags in TS files should match contributor names

NCOP/NCED files

• ShowName - XX.ass

Note

• Replace XX with the OP/ED number
• It accepts any number of NCOP/NCED files, and they will all be merged together before being synced.

Example of NCOP1 with a lyrics file and a TS file:

• NCOP1/NewShow - NCOP1 - Lyrics.ass
• NCOP1/NewShow - NCOP1 - TS.ass

The following is also valid:

• NCOP1/NewShow - NCOP1.ass
• NCOP1/NewShow - NCOP1 - TS.ass

Only one file may have opsync or edsync in the effect field. It's highly recommended to set it in the lyrics file.

Getting Started

1. Project Setup

1. Use the Template Repository:

   Click the following button in the top-right of the project-template GitHub repo.

   

2. Set up project files:

   The project file should be updated on a per-project basis. This may also include the types of expected files, as well as metadata.

   For a fairly regular project, set up the following files:

   • Set up the sub.properties file.
     • Set the name of your group and the show.
     • Set the format of the video and audio.
     • Set the number of episodes, as well as any specials.
     • Set the episode ranges for the OP and EDs. If no episodes are set, expect it in every episode. If an episode has no OP or ED set, it will not be muxed.
   • (Optional) Place any common subtitle files or other resources in the common/ directory.
   • Add your dialogue and chapters to the episode's dialogue subtitle file.
   • Add your typesetting to the episode's TS subtitle file.
   • (Optional) Set up INS and Extra subtitle files.
   • Collect all the fonts and put them in the episode/fonts/ directory (i.e. 01/fonts/).

3. Build project:

   Use the Gradle wrapper to build the project:

   # Unix
   ./gradlew chapters.01    # Generate chapters
   ./gradlew merge.01      # Merge subtitle files
   ./gradlew cleanmerge.01 # Clean merged subtitles
   ./gradlew mux.01        # Create final MKV
   
   # Windows
   gradlew.bat chapters.01
   gradlew.bat merge.01
   gradlew.bat cleanmerge.01
   gradlew.bat mux.01

Troubleshooting

1. Merge Failures:

   • Check for syntax errors in ASS files
   • Verify font names match between files
   • Ensure no UTF-16 BOM in subtitle files

2. Mux Errors:

   • Verify mkvmerge is in PATH
   • Check premux file exists and is readable
   • Ensure all referenced fonts exist

Scripts & Hooks

This template comes with multiple scripts and hooks.

no-common-fonts

A pre-commit hook that checks if any pushed fonts match any fonts in common/fonts. This is to prevent users from pushing duplicate fonts and potentially overriding dialogue fonts with different versions of the font.

blank_dialogue

Replaces the given .ass subtitle file with:

• Custom metadata and two predefined styles (Default, Alt)
• A set of fixed chapter marker and comment events
• All Dialogue lines retained structurally but emptied of text

The original file is overwritten in-place. This is used to blank out for example official scripts while preserving their timing to use as a base for original translations.

project_setup

A simple shell script that updates the local git config to filter commits using scripts/clean_project_garbage.sh. This will filter out Aegisub project garbage metadata so users won't keep overriding that with their own premux locations and other local metadata. As such, it's highly recommended that everyone on the team runs this script.

releasepost

A simple Python script to generate our common release post template. It will ask for nyaa and neko urls, and create a /release command for Nino and tweet for X or BlueSky, including hashtags which must be manually set before running the script. Currently, the following urls are required, although you can modify it after as necessary.

Setting local.properties

The local.properties file is not included in this repository. If you want to use custom local settings, you should create this file in the project root directory. This allows you to override specific properties locally without the risk of accidentally committing them to the repository.

This is read after the sub.properties file, and overrides any properties set in that file.

Example pointing premux directory to a network drive

# local.properties file in project root directory.
premux=Z:/share/private/Premuxes/show_title/premux/*${tvdb}* (premux)*.mkv
{SP*}.premux=Z:/share/private/Premuxes/show_title/premux/Specials/*${tvdb}* (premux)*.mkv
ncpremux=Z:/share/private/Premuxes/show_title/premux/Extras/*${episode}* (premux)*.mkv

mini.*.premux=Z:/share/private/Premuxes/show_title/premux (AV1)/*${tvdb}* (Mini Premux)*.mkv
mini.{SP*}.premux=Z:/share/private/Premuxes/show_title/premux (AV1)/Specials/*${tvdb}* (Mini Premux)*.mkv
mini.*.ncpremux=Z:/share/private/Premuxes/show_title/premux (AV1)/Extras/*${episode}* (Mini Premux)*.mkv

Setting sekrit.properties

The sekrit.properties file is not included in this repository. This properties file is used to store your Nyaa username and password, as well as other sensitive information. By default, this file will be read from a directory above the project root directory.

This is read after the sub.properties and local.properties files, and overrides any properties set in those files.

Example setting Nyaa username and password

# sekrit.properties file in the directory above the project root directory.
nyaauser=YourUsername
nyaapass=YourPassword

Contributing

Spot an issue in the build scripts? Have any suggestions? Contributions are welcome!
Please fork the repository and create a pull request with your changes, or create an issue.

For further support, please contact either LightArrowsEXE or petzku on the Kaleido discord server.