Subgen Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Subgen Setup Guide

Introduction

Subgen creates subtitles with Whisper (speech to text) for videos that have none. It can work on its own, watching your folders or reacting to Plex/Jellyfin events, or as an AI provider for Bazarr Setup Guide.

Is it right for you? Whisper writes out everything said, so it makes full subtitles for a whole movie. It doesn't make "forced" subtitles that only cover foreign-language scenes in an otherwise English film. It's most useful for foreign-language films and shows with no subtitles available anywhere.

Compose

compose/server7/subgen.yaml:

services:
  subgen:
    container_name: subgen.${HOST_NAME}
    image: mccloud/subgen:latest
    environment:
      PUID: ${PUID}
      PGID: ${PGID}
      TZ: ${TZ}
      WHISPER_MODEL: small.en
      WHISPER_THREADS: 4
      TRANSCRIBE_DEVICE: cpu            # or cuda with a GPU
      CONCURRENT_TRANSCRIPTIONS: 1
      WEBHOOKPORT: 9000
      PROCADDEDMEDIA: "True"            # new media from Plex/Jellyfin webhooks
      PROCMEDIAONPLAY: "True"           # media when someone presses play
      ONLY_SKIP_IF_SUBGEN_SUBTITLE: "True"
      MONITOR: "True"
      MODEL_PATH: /subgen/models
      #TRANSCRIBE_FOLDERS: "/tv|/movies"   # batch the backlog once, then turn off
    ports:
      - "${SUBGEN_PORT}:9000"
    volumes:
      - ${DOCKERDIR}/subgen/models:/subgen/models
      - ${MEDIASHARE}/Videos/TV:/tv
      - ${MEDIASHARE}/Videos/Movies:/movies
    restart: always

The media paths inside the container must match what Plex or Bazarr report, or Subgen can't find the files.

Using It with Bazarr

In Bazarr, Settings → Providers → Whisper, endpoint http://subgen.<host>:9000. Bazarr then asks Subgen for a subtitle when no provider has one.

Notes

  • On a CPU, transcribing a full movie takes a long time, even with small.en. Keep CONCURRENT_TRANSCRIPTIONS at 1 and let it work through the queue.
  • .en models only handle English audio. For foreign-language audio use a multilingual model (small, medium) with translation to English.
  • Batch mode (TRANSCRIBE_FOLDERS) processes everything in those folders; turn it off once the backlog is done.
⚠️ **GitHub.com Fallback** ⚠️