subsyncerr

Still in development and testing stage, using the project is currently not recommended.

A containerized automated Bazarr-companion that synchronizes the subtitles downloaded by Bazarr using sc0ty's subsync. Conditions are set in place for a successful sync that are quite strict, for in which case they aren't met, the subtitle will be blacklisted in Bazarr and a new subtitle will be downloaded. This will in turn leave you with close to 100% of your subtitles in sync.

This project could not have come into fruition without these amazing open-source projects, written by awesome people.

Features

• Great results for non-English subtitles, thanks to subsync's ability to sync them to already synced English subtitles, which evidently achieve better results.
• Simple concept, aimed to work as universally as possible, while also keeping the setup process easy to follow.
• Downloaded subtitles are saved as entries in a CSV-file, enabling Bazarr to work independently from subsyncerr.
• Separate CSV-file used for temporarily storing bad subtitles to blacklist while Bazarr-API is unreachable, ensuring that nothing gets swept under the rug.
• Blacklisting of bad unsyncable subtitles, leaving only successfully synced subtitles.
• Prerequisites for file permissions, Bazarr-API access, and other requirements before running main.py to ensure everything functions correctly.
• Logs are saved for both subsync and subcleaner, making troubleshooting easier.
• Although uncommon, subtitles that can not be synchronized by subsync, due to either a bad media file or an unsupported language saved in failed.txt, which is a list for subtitles needing manual adjustment.
• Language verification on subtitles against language code in filename, in which case it detects another language, it will get blacklisted and a new subtitle will be requested. This has in my experience proven to be necessary.
• Subtitle ad-remover built-in, can be optionally enabled.

Disclaimer

• If you want your entire library processed, because of the subtitle metadata required for fundamental functions in the script to work properly you have to redownload all your subtitles. Example of these functions are blacklisting and downloading requests to Bazarr's API.
• Some subtitles will inevitably pass through the strict sync requirements, which means that some out-of-sync subtitles processed will still be recognized as successful. This is sadly a limitation with subsync. However rare, from what I've observed, most these out-of-sync subtitles are on TV-shows, more specifically parts before intros, on recaps, or in outros.

Installation

1. Pull the container from the following Docker-repository: tarzoq/subsyncerr
2. Create a new folder/share, allocate the folder to both Bazarr and the container using /subsyncerr as the container path.
3. Allocate the same media paths used by Bazarr to the container.
4. Add the following Environment Variables along with their corresponding values: API_KEY & BAZARR_URL
   • Additionally you can choose to enable subcleaner (KBlixt), by setting the environment variable value "SUBCLEANER" to "True". (Supported languages are: English, Spanish, Portuguese, Dutch, Indonesian and Swedish)
5. CPU-pinning for the container is highly recommended, subsync uses all it can get. (I for example have it set to one isolated core)
6. Check the container's Docker-log, if all prerequisite checks are passed, main.py will commence.
7. The container will now have added all necessary files, including the addtosynclist-script to your newly created folder. Last step, simply add this as a post exectution script in Bazarr:

   bash /subsyncerr/addtosynclist.bash '{{episode}}' '{{subtitles}}' '{{subtitles_language_code2}}' '{{subtitles_language_code3}}' '{{episode_language_code3}}' '{{subtitle_id}}' '{{provider}}' '{{series_id}}' '{{episode_id}}'
   

• One more thing, make sure Bazarr is using two-letter language codes in the filename (this is on by default). Hearing-impaired subtitles with hi, cc or sdh in the filename will work fine. But if forced is added, it won't work, but those most likely won't work well with subsync either way.

Docker-Compose

version: "3.8"
services:
  subsyncerr:
    image: tarzoq/subsyncerr:latest
    container_name: subsyncerr
    volumes:
      - /folder/path:/subsyncerr
      - /media/path:/container/path
    environment:
        API_KEY: None
        BAZARR_URL: http://localhost:6767
        SUBCLEANER: True # Optional, False by default
        TZ: Europe/Berlin
    cpuset: "5"
    restart: unless-stopped

Environment Variables

| Variable | Required | Description | Default value | | --- | --- | --- | --- | | API_KEY | Yes | API key for Bazarr, required to blacklist and request new subtitles in case subtitles fail to synchronize. | None | | BAZARR_URL | Yes | IP address/hostname and port for Bazarr. | http:localhost:6767 | | SUBCLEANER | No | True or False for if you want to enable subcleaner when processing subtitles. | False | | SLEEP | No | Time interval for how often to check unsynced.csv for new entries when it is empty. | 300 (seconds) | | WINDOW_SIZE | No | Maximum window of time for subsync to spend synchronizing subtitles, lower this if you think subtitles take too long to finish (wouldn't recommend for most people). | 1800 (seconds) |

Usage

Subsyncerr aims to be as self-reliant as possible. It's merely a companion, so subtitles are all still controlled as per usual through Bazarr. The only thing you need to be aware about is this projects approach to save subsync's "unprocessable" subtitles from being blacklisted, which is to add them to a list called failed.txt.

What To Do With Subtitles In failed.txt

Whenever a subtitle gets added to failed.txt, it's because the error outputted by subsync depicts that it couldn't process the media file properly. Based on my testing, if you look further down the page here, you can find the different triggers I have implemented.

How should I proceed? To put it simply, either get another media file, which can in many cases fare better, or, sync it manually.

My approach is as follows:

1. Double-check to see if the subtitles are correct.
   • In cases where the English subtitle is in sync, thus not requiring manual synchronization, the non-English subtitles can be easily re-downloaded in Bazarr, which will make them synchronize to the "in sync" English subtitle.
2. If you're out of luck, both the English subtitle is out-of-sync, and you can't get your hands on another media file, your only option left is unfortunately to sync it manually.

• Once done, remove it from failed.txt.

If you're curious, this project will always attempt to sync the English subtitle first, in which case it gets added to failed.txt, all the non-English subtitles will first, if enabled, be processed by subcleaner, and then they also get added to failed.txt.

Audio languages supported

Subsync's only supported audio track languages are Chinese, Dutch, English, French, German, Italian, Russian and Spanish. Media files in any other language will most likely result in the subtitles being added to failed.txt.

Limitations

In some cases, the minimum point requirement is not enough to stop out-of-sync subtitles from getting through. Basically they still get high points above the threshold, just a good subtitle would. This is something caused directly by subsync, which I have no ability to fix in the script.

But in my experience it's most usually only out-of-sync in the beginning before an intro in a TV Show, or one small segment of the subtitle.

How It Works

When processing a non-English subtitle, it will first look in unsynced.csv for an English counterpart. If that is found, that is processed first. If it doesn't exist in unsynced.csv but does as a file, it will assume it has already been processed and sync to that subtitle file. If neither of those are true, it will sync the non-English subtitle directly to the audio, just like an English subtitle.

The reason for this is my testing, I arrived at the conclusion that syncing the non-English subtitle directly to the audio yields much worse results than my approach. For this very reason the script will redownload all non-English subtitles when a new English subtitle has been processed, to make sure everything stays consistent. An example of this would be if Bazarr upgrades to a better English subtitle on a new movie.

Flowchart

The process depicted in this flowchart is simplified to demonstrate the fundamentals required to understand how everything works together.

Files

| File | Description | | --- | --- | | addtosynclist.bash| Script used by Bazarr to add downloaded subtitles to unsynced.csv. | | failed.txt | List of subtitles which couldn't be processed by subsync. | | main.py | Main script which processes subtitles found in unsynced.csv. | | retry.csv | List of subtitles that are waiting be blacklisted while Bazarr-API is unreachable (located in the logs directory). | | start.py | Script which checks all prerequisites, and if met will launch main.py. | | unsynced.csv | List of subtitles-entries which are yet to be processed. |

Folder structure

/subsyncerr
├── addtosynclist.bash
├── failed.txt
├── unsynced.csv
└── /logs
    ├── retry.csv
    ├── /subcleaner # Only exists if enabled
    └── /subsync

Operating System