bazarrbulksync 0.2.0

Bulk subtitle synchronization for Bazarr

Bazarr Bulk Sync

An optimized command-line tool for bulk syncing media subtitles in Bazarr.

TLDR Sync Everything

You should have a config file in your current working directory. Set base_url and api_key to your Bazarr instance.

Docker

# Sync all subtitles interactively.
docker run --rm -it -v ./bazarrbulksync_config.yml:/app/bazarrbulksync/bazarrbulksync_config.yml wayhowma/bazarrbulksync:0.2.0 sync all

# Sync all subtitles detached.
docker run --rm -d -v ./bazarrbulksync_config.yml:/app/bazarrbulksync/bazarrbulksync_config.yml wayhowma/bazarrbulksync:0.2.0 sync all

Local Python

# Sync all subtitles interactively.
pip install bazarrbulksync==0.2.0
bazarrbulksync sync all --config ./bazarrbulksync_config.yml

More Information

CLI Usage

The CLI was created using Rich. You can view the descriptions of different commands/options by chaining commands with --help.

 Usage: bazarrbulksync sync all [OPTIONS]                                                                                                                                     
                                                                                                                                                                              
 Sync without date/datetime restriction.                                                                                                                                      
                                                                                                                                                                              
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --config               -c                     PATH                  Path to config file.                                                                                   │
│ --series-chunk-size                           INTEGER RANGE [x>=1]  Series fetched per Bazarr list API call.                                                               │
│ --movies-chunk-size                           INTEGER RANGE [x>=1]  Movies fetched per Bazarr list API call.                                                               │
│ --episodes-chunk-size                         INTEGER RANGE [x>=1]  Approximate episodes fetched per API call (approximate because we fetch all the episodes in an entire  │
│                                                                     series at a time).                                                                                     │
│ --series-ids                                  TEXT                  Comma-separated Sonarr series IDs to sync (all episodes from each series given will be synced).        │
│ --movie-ids                                   TEXT                  Comma-separated Radarr movie IDs to sync.                                                              │
│ --episode-ids                                 TEXT                  Comma-separated Sonarr episode IDs to sync.                                                            │
│ --media-type                                  [series|movies|all]   Which type of media to sync. [default: all]                                                            │
│ --language                                    TEXT                  Only sync subtitles with this code2 language.                                                          │
│ --forced                   --no-forced                              Override forced flag.                                                                                  │
│ --hi                       --no-hi                                  Override hearing-impaired flag.                                                                        │
│ --max-offset-seconds                          INTEGER RANGE [x>=1]  Maximum sync offset seconds.                                                                           │
│ --no-fix-framerate         --fix-framerate                          Toggle framerate fixing.                                                                               │
│ --gss                      --no-gss                                 Toggle usage of Golden-Section Search algorithm during syncing.                                        │
│ --reference                                   TEXT                  Sync reference track or subtitle path.                                                                 │
│ --dry-run                                                           Simulate work without calling sync.                                                                    │
│ --yes                  -y                                           Skip confirmation prompts.                                                                             │
│ --log                      --no-log                                 Turn file logging on or off for this run.                                                              │
│ --log-file                                    PATH                  Log file path for this run (implies logging on).                                                       │
│ --log-debug                --no-log-debug                           Verbose file log when a log file is used.                                                              │
│ --help                                                              Show this message and exit.                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Examples

# Get the CLI help page.
docker run --rm -it wayhowma/bazarrbulksync:0.2.0 --help

# Get the sync command help page.
docker run --rm -it wayhowma/bazarrbulksync:0.2.0 sync --help

# Get the sync all command help page.
docker run --rm -it wayhowma/bazarrbulksync:0.2.0 sync all --help

# Get the sync before command help page.
docker run --rm -it wayhowma/bazarrbulksync:0.2.0 sync before --help

Configuration

Bazarr Bulk Sync reads a YAML config—see the sample layout. If you omit --config, it looks for ./bazarrbulksync/bazarrbulksync_config.yml first; if that file does not exist, it uses ./bazarrbulksync_config.yml in the current working directory. With the usual Docker volume layout, the nested path inside the container is /app/bazarrbulksync/bazarrbulksync_config.yml. Use --config to point anywhere else.

The defaults in that file are sensible starting points. The options that most affect sync behaviour are max_offset_seconds, no_fix_framerate, and gss, depending on your media and subtitles.

More Examples

Docker

# Syncs all episodes for the series with IDs 10, 20, and 50, and syncs the movie with an ID of 5.
docker run --rm -it -v ./bazarrbulksync_config.yml:/app/bazarrbulksync/bazarrbulksync_config.yml wayhowma/bazarrbulksync:0.2.0 sync all --series-ids 10,20,50 --movie-ids 5

# Syncs all movies whose latest sync is before 2026-03-01.
docker run --rm -it -v ./bazarrbulksync_config.yml:/app/bazarrbulksync/bazarrbulksync_config.yml wayhowma/bazarrbulksync:0.2.0 sync before 2026-03-01 --media-type movies

# Syncs all subtitles with debug logging to the local ./bazarrbulksync.log file.
# Create an empty host file first so Docker bind-mounts a file, not a directory.
touch ./bazarrbulksync.log
docker run --rm -it -v ./bazarrbulksync_config.yml:/app/bazarrbulksync/bazarrbulksync_config.yml -v ./bazarrbulksync.log:/app/bazarrbulksync/bazarrbulksync.log wayhowma/bazarrbulksync:0.2.0 sync all --log --log-debug

Local Python

# Syncs all episodes for the series with IDs 10, 20, and 50, and syncs the movie with an ID of 5.
bazarrbulksync sync all --config ./bazarrbulksync_config.yml --series-ids 10,20,50 --movie-ids 5

# Syncs all movies whose latest sync is before 2026-03-01.
bazarrbulksync sync before 2026-03-01 --config ./bazarrbulksync_config.yml --media-type movies

# Syncs all subtitles with debug logging to the local ./bazarrbulksync.log file.
bazarrbulksync sync all --config ./bazarrbulksync_config.yml --log-file ./bazarrbulksync.log --log-debug

Contributing

If you find any bugs, or think that another feature would be worth adding, please don't hesitate to open an issue or a pull request.