diff --git a/docs/building/build-script/index.md b/docs/building/build-script/index.md new file mode 100644 index 0000000..0dbd238 --- /dev/null +++ b/docs/building/build-script/index.md @@ -0,0 +1,284 @@ +# Build script + +The build script is the script +that reads all the subtitle properties +and uses them to merge subtitle files +and mux them into a single `.mkv` file. + +The build script is located at `./build.gradle.kts`, +and can be called with the `gradlew` wrapper. + +!!! example "Calling the build script" + === ":fontawesome-brands-windows: Windows" + ```sh + gradlew mux.01 + ``` + + === ":fontawesome-brands-linux: Unix" + ```sh + ./gradlew mux.01 + ``` + +This is what a default build script looks like, +with annotations added to explain each line. + +!!! example "Default build script" + ```kotlin + import myaa.subkt.ass.* + import myaa.subkt.tasks.* + import myaa.subkt.tasks.Mux.* + import myaa.subkt.tasks.Nyaa.* + import java.awt.Color + import java.time.* + + plugins { + id("myaa.subkt") + } + + // Retrieve the script's playRes values + fun ASSFile.getPlayRes(): Pair { + return this.scriptInfo.playResX to this.scriptInfo.playResY + } + + fun Provider.getPlayRes(): Pair { + return ASSFile(File(this.get())).getPlayRes() + } + + // Check whether a string contains parts of a ktemplate + fun String.isKaraTemplate(): Boolean { + return this.startsWith("code") || this.startsWith("template") || this.startsWith("mixin") + } + + // Check whether a line is part of a ktemplate + fun EventLine.isKaraTemplate(): Boolean { + return this.effect.isKaraTemplate() + } + + // Check if a line is entirely blank (no text, actor, or effect) + fun EventLine.isBlank(): Boolean { + return this.text.isEmpty() && this.actor.isEmpty() && this.effect.isEmpty() + } + + subs { + readProperties("sub.properties") // Read properties from sub.properties file + episodes(getList("episodes")) // Get list of episodes from properties + + // Merge all the individual script components + merge { + from(get("dialogue")) // Include the main dialogue file + + if (propertyExists("OP")) { + from(get("OP")) { + syncSourceLine("sync") // Specify the sync line in the OP file + syncTargetLine("opsync") // Specify the target sync line in the main file + } + } + + if (propertyExists("ED")) { + from(get("ED")) { + syncSourceLine("sync") // Specify the sync line in the ED file + syncTargetLine("edsync") // Specify the target sync line in the main file + } + } + + fromIfPresent(get("extra"), ignoreMissingFiles = true) // Include extra file if present + fromIfPresent(getList("INS"), ignoreMissingFiles = true) // Include INS files if present + fromIfPresent(getList("TS"), ignoreMissingFiles = true) // Include TS files if present + + fromIfPresent(get("render_warning"), ignoreMissingFiles = true) // Include render warning if present + + includeExtraData(false) // Don't include extra data + includeProjectGarbage(false) // Don't include project garbage + + // Try to set the LayoutRes values from the playRes values of the dialogue file. + // Falls back to 1920x1080 if not found + val (resX, resY) = get("dialogue").getPlayRes() + + scriptInfo { + title = get("group").get() + scaledBorderAndShadow = true + wrapStyle = WrapStyle.NO_WRAP + values["LayoutResX"] = resX ?: 1920 // Set LayoutResX, default to 1920 if not found + values["LayoutResY"] = resY ?: 1080 // Set LayoutResY, default to 1080 if not found + } + } + + // Remove ktemplate and empty lines from the final output + val cleanmerge by task { + from(merge.item()) + // ass { events.lines.removeIf { it.isKaraTemplate() or it.isBlank() } } + ass { events.lines.removeIf { it.isBlank() } } // Remove blank lines + } + + // Generate chapters from dialogue file + chapters { + from(get("chapters")) + chapterMarker("chapter") // Use "chapter" as the chapter marker + } + + // Run swapper script for honorifics and other swaps + swap { + from(cleanmerge.item()) + + styles(Regex("Main|Default|Alt")) // Apply swaps to these styles + } + + // Finally, mux following the conventions listed here: https://thewiki.moe/advanced/muxing/#correct-tagging + mux { + title(get("title")) // Set the title of the muxed file + + // Optionally specify mkvmerge version to use + if (propertyExists("mkvmerge")) { + mkvmerge(get("mkvmerge")) + } + + from(get("premux")) { + tracks { + include(track.type == TrackType.VIDEO || track.type == TrackType.AUDIO) // Include only video and audio tracks + } + + video { + lang("und") // Set video language to undefined + name(get("vtrack")) // Set video track name + default(true) // Set as default video track + } + + audio { + lang("jpn") // Set audio language to Japanese + name(get("atrack")) // Set audio track name + default(true) // Set as default audio track + forced(false) // Not forced + } + + includeChapters(false) // Don't include chapters from premux + attachments { include(false) } // Don't include attachments from premux + } + + from(cleanmerge.item()) { + tracks { + lang("eng") // Set subtitle language to English + name(get("strack_reg")) // Set subtitle track name + default(true) // Set as default subtitle track + forced(false) // Not forced + compression(CompressionType.ZLIB) // Use ZLIB compression + } + } + + from(swap.item()) { + subtitles { + lang("enm") // Set honorific subtitle language to Middle English + name(get("strack_hono")) // Set honorific subtitle track name + default(true) // Set as default subtitle track + forced(false) // Not forced + compression(CompressionType.ZLIB) // Use ZLIB compression + } + } + + chapters(chapters.item()) { lang("eng") } // Include chapters with English language + + // Fonts handling + skipUnusedFonts(true) // Skip attaching unused fonts + + attach(get("common_fonts")) { + includeExtensions("ttf", "otf") // Attach common fonts + } + + attach(get("fonts")) { + includeExtensions("ttf", "otf") // Attach episode-specific fonts + } + + // Get OP/ED fonts if necessary + if (propertyExists("OP")) { + attach(get("opfonts")) { + includeExtensions("ttf", "otf") // Attach OP fonts + } + } + + if (propertyExists("ED")) { + attach(get("edfonts")) { + includeExtensions("ttf", "otf") // Attach ED fonts + } + } + + out(get("muxout")) // Set output file name and path + } + + // ================================================================================================================= + // NCOP/EDs + tasks(getList("ncs")) { + merge { + from(get("ncsubs")) // Include NC subtitle file + + includeExtraData(false) + includeProjectGarbage(false) + + scriptInfo { + title = get("group").get() + originalScript = get("group").get() + scaledBorderAndShadow = true + } + } + + val cleanncmerge by task { + from(merge.item()) + // ass { events.lines.removeIf { it.isKaraTemplate() or it.isBlank() } } + ass { events.lines.removeIf { it.isBlank() } } // Remove blank lines + } + + chapters { + from(cleanncmerge.item()) + chapterMarker("ncchapter") // Use "ncchapter" as the chapter marker for NC + } + + mux { + title(get("title")) // Set the title of the muxed NC file + + from(get("ncpremux")) { + tracks { + include(track.type == TrackType.VIDEO || track.type == TrackType.AUDIO) // Include only video and audio tracks + } + + video { + lang("jpn") // Set video language to Japanese + name(get("vtrack")) // Set video track name + default(true) // Set as default video track + } + audio { + lang("jpn") // Set audio language to Japanese + name(get("atrack")) // Set audio track name + default(true) // Set as default audio track + } + includeChapters(false) // Don't include chapters from NC premux + attachments { include(false) } // Don't include attachments from NC premux + } + + from(cleanncmerge.item()) { + tracks { + lang("eng") // Set subtitle language to English + name(get("strack_reg")) // Set subtitle track name + default(true) // Set as default subtitle track + forced(false) // Not forced + compression(CompressionType.ZLIB) // Use ZLIB compression + } + } + + chapters(chapters.item()) { lang("eng") } // Include chapters with English language + + skipUnusedFonts(true) // Skip attaching unused fonts + + attach(get("ncfonts")) { + includeExtensions("ttf", "otf") // Attach NC-specific fonts + } + + attach(get("common_fonts")) { + includeExtensions("ttf", "otf") // Attach common fonts + } + + out(get("ncmuxout")) // Set output file name and path for NC + } + } + } + ``` + +For more information on individual tasks, +see the [tasks documentation](./tasks.md). diff --git a/docs/building/build-script/tasks.md b/docs/building/build-script/tasks.md new file mode 100644 index 0000000..ba86443 --- /dev/null +++ b/docs/building/build-script/tasks.md @@ -0,0 +1,145 @@ +# Build Script tasks + +!!! warning "Stub" + This page is a [stub][wikipedia-stubs]. + You can help by [expanding it][contributing]. + + ??? question "How can I help?" + You can help by updating this page with examples. + +This is a list of all the tasks +automatically included in our build script. + +## Tasks + +### merge + +=== "Description" + !!! info "" + The `merge` task combines multiple subtitle files into a single ASS file. + It's used to merge the main dialogue file with other components like OP/ED, extras, inserts, and typesetting. + + Key features: + - Includes the main dialogue file + - Optionally includes OP/ED files with sync line matching + - Includes extra files if present + - Sets script info like title, border/shadow scaling, and layout resolution + +=== "Example" + !!! example "" + ```kotlin + // Example code for merge task + ``` + +### cleanmerge + +=== "Description" + !!! info "" + The `cleanmerge` task processes the merged subtitle file to remove unnecessary lines: + - Removes blank lines + - (Optionally) Removes karaoke template lines + +=== "Example" + !!! example "" + ```kotlin + // Example code for cleanmerge task + ``` + +### chapters + +=== "Description" + !!! info "" + Generates chapter markers from the dialogue file: + - Uses "chapter" as the chapter marker + - Creates a chapters file for muxing + +=== "Example" + !!! example "" + ```kotlin + // Example code for chapters task + ``` + +### swap + +=== "Description" + !!! info "" + Applies text swapping for honorifics and other predefined replacements: + - Operates on specified styles (e.g., "Main", "Default", "Alt") + - Creates an alternative subtitle track with swapped text + +=== "Example" + !!! example "" + ```kotlin + // Example code for swap task + ``` + +### mux + +=== "Description" + !!! info "" + The `mux` task combines video, audio, and subtitle files into a single MKV container: + - Sets title and track metadata + - Includes video and audio from the premux + - Adds regular and honorific subtitle tracks + - Attaches fonts and chapters + - Applies compression to subtitle tracks + - Skips unused fonts + - Outputs the final muxed file + +=== "Example" + !!! example "" + ```kotlin + // Example code for mux task + ``` + +## NC Tasks + +For NCOP/NCED (creditless openings/endings): + +### merge +=== "Description" + !!! info "" + - Combines NC-specific subtitle files + +=== "Example" + !!! example "" + ```kotlin + // Example code for NC merge task + ``` + +### cleanncmerge +=== "Description" + !!! info "" + - Removes unnecessary lines from NC subtitles + +=== "Example" + !!! example "" + ```kotlin + // Example code for NC cleanncmerge task + ``` + +### chapters +=== "Description" + !!! info "" + - Generates NC-specific chapters + +=== "Example" + !!! example "" + ```kotlin + // Example code for NC chapters task + ``` + +### mux +=== "Description" + !!! info "" + - Creates a separate muxed file for NC videos with appropriate metadata and attachments + +=== "Example" + !!! example "" + ```kotlin + // Example code for NC mux task + ``` + +[//]: # (stubs) +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls +[wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/building/getting-started.md b/docs/building/getting-started.md new file mode 100644 index 0000000..34dc927 --- /dev/null +++ b/docs/building/getting-started.md @@ -0,0 +1,73 @@ +# Getting Started + +## Prerequisites + +To begin using this template for your subtitling project, +you'll need to ensure you have the necessary dependencies installed. + +- [SubKt](https://github.com/Myaamori/SubKt) for subtitle processing +- [mkvmerge](https://mkvtoolnix.download/downloads.html) for video muxing +- A compatible version of the Java Development Kit (JDK) + +!!! warning "JDK version" + Currently, JDK versions 14, 15, and 16 are supported, + with versions 14 and 15 working out-of-the-box with SubKt. + Later versions _may_ work. + If you encounter any issues, + make sure Gradle is using the correct JDK version. + +## Setting up your project + +Navigate to the [project-template](https://github.com/Kaleido-subs/project-template) GitHub page, +then click the "Use this template" button in the top-right corner of the page +to create a new repository based on this template. + +!["Use this template" button](./img/use-this-template.png) + +Next, configure your project files. +Generally speaking, +you'll only need to configure the following files: + +- `build.gradle.kts` +- `sub.properties` + +For more details on how to configure these files, +see their respective documentation: + +- [build.gradle.kts](./build-script/index.md) +- [sub.properties](./properties/index.md) + +## Building your project subtitles + +You can build your project using the Gradle wrapper. + +!!! example "Calling the Gradle wrapper" + === ":fontawesome-brands-windows: Windows" + ```sh + gradlew.bat mux.01 + ``` + + === ":fontawesome-brands-linux: Unix" + ```sh + ./gradlew mux.01 + ``` + +!!! tip "Using other commands" + You can replace `mux` with other commands like `chapters`, `merge`, `cleanmerge`, or `swap` + depending on your needs. + The output of these commands (except for `mux`) can be found in the `build/` directory. + +The output of the `mux` command is a single `.mkv` file +with the subtitle embedded in it +and any other associated files attached to it. + +By default, +the output directory is `[${group}] ${jp_title} (${codec_info})`. +This directory will contain the final muxed `.mkv` files, +named according to the `muxout` pattern: +`[${group}] ${jp_title} - ${tvdb} - (${codec_info}) [$mux.crc].mkv` + +!!! tip "Changing the output directory" + You can change the output directory and filename pattern + by editing the `muxout` and `title` properties in the `sub.properties` file! + See the [properties documentation](./properties/index.md) for more information. diff --git a/docs/building/img/use-this-template.png b/docs/building/img/use-this-template.png new file mode 100644 index 0000000..204d88c Binary files /dev/null and b/docs/building/img/use-this-template.png differ diff --git a/docs/building/index.md b/docs/building/index.md new file mode 100644 index 0000000..aee1023 --- /dev/null +++ b/docs/building/index.md @@ -0,0 +1,58 @@ +# Building our subtitles + +This document covers a high-level overview of SubKt, +our build script template, +and how to use and modify it depending on the project. + +## What is SubKt? + +SubKt is a build script template for subtitles. +It is designed to be a starting point for any project, +and can be modified to fit the needs of said project. +It also includes in-depth [documentation](https://github.com/TypesettingTools/SubKt/blob/master/docs/subkt/index.md). + +If includes a lot of useful features +for building a subtitle file +using individual components, +allowing subtitlers to work with individual files +without having to worry about touching files +that other subtitlers are working in. + +It also comes with muxing functionality, +adding stuff like font checking, +CRC32 hashing, +batching, +distributing, +and more. + + +## Kaleido project template + +Kaleido uses SubKt to build subtitle files and mux files. + +The [Kaleido project template][project-template] +is a Github repository that can be used as a template +for new projects. +It includes a pre-configured build setup, +as well as a basic project structure. + +!!! warning "Project-dependent settings" + Our template is designed to be a starting point for any new project, + which means you **must** modify the template to fit the needs of your project + every time you start a new one! + +For a quickstart guide, +see the [getting started](./getting-started.md) document. + +For information on how to modify the template, +see the following documents: + +- [Project structure](./structure/index.md) +- [Subtitle Properties](./properties/index.md) +- [Build Script](./build-script/index.md) + +For running the build script, +see the [building your project subtitles](./getting-started.md/#building-your-project-subtitles) section. + +[//]: # (TODO: add links to the other documents) +[project-template]: https://github.com/Kaleido-subs/project-template diff --git a/docs/building/properties/index.md b/docs/building/properties/index.md new file mode 100644 index 0000000..08d3948 --- /dev/null +++ b/docs/building/properties/index.md @@ -0,0 +1,248 @@ +# Subtitle Properties + +!!! warning "Stub" + This page is a [stub][wikipedia-stubs]. + You can help by [expanding it][contributing]. + + ??? question "How can I help?" + You can help by updating this page with examples, + and better splitting up the sections. + +The `sub.properties` file is used to configure the build script. +This file contains various settings that control how the subtitles are processed +and how the final output is generated. + +## Basic Structure + +The `sub.properties` file is structured as an INI-like configuration file, +with key-value pairs separated by an equals sign (`=`). +Comments can be added using the hash symbol (`#`). + +## Key Sections + +### Release Information + +=== "Description" + + !!! info "" + + - Basic Information: Details about the release group, show title, and shorthand names. + - Codec Information: Specifies video format, video codec, and audio codec. + - Track Names: Defines names for individual tracks (video, audio, subtitles). + +=== "Example" + + !!! example "" + + ```ini + # Basic information + group=Kaleido-subs + jp_title=Some random show + shorthand=${jp_title} + shorthand_pmx=${shorthand} + + # Codec information + format=BD 1080p + vcodec=HEVC x265 10-bit + acodec=Opus 2.0 + codec_info=${format} ${vcodec} ${acodec} + + # Track names + vtrack=x265 + atrack=Opus 2.0 @ 192 kb/s + strack_reg=Full Subtitles [${group}] + strack_hono=Honorifics [${group}] + ``` + +### File Configuration + +=== "Description" + + !!! info "" + + - Output Files: Naming conventions for muxed files and creditless versions. + - Episode Configuration: Specifies episode range and chapter generation settings. + - Script Components: File paths for subtitle components (dialogue, typesetting, inserts, warnings). + +=== "Example" + + !!! example "" + + ```ini + # Output files + title=[${group}] ${jp_title} - ${tvdb} - (${codec_info}) + muxdir=[${group}] ${jp_title} S${season} (${codec_info}) + muxout=${muxdir}/$title [$mux.crc].mkv + ncmuxout=${muxdir}/Creditless/${muxout} + + # Episode configuration + episodes={01..24} + chapters=${dialogue} + + # Script components + dialogue=${episode}/${shorthand} ${episode} - Dialogue.ass + extra=${episode}/${shorthand} ${episode} - Extra.ass + TS=${episode}/${shorthand} ${episode} - TS*.ass + INS=${episode}/${shorthand} ${episode} - INS*.ass + notes=${episode}/${shorthand} ${episode} - Notes.ass + render_warning=common/warning.ass + ``` + +### Font Settings + +=== "Description" + + !!! info "" + + - Font Directories: Locations of episode-specific and common fonts. + +=== "Example" + + !!! example "" + + ```ini + fonts=${episode}/fonts + common_fonts=common/fonts + ``` + +### OP/ED Settings + +=== "Description" + + !!! info "" + + - OP/ED Configuration: Configures opening and ending credit sequences, including episode usage and font locations. + - Creditless Videos: Settings for NCOPs/NCEDs (creditless openings and endings). + +=== "Example" + + !!! example "" + + ```ini + OP1=${OP1}/${shorthand} - OP1.ass + ED1=${ED1}/${shorthand} - ED1.ass + + NCOP1=${OP1}/${shorthand} - NCOP1 (Premux).mkv + NCED1=${ED1}/${shorthand} - NCED1 (Premux).mkv + ``` + +### Episode Metadata + +=== "Description" + + !!! info "" + + - Episode Numbering: Configures numbering scheme to match TVDB, including special episodes and absolute numbers. + +=== "Example" + + !!! example "" + + ```ini + tvdb=S${season}E${episode} + epabs=${episode} + ``` + +## Example Configuration + +Below is an example of a typical `sub.properties` file: + +!!! example "Default subtitle properties file" + + ```ini + # Basic information. + ### TODO: fill this in + group=Kaleido-subs # Name of the release group + jp_title= # Japanese title of the show (to be filled in) + shorthand=${jp_title} # Shorthand name, using the Japanese title + shorthand_pmx=${shorthand} # Shorthand name for premux files + + + # Codec info + format=BD 1080p # Video format (Blu-ray, 1080p resolution) + vcodec=HEVC x265 10-bit # Video codec (HEVC x265 with 10-bit color depth) + acodec=Opus 2.0 # Audio codec (Opus 2.0 channel) + codec_info=${format} ${vcodec} ${acodec} # Combined codec information string + + + # Specific names for individual tracks. Should match codec info. + vtrack=x265 # Video track name + atrack=Opus 2.0 @ 192 kb/s # Audio track name with bitrate + strack_reg=Full Subtitles [${group}] # Regular subtitle track name + strack_hono=Honorifics [${group}] # Honorifics subtitle track name + + + # Show-related (output) files + title=[${group}] ${jp_title} - ${tvdb} - (${codec_info}) # Title format for regular episodes + {SP*}.title=[${group}] ${jp_title} - ${epabs} (${episode}) - ${tvdb} - (${format} ${vcodec} ${acodec}) # Title format for special episodes + premux=${episode}/*(Premux)*.mkv # Path pattern for premux files + + muxdir=[${group}] ${jp_title} (${codec_info}) # Directory name for muxed files + muxout=${muxdir}/$title [$mux.crc].mkv # Output filename for muxed files + ncmuxout=${muxdir}/Creditless/${muxout} # Output filename for creditless (NC) muxed files + + + # Episodes and other basic features. + episodes={01..24}|SP{1..2} # Episode range, including specials + chapters=${dialogue} # Generate chapters from dialogue file + + + # Individual script components + dialogue=${episode}/${shorthand} ${episode} - Dialogue.ass # Path for dialogue subtitle file + extra=${episode}/${shorthand} ${episode} - Extra.ass # Path for extra subtitle file + TS=${episode}/${shorthand} ${episode} - TS*.ass # Path pattern for typesetting files + INS=${episode}/${shorthand} ${episode} - INS*.ass # Path pattern for insert files + render_warning=common/warning.ass # Path for rendering warning file + + + ## Per-episode fonts, e.g. typesetting + fonts=${episode}/fonts # Directory for episode-specific fonts + ## Common fonts, e.g. dialogue and titles + common_fonts=common/fonts # Directory for common fonts used across episodes + + + # OP/ED scripts and episode numbers + ## Common OP/EDs + {02..12}.OP_name=NCOP1 # Opening 1 used in episodes 2-12 + {13..24}.OP_name=NCOP2 # Opening 2 used in episodes 13-24 + {01..12}.ED_name=NCED1 # Ending 1 used in episodes 1-12 + {13..24}.ED_name=NCED2 # Ending 2 used in episodes 13-24 + + OP=${OP_name}/${shorthand} ${OP_name}.ass # Path for opening subtitle file + ED=${ED_name}/${shorthand} ${ED_name}.ass # Path for ending subtitle file + + ## Fonts + opfonts=${OP_name}/fonts # Directory for opening-specific fonts + edfonts=${ED_name}/fonts # Directory for ending-specific fonts + + + # Creditless + ncs=NCOP{1..2}|NCED{1..2} # Creditless opening and ending patterns + + ncsubs=${episode}/${shorthand}_${episode}.ass # Path for creditless subtitle file + ncpremux=${episode}/${shorthand}_${episode} (Premux).mkv # Path for creditless premux file + ncfonts=${episode}/fonts # Directory for creditless-specific fonts + + + ## Episode numbers following TVDB. + ### Moved to the bottom because it's very spammy. + tvdb=S${season}E${epnum} # TVDB episode numbering format + + season=01 # Default season number + epnum=${episode} # Episode number (same as episode variable) + + ### S00 episodes. + {SP*}.season=00 # Set season to 00 for all special episodes + SP1.epnum=01 # Episode number for Special 1 + SP2.epnum=02 # Episode number for Special 2 + SP3.epnum=03 # Episode number for Special 3 + + ### S00 absolute-ish episode number, used for easier user readability. + SP1.epabs=07.5 # Absolute episode number for Special 1 + SP2.epabs=12.5 # Absolute episode number for Special 2 + SP3.epabs=25 # Absolute episode number for Special 3 + ``` + +[//]: # (stubs) +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls +[wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/building/structure/index.md b/docs/building/structure/index.md new file mode 100644 index 0000000..569b4c4 --- /dev/null +++ b/docs/building/structure/index.md @@ -0,0 +1,168 @@ +# Project structure + +By default, +it assumes the following directory structure: + +!!! example "Project Directory" + ```tree + Project Directory # Root directory of the project + ├── 01 # Directory for episode 1 + │ ├── NewShow - S01E01 (Premux) [ABCD1234].mkv # Raw video file for episode 1 + │ ├── NewShow 01 - Dialogue.ass # Main dialogue subtitle file for episode 1 + │ ├── NewShow 01 - OP.ass # Opening song subtitle file for episode 1 + │ ├── NewShow 01 - TS (Actor 1).ass # Typesetting subtitle file for Actor 1 in episode 1 + │ ├── NewShow 01 - TS (Actor 2).ass # Typesetting subtitle file for Actor 2 in episode 1 + │ ├── NewShow 01 - TS (Actor 3).ass # Typesetting subtitle file for Actor 3 in episode 1 + │ └── fonts # Directory for episode-specific fonts + │ └── ... + ├── 02 # Directory for episode 2 + │ ├── NewShow - S01E02 (Premux) [ABCD1234].mkv # Raw video file for episode 2 + │ ├── NewShow 02 - Dialogue.ass # Main dialogue subtitle file for episode 2 + │ ├── NewShow 02 - TS.ass # Typesetting subtitle file for episode 2 + │ └── fonts # Directory for episode-specific fonts + │ └── ... + ├── ED1 # Directory for ending 1 + │ ├── NewShow - ED1 (Premux) [ABCD1234].mkv # Raw video file for ending 1 + │ ├── NewShow - ED1.ass # Subtitle file for ending 1 (includes both lyrics and typesetting) + │ └── fonts # Directory for ending-specific fonts + │ └── ... + ├── OP1 # Directory for opening 1 + │ ├── NewShow - OP1 (Premux) [ABCD1234].mkv # Raw video file for opening 1 + │ ├── NewShow - OP1.ass # Subtitle file for opening 1 (includes both lyrics and typesetting) + │ └── fonts # Directory for opening-specific fonts + │ └── ... + ├── common # Directory for common files + │ ├── fonts # Directory for fonts used across multiple episodes + │ │ ├── LinotypeFinnegan Medium.ttf # Default dialogue font + │ │ └── LinotypeFinnegan MediumItalic.ttf # Default dialogue font + │ └── warning.ass # Subtitle file containing a warning about rendering issues + ├── gradle # Directory for Gradle build tool files + │ └── wrapper # Gradle wrapper directory + │ ├── gradle-wrapper.jar # Gradle wrapper JAR file + │ └── gradle-wrapper.properties # Gradle wrapper properties file + ├── README.md # Project README file + ├── build.gradle.kts # Gradle build script + ├── gradle.properties # Gradle properties file + ├── gradlew # Gradle wrapper script for Unix-like systems + ├── gradlew.bat # Gradle wrapper script for Windows + ├── settings.gradle.kts # Gradle settings file + └── sub.properties # Subtitle properties file + ``` + +??? example "Example of a real project structure" + ```tree + Blue-Archive + |-- 01 + | |-- Blue Archive The Animation - S01E01 (Premux) [A4B6D23B].mkv + | |-- BlueArchive 01 - Dialogue.ass + | |-- BlueArchive 01 - OP.ass + | |-- BlueArchive 01 - TS (Gry).ass + | |-- BlueArchive 01 - TS (Light).ass + | |-- BlueArchive 01 - TS (MSO).ass + | |-- BlueArchive 01 - TS (Period).ass + | |-- BlueArchive 01 - TS (petzku).ass + | `-- fonts + | |-- ... + |-- 02 + | |-- Blue Archive The Animation - S01E02 (Premux) [DCFED1AB].mkv + | |-- BlueArchive 02 - Dialogue.ass + | |-- BlueArchive 02 - TS (Light).ass + | |-- BlueArchive 02 - TS (MSO).ass + | `-- fonts + | |-- ... + |-- 03 + | |-- Blue Archive The Animation - S01E03 (Premux) [38000900].mkv + | |-- BlueArchive 03 - Dialogue.ass + | |-- BlueArchive 03 - TS (Light).ass + | `-- fonts + | |-- ... + |-- 04 + | |-- Blue Archive The Animation - S01E04 (Premux) [3AA19D61].mkv + | |-- BlueArchive 04 - Dialogue.ass + | |-- BlueArchive 04 - Extra.ass + | |-- BlueArchive 04 - TS (Light).ass + | |-- BlueArchive 04 - TS (petzku).ass + | `-- fonts + | |-- ... + |-- 05 + | |-- Blue Archive The Animation - S01E05 (Premux) [83434195].mkv + | |-- BlueArchive 05 - Dialogue.ass + | |-- BlueArchive 05 - TS (Light).ass + | `-- fonts + | |-- ... + |-- 06 + | |-- Blue Archive The Animation - S01E06 (Premux) [4F14C2AE].mkv + | |-- BlueArchive 06 - Dialogue.ass + | |-- BlueArchive 06 - Extra.ass + | |-- BlueArchive 06 - TS (Light).ass + | |-- BlueArchive 06 - TS (petzku).ass + | `-- fonts + | |-- ... + |-- 07 + | |-- Blue Archive The Animation - S01E07 (Premux) [3B0015AF].mkv + | |-- BlueArchive 07 - Dialogue.ass + | |-- BlueArchive 07 - TS (Light).ass + | `-- fonts + | |-- ... + |-- 08 + | |-- Blue Archive The Animation - S01E08 (Premux) [A5674D39].mkv + | |-- BlueArchive 08 - Dialogue.ass + | |-- BlueArchive 08 - TS (Light).ass + | |-- BlueArchive 08 - TS (petzku).ass + | `-- fonts + | |-- ... + |-- 09 + | |-- Blue Archive The Animation - S01E09 (Premux) [C6C9D1E0].mkv + | |-- BlueArchive 09 - Dialogue.ass + | |-- BlueArchive 09 - TS (Light).ass + | |-- Whiteboard.ass + | `-- fonts + | |-- ... + |-- 10 + | |-- Blue Archive The Animation - S01E10 (Premux) [C077087E].mkv + | |-- BlueArchive 10 - Dialogue.ass + | |-- BlueArchive 10 - TS (Light).ass + | `-- fonts + | |-- ... + |-- 11 + | |-- Blue Archive The Animation - S01E11 (Premux) [DC03E7BE].mkv + | |-- BlueArchive 11 - Dialogue.ass + | |-- BlueArchive 11 - TS (Light).ass + | `-- fonts + | |-- ... + |-- 12 + | |-- Blue Archive The Animation - S01E12 (Premux) [1ADD8F6D].mkv + | |-- BlueArchive 12 - Dialogue.ass + | |-- BlueArchive 12 - INS.ass + | |-- BlueArchive 12 - TS (Light).ass + | |-- BlueArchive 12 - TS (petzku).ass + | `-- fonts + | |-- ... + |-- NCED1 + | |-- Blue Archive The Animation - NCED1 (Premux) [8C8AD616].mkv + | |-- BlueArchive NCED1.ass + | `-- fonts + | |-- ... + |-- NCOP1 + | |-- Blue Archive The Animation - NCOP1 (Premux) [BE45148E].mkv + | |-- BlueArchive NCOP1.ass + | `-- fonts + | |-- ... + |-- README.md + |-- build.gradle.kts + |-- common + | |-- fonts + | | |-- LinotypeFinnegan Medium.ttf + | | |-- LinotypeFinnegan MediumItalic.ttf + | | `-- RoGSanSrfStd-UB.otf + | `-- warning.ass + |-- gradle + | `-- wrapper + | |-- gradle-wrapper.jar + | `-- gradle-wrapper.properties + |-- gradle.properties + |-- gradlew + |-- gradlew.bat + |-- settings.gradle.kts + `-- sub.properties + ``` diff --git a/docs/guidelines/editing.md b/docs/guidelines/editing.md index 54998c5..2e09e05 100644 --- a/docs/guidelines/editing.md +++ b/docs/guidelines/editing.md @@ -856,5 +856,5 @@ Rules that don't fit in the other categories. [^gardenpath]: Most of these examples are taken from [this paper](https://pdfs.semanticscholar.org/260d/3b53b1376b5cd30881bbd3ce2472af507adc.pdf). [//]: # (stubs) -[contributing]: https://github.com/Jaded-Encoding-Thaumaturgy/JET-Guide?tab=readme-ov-file#contributing +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls [wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/guidelines/shenanigans.md b/docs/guidelines/shenanigans.md index 79e7547..22c92fb 100644 --- a/docs/guidelines/shenanigans.md +++ b/docs/guidelines/shenanigans.md @@ -1,5 +1,12 @@ # Shenanigans +!!! warning "Stub" + This page is a [stub][wikipedia-stubs]. + You can help by [expanding it][contributing]. + + ??? question "How can I help?" + Whip me into writing this page. + Shenanigans speak to the more "fun" part of fansubbing. They're often meant to be humorous or light-hearted, but can also be used to otherwise enhance the viewer's experience. @@ -34,3 +41,7 @@ Shenganigans that play in the background, giving you more leeway to be creative. - Font changes - Color coding - Easter eggs or hidden messages for attentive viewers + +[//]: # (stubs) +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls +[wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/guidelines/technical.md b/docs/guidelines/technical.md index 7bd3fb9..47c9429 100644 --- a/docs/guidelines/technical.md +++ b/docs/guidelines/technical.md @@ -1,5 +1,12 @@ # Technical Guidelines +!!! warning "Stub" + This page is a [stub][wikipedia-stubs]. + You can help by [expanding it][contributing]. + + ??? question "How can I help?" + Whip me into writing this page. + This section contains technical guidelines for ASS subtitles, mostly involving technical aspects that ensure subtitles display correctly, or otherwise improve accessibility for viewers. @@ -53,3 +60,7 @@ but do also touch upon performance and style override supports. - Release description and notes - Versioning - Hiding old releases + +[//]: # (stubs) +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls +[wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/guidelines/timing.md b/docs/guidelines/timing.md index 0d37a83..6c9fe62 100644 --- a/docs/guidelines/timing.md +++ b/docs/guidelines/timing.md @@ -1,5 +1,12 @@ # Timing Guidelines +!!! warning "Stub" + This page is a [stub][wikipedia-stubs]. + You can help by [expanding it][contributing]. + + ??? question "How can I help?" + Whip me into writing this page. + Timing is possibly the most invisible part of fansubbing. That is, until a line is mistimed and the viewer's immersion is immediately broken. @@ -20,3 +27,7 @@ This document also covers karaoke timing. - Syllable-by-syllable timing techniques - Handling different musical styles and tempos - On-screen lyrics and similar + +[//]: # (stubs) +[contributing]: https://github.com/Kaleido-subs/style-guide/pulls +[wikipedia-stubs]: https://en.wikipedia.org/wiki/Wikipedia:Stubs diff --git a/docs/release/description.md b/docs/release/description.md new file mode 100644 index 0000000..62dde9a --- /dev/null +++ b/docs/release/description.md @@ -0,0 +1,174 @@ +# Release Description Template + +This document outlines the structure and content of a typical anime release description. + +It's designed to provide comprehensive information about the release, +including technical details, staff credits, usage guidelines, and social media links. + +## Cover Art and Basic Information + +The description typically starts with a cover image of the anime, +followed by a table containing basic information about the series: + +- Title: The official title of the anime + - This will typically be the romanized title +- TVDB ID: The identifier for the series on TheTVDB +- AniDB ID: The identifier for the series on AniDB +- Season: The season number and ordering information + - The order is obtained from [TVDB][tvdb] + +!!! example "Basic Information Table" + ``` + | Anime Information | | + | ----------------- | ------------------------------- | + | **Title** | Anime Name | + | **TVDB ID** | [TVDB ID][tvdb] | + | **AniDB ID** | [AniDB ID][anidb] | + | **Season** | Season Number (Watch Order) | + ``` + +## Staff Credits + +Two tables are usually included to credit the staff involved in the release: + +1. Episode Staff + - Lists roles such as Translation, Editing, Encoding, Timing, Typesetting, and Quality Control, + along with the contributors for each role. +2. Song Staff + - Credits for Opening and Ending themes and insert songs, + including Translation, Editing, (Karaoke) Timing, Typesetting, and Song Styling. + +If the song list is too large, +it can be split off into a separate table. + +!!! example "Example" + === "Combined" + ``` + | Episode Staff | | | Song Staff | Opening | Ending | + | --------------------- | ------------------ | --- | --------------------- | -------------- | -------------- | + | **Translation** | Translator A | | **Translation** | Translater I | Translater I | + | **Translation Check** | Checker B | | **Translation Check** | Checker J | Checker J | + | | Checker C | | **Editing** | Editor K | Editor K | + | **Editing** | Editor D | | **Timing** | Timer M | Timer M | + | **Encode** | Editor D | | **Typesetting** | Timer M | Typesetter N | + | **Timing** | Timer E | | | Typesetter O | | + | **Typesetting** | Editor D | | **Song Styling** | Timer M | Timer M | + ``` + === "Split off" + ``` + | Episode Staff | | + | --------------------- | ------------ | + | **Translation** | Translator A | + | **Translation Check** | Checker B | + | **Editing** | Editor C | + | **Encode** | Encoder D | + | **Timing** | Timer E | + | **Typesetting** | Typesetter F | + | **Quality Control** | QC G | + | | QC H | + + | Song Staff | Translation | Editing | (Karaoke) Timing | Song Styling | Typesetting | + | ----------- | ------------ | -------- | ---------------- | ------------ | ------------ | + | OP | Translator I | Editor K | Timer M | Styler Q | Typesetter O | + | ED (S01E01) | Translator J | Editor L | Timer N | Styler R | Typesetter O | + | ED (S01E02) | Translator J | Editor L | Timer N | Styler R | Typesetter O | + | ED (S01E03) | Translator J | Editor K | Timer N | Styler R | Typesetter O | + | ED (S01E04) | Translator J | Editor L | Timer N | Styler R | Typesetter O | + | ED (S01E05) | Translator J | Editor K | Timer N | Styler R | Typesetter O | + ... + ``` + +## Technical Information + +### Video + +Provides details about the video source and specifications: + +- Sources: Origin of the video (e.g., Blu-ray) +- Resolution: Video resolution (e.g., 1920x1080p) +- Codec: Video codec used (e.g., H.265 10-bit) +- Aspect Ratio: The aspect ratio of the video +- Extra: Links to video comparisons and media info + +!!! example "Video Table" + ``` + | | | | + | ---------------- | ------------------------------- | ---------------------- | + | **Sources** | [Blu-ray (company)][source-url] | | + | **Resolution** | 1920x1080p | | + | **Codec** | H.265 (x265) 10-bit | | + | **Aspect Ratio** | 16:9 | | + | **Extra** | [Video Comparison][slowpics] | [MediaInfo][mediainfo] | + ``` + +### Audio + +A table describing the audio track(s): + +- Track language +- Codec +- Channel configuration +- Bitrate +- Source +- Default and forced flags + +!!! example "Audio Table" + === "Mono Audio" + ``` + | Track | Codec | Channels | Bitrate | Source | Default | Forced | + | ------------ | ----- | -------- | -------- | ------------------------------- | ------- | ------ | + | **Japanese** | Opus | 2.0 | 192 kbps | [Blu-ray (company)][source-url] | Yes | No | + ``` + === "Dual Audio" + ``` + | Track | Codec | Channels | Bitrate | Source | Default | Forced | + | ------------ | ----- | -------- | -------- | ------------------------------- | ------- | ------ | + | **Japanese** | Opus | 2.0 | 192 kbps | [Blu-ray (company)][source-url] | Yes | No | + | **English** | AAC | 2.0 | 192 kbps | [Blu-ray (company)][source-url] | Yes | No | + ``` + +### Subtitles + +A table listing available subtitle tracks: + +- Track description +- Language +- Language code +- Format (e.g., ASS, SRT) +- Default and forced status + +!!! example "Subtitle Table" + === "Regular Tracks" + ``` + | Track | Language | Language Code | Format | Default | Forced | + | --------------------------------- | -------- | ------------- | ------ | ------- | ------ | + | **Full Subtitles** | English | eng | ASS | Yes | No | + | **Full Subtitles (Honorifics)** | English | enm | ASS | Yes | No | + ``` + === "Dual Audio" + ``` + | Track | Language | Language Code | Format | Default | Forced | + | --------------------------------- | -------- | ------------- | ------ | ------- | ------ | + | **Full Subtitles** | English | eng | ASS | Yes | No | + | **Full Subtitles (Honorifics)** | English | enm | ASS | Yes | No | + | **Signs & Songs** | English | sng | ASS | No | Yes | + ``` + === "Extra Tracks" + ``` + | Track | Language | Language Code | Format | Default | Forced | + | --------------------------------- | -------- | ------------- | ------ | ------- | ------ | + | **Full Subtitles** | English | eng | ASS | Yes | No | + | **Full Subtitles (Honorifics)** | English | enm | ASS | Yes | No | + | **Full Subtitles (Trivia Notes)** | English | eng | ASS | No | No | + ``` + +## Additional Information + +- Special features of the release (e.g., alternative subtitle tracks) +- Contact information (e.g., Discord server link) +- Social media links (e.g., Twitter) +- Supported media players +- Usage and redistribution guidelines +- Offers for additional resources (e.g., song styling for other groups) + +[tvdb]: https://www.thetvdb.com/ diff --git a/mkdocs.yml b/mkdocs.yml index 9b3490c..25693c5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,18 @@ nav: - Shenanigans: guidelines/shenanigans.md - Song Styling: guidelines/styling/songstyling.md - Technical: guidelines/technical.md + - Building: + - Introduction: building/index.md + - Getting Started: building/getting-started.md + - Project Structure: + - Introduction: building/structure/index.md + - Subtitle Properties: + - Structure: building/properties/index.md + - Build Script: + - Introduction: building/build-script/index.md + - Tasks: building/build-script/tasks.md + - Release: + - Description: release/description.md - Additional Resources: resources.md plugins: