https://github.com/rasmus-kirk/submerger
Submerger combines subtitles from two files into one, with customizable position and color settings
https://github.com/rasmus-kirk/submerger
jellyfin language-learning plex rust subtitles subtitles-generator
Last synced: 3 days ago
JSON representation
Submerger combines subtitles from two files into one, with customizable position and color settings
- Host: GitHub
- URL: https://github.com/rasmus-kirk/submerger
- Owner: rasmus-kirk
- License: mit
- Created: 2024-09-20T14:23:27.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-10-26T11:20:00.000Z (6 months ago)
- Last Synced: 2025-04-16T19:16:48.115Z (7 days ago)
- Topics: jellyfin, language-learning, plex, rust, subtitles, subtitles-generator
- Language: Rust
- Homepage: https://crates.io/crates/submerger
- Size: 22.5 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Submerger
**Submerger** is a simple tool designed to merge subtitles from two different
files into a single output file. It's especially useful for language learners
who want to watch content with subtitles in multiple languages simultaneously.
The tool offers two main functionalities: Direct merging of two subtitle
files for quick, one-time use, and a more advanced recursive search feature
that scans entire directories for subtitle files matching specific language
preferences.
## Features
- Merge two subtitle files into one output file.
- Customize subtitle color and position for the second subtitle track.
- Recursively search directories for subtitle files to merge based on
language markers.
- Supports both `.srt` and `.vtt` subtitle formats for inputs, only outputs
`.srt` however.
## Installation
### Cargo
#### Installation
To install using cargo:
```bash
cargo install submerger
```
#### Building
One way to build this project is using [Rust](https://www.rust-lang.org/tools/install).
> **Note:** You must build using [rust nightly](https://rust-lang.github.io/rustup/concepts/toolchains.html)!
Clone the repository:
```bash
git clone https://github.com/rasmus-kirk/submerger.git
cd submerger
```
Build the project:
```bash
cargo build --release
```
### Nix
> **Note:** [Nix flakes](https://nixos.wiki/wiki/flakes) must be enabled!
#### Installation
```bash
nix profile install github:rasmus-kirk/submerger
```
#### Building
This project has a nix flake, so it can be built using nix:
```bash
nix build github:rasmus-kirk/submerger
```
#### Running
If you just wish to run the program using nix:
```bash
nix run github:rasmus-kirk/submerger -- --help
```
#### Developement Shell
To enter a developement shell with the correct rust-toolchain and rust
analyzer using nix:
```bash
nix develop github:rasmus-kirk/submerger
```
If you use a shell other than bash:
```bash
nix develop github:rasmus-kirk/submerger -c $SHELL
```
## Usage
You can either merge two files directly or recursively search a directory
for matching subtitle pairs.
### 1. Merging Two Subtitle Files
Merge two subtitle files into a single output:
```
submerger simple [OPTIONS]
```
Required:
- ``: Path to the first subtitle file
- ``: Path to the first subtitle file
- ``: Output file where the merged subtitles will be saved
Optional:
- `--color ` Sets the color for the second subtitle track
- `--position ` Sets the position of the second subtitle track (default: top-center)
- `--log-level ` Sets the level of logging [default: warn] [possible values: error, warn, info, debug, trace]
- `--help` Print help
#### Example
```bash
submerger simple movie.en.srt movie.ja.srt --out merged.srt --color "#fbf1c7" --position top-center
```
### 2. Recursive Subtitle Merging
Search a directory for subtitle files matching given language codes and merge them:
```
submerger recursive [OPTIONS]
```
Required:
- ``: Language code for the first subtitle file (e.g., `en` for English)
- ``: Language code for the second subtitle file (e.g., `ja` for Japanese)
- ``: Root directory to recursively search for subtitle files
Optional:
- `--out-ext `: The file extension for the output file (e.g. `file.en.srt` -> `file.merged.srt` if set to `merged.srt`) (Default: `srt`)
- `--vtt`: Also match and convert VTT files. Note, this will not output VTT files, only SRT is supported as output (Default: `true`)
- `--color `: Sets the color for the second subtitle track
- `--position `: Sets the position of the second subtitle track (Default: `top-center`)
- `--log-level `: Sets the level of logging (Default: `warn`)
#### How it works
- The program reads both subtitle files and assigns different positions and
colors to the second subtitle track (if configured).
- When merging recursively, the program looks for matching subtitle files
based on the provided language codes (e.g., `en`, `ja`).
- If hearing-impaired subtitles are found (e.g., `en.hi`), they will be
preferred only if normal subtitles (`en`) aren't available.
- The merged subtitle output file will contain both sets of subtitles and
be written as `ORIGINAL_FILE_NAME.OUT_EXTENSION$` in the directory where
the matching subs were found.
#### Example
```bash
submerger recursive en ja ./movies --color "#fbf1c7" --position top-center
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE.txt) file for details.