Do you have Movies or TV shows in your media player for which the audio and/or subtitle tracks are labeled as "undefined" or "unknown"?
ULDAS (Undefined Language Detector for Audio and Subtitles) solves that problem by:

1. Scanning your video and subtitle files for undefined tracks
2. Extracting audio and subtitle samples
3. Using AI speech recognition to detect the audio language
4. Detecting subtitle language (can also detect if subtitles are [FORCED] and/or [SDH])
5. Updating the file metadata with the correct language codes and flags

ULDAS supports MKV and MP4/m4v, and optionally remuxes unsupported video formats to MKV first.

Uses faster-whisper, langdetect, FFmpeg, MKVToolNix and Tesseract-OCR.

---

📑 Table of Contents

• 🛠️ Installation
  • Step 1: Install Docker
  • Step 2: Create docker-compose file
  • Step 3: Update volumes, IDs, port and CRON Schedule
  • Step 4: Create config
  • Step 5: Configure your settings
  • Step 6: Run ULDAS
  • Unraid
  • NVIDIA GPU
• ⚙️ Configuration
  • Expert variables
  • Model Size Guide
• 🌐 WebUI
• 🔔 Webhook on Remux
• 📄 Supported File Formats
• ⌨️ CLI Reference
  • Utility Commands
  • Logging & Output
  • Paths & General
  • Voice Activity Detection (VAD)
  • Device & Compute
  • Confidence & Reprocessing
  • Tracking
  • Subtitle Processing
  • Timeouts
  • Forced Subtitle Thresholds
  • CLI ↔ Config File Mapping
• 🏞️ Example screenshots
  • WebUI
  • Audio Processing
  • Subtitle Processing
• ⚠️ Need Help or have Feedback?
• ❤️ Support the Project

---

🛠️ Installation

Step 1: Install Docker

1. Download Docker Desktop from docker.com
2. Install and start Docker Desktop on your computer
3. Verify installation: Open a terminal/command prompt and type docker --version - you should see a version number

Step 2: Create Docker Compose File

1. Create a new folder for ULDAS on your computer (e.g., C:\ULDAS or /home/user/ULDAS)
2. Download the docker-compose.yml and place it in that folder, or manually create it by copy pasting this content:

version: "3.8"
services:
  uldas:
    container_name: uldas
    image: netplexflix/uldas:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York # Set your timezone
      - CRON_SCHEDULE=0 5 * * 5
      # Examples:
      #   "0 3 * * *"    = every day at 3:00 AM
      #   "0 */6 * * *"  = every 6 hours
      #   "0 5 * * 5"    = every Friday at 5:00 AM
      # Alternative: use a simple hours interval instead of cron:
      # - SCHEDULE_HOURS=24
      # To run once and exit instead of on a schedule, add `command: --once`
      # and set `restart: "no"` (with `unless-stopped` Docker restarts the
      # container, and the run, after every exit). Removing the scheduler env
      # vars is not enough once a schedule has been saved to config.yml.
      #
      # NOTE: CRON_SCHEDULE / SCHEDULE_HOURS are only used as initial defaults
      # on first launch. Once saved to config.yml they can be edited live from
      # the webUI Settings page (Scheduler section) without a container restart.
    ports:
      - "2119:2119"
    volumes:
      - ./config:/app/config
      - /path/to/folder1:/folder1
      - /path/to/folder2:/folder2
      # Optional: mount custom temp directory:
      # - /path/to/temp:/tmp/uldas
    # Optional: NVIDIA GPU acceleration. Requires the NVIDIA Container Toolkit
    # to be installed on the host first (Unraid: the "Nvidia-Driver" plugin):
    # https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
    # Without this ULDAS runs on CPU. Intel/AMD GPUs are not supported.
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]
    restart: unless-stopped  # use "no" together with `command: --once` for a single run

[!NOTE] GPU support: ULDAS uses an NVIDIA GPU automatically when one is made available to the container; otherwise it runs on CPU. See NVIDIA GPU below.

Step 3: Update volumes, IDs, port and CRON Schedule

• Volume Mounts:

Mount	Description
/app/config	Config file and tracking data (required)
/folder1	e.g. Your movies library
/folder2	e.g. Your TV shows library
/tmp/uldas	optional mount for custom tmp directory

[!NOTE] Your config.yml paths need to match the paths inside your container
example:

    volumes:
      - ./config:/app/config
      - /media/movies:/folder1
      - /media/tv:/folder2

Extra paths can be added as long as they are also listed in the config.

[!IMPORTANT] The format is: your-actual-path:container-path

• Set the timezone (TZ) e.g. Europe/Brussels, America/New_York, Asia/Tokyo,...
• Update the CRON Schedule Tip: Crontab.Guru
  • CRON_SCHEDULE (and SCHEDULE_HOURS) are only consulted on first start. After that, edit the schedule live from the webUI Settings page → Scheduler section (between General and Advanced). You can switch between a simple hours interval and a CRON expression without restarting the container.
  • By default ULDAS does not run immediately when the container starts — it waits for the next scheduled time (or a manual Run Now from the dashboard), so you have a chance to review your settings in the webUI first. If you prefer ULDAS to start processing as soon as the container is up, enable Run on Startup in the webUI Settings → Scheduler section (or set run_on_startup: true in config.yml).
• Update port to xxxx:2119 if you want to run the webUI on a different port than 2119.

Step 4: Create a config

1. Create a subfolder named config
2. Download config/config.example.yml and save it as config.yml in your config folder

Step 5: Configure Your Settings

• See ⚙️ Configuration

Step 6: Run ULDAS

1. Open a terminal/command prompt in your ULDAS folder
2. Type this command and press Enter:

   docker-compose up -d
   

3. That's it! The latest docker container will be pulled from Dockerhub.
4. Update

   docker-compose pull
   

---

Unraid

ULDAS is available in Community Applications. Search for "ULDAS" or install manually using the template in unraid/.

---

NVIDIA GPU

ULDAS runs Whisper through CTranslate2, which supports CPU and NVIDIA CUDA only. Intel and AMD GPUs are not supported. With the default device: auto, ULDAS uses an NVIDIA GPU when one is available inside the container and otherwise runs on CPU; slower, but fully functional.

Making the GPU available is a host-side setting. The NVIDIA container runtime injects the GPU driver into the container. Enable it as follows:

Platform	What to do
Docker Compose (Linux)	Install the NVIDIA Container Toolkit, then uncomment the deploy: block in the compose example above
Docker Desktop (Windows)	Use the WSL 2 backend (Settings → General); the toolkit is bundled. Then uncomment the deploy: block
docker run	Add --gpus all
Unraid	Install the Nvidia-Driver plugin, then add --runtime=nvidia to the container's Extra Parameters

Hosts whose Docker daemon has "default-runtime": "nvidia" configured need nothing extra.

Environment variables. These two are read by the NVIDIA runtime. Both are already set in the image, so you normally don't need to touch them:

Variable	Default	Meaning
NVIDIA_VISIBLE_DEVICES	all	Which GPU(s) to expose: all, an index (0), or a UUID from nvidia-smi -L. Useful on multi-GPU hosts
NVIDIA_DRIVER_CAPABILITIES	compute,utility	Driver features to inject. compute is required for Whisper; utility provides nvidia-smi inside the container. Leave as is

Verifying. With show_details: true, the start of a run logs Initializing faster-whisper: device=cuda, compute=float16, …. docker exec uldas nvidia-smi should list your GPU. If you see device=cpu on an NVIDIA host, the runtime is not active; recheck the table above.

---

⚙️ Configuration

Rename config.example.yml to config.yml and change the values where needed:

• path: Main Paths for your media.
• ignore_tags: List of substrings. Any file whose name contains one of these (case-insensitive, matched against the name without extension) is skipped. Useful for trailers, samples, featurettes. Example: [-trailer, sample]
• ignore_tags_match_dirs: true also skips any directory (and everything inside it) whose name contains one of the ignore_tags. The scan directories themselves are never matched. Default false.
• remux_to_mkv: true remuxes non-MKV files so they can be processed too (MP4/M4V files are excluded from remuxing when mp4_support is on)
• mp4_support: true labels .mp4/.m4v files in place, without remuxing them to MKV. Default false. See Supported File Formats for the MP4 limitations.
• show_details: true will show you more details of what's happening
• dry_run: true will do a dry run (will show what it would do, without actually altering any files)
• run_on_startup: false (default) — ULDAS will not run immediately when the container starts, giving you time to review settings in the webUI first. Set to true to run straight away on container start; subsequent runs then follow the configured schedule in either case.
• process_subtitles: true will process undefined subtitle tracks
• process_external_subtitles: true will process external subtitle files
• analyze_forced_subtitles: true will analyze whether a subtitle track has "Forced Subtitles" or not
• detect_sdh_subtitles: true will analyze whether a subtitle track has 'hearing impaired' support. (e.g.: [Dogs barking], [Narrator:],... )

Expert variables

Only Change these if you know what you're doing.

• vad_filter: Enables Voice Activity Detection to filter out silence and background noise before language analysis (Default: True)
• vad_min_speech_duration_ms: Minimum speech segment length (in milliseconds) to consider as valid speech (Default: 250)
• vad_max_speech_duration_s: Maximum continuous speech segment length (in seconds) before splitting (Default: 30)
• whisper_model: See Model Size Guide below
• device: Hardware acceleration preference (auto, cpu, or cuda). Auto-detects CUDA GPU if available, falls back to CPU (Default: "auto")
• compute_type: Precision/performance trade-off (auto, int8, float16, float32). Auto-selects optimal type based on device (Default: "auto")
• cpu_threads: Number of CPU threads Whisper uses on CPU. 0 = all cores ULDAS is allowed to use (75% of the system's cores) (Default: 0)
• confidence_threshold: Minimum Whisper language probability (0.0-1.0) for a single audio sample to be accepted immediately. Below it, the evidence of several samples spread over the runtime is pooled, and if that is still not convincing the entire audio track is analyzed. Tracks with no confident result are left as und and flagged Inconclusive. Higher values are more conservative but reduce false positives. (Default: 0.9)
• subtitle_confidence_threshold: If subtitle detection confidence falls below confidence, the track is skipped. Skipped tracks are not retried until the file changes (use Reprocess Specific Files to retry after changing the threshold)
• reprocess_all : true will reprocess ALL audio tracks, even if they already have a language tag. (Default: false)
• reprocess_all_subtitles: true will reprocess ALL subtitle tracks, even if they already have a language tag. (Default: false)
• operation_timeout_seconds: 600, # 10 minutes
• temp_dir: Change temporary directory for audio/subtitle extraction. Leave empty to use system default (/tmp)

Forced subtitle detection thresholds.
Density-based:

• forced_subtitle_low_density_threshold: Below = likely forced
• forced_subtitle_high_density_threshold: Above = likely full

Coverage-based (secondary factor):

• forced_subtitle_low_coverage_threshold: Below = likely forced
• forced_subtitle_high_coverage_threshold: Above = likely full

Absolute count thresholds:

• forced_subtitle_min_count_threshold: Below = likely forced
• forced_subtitle_max_count_threshold: Above = likely full

Model Size Guide

• tiny: Fastest, least accurate
• base: Good balance
• small: More accurate, slower (used during development tests)
• medium: Very accurate, much slower
• large: Most accurate, very slow

---

🌐 WebUI

You can access the webui via localhost:2119 Here you can edit settings and check your log. Screenshots

Maintenance Actions (Settings → Advanced):

• Reprocess audio tracks tagged as a specific language: re-runs detection on every track with that tag (e.g. zxx or a suspicious nl).
• Reprocess specific files: search the processed files by (partial) name, add as many as you like, and re-run detection on just those files. Every audio track is re-detected whatever its current tag, plus every embedded subtitle track when Process Subtitles is on. Dry Run is honored.
• Change audio language tag: rewrites every audio track tagged X to Y across your libraries, without running detection. Use it when you know the right answer, e.g. zxx → en in an all-English library. Files are modified in place; Dry Run is honored.
• Index languages: read-only pass that records every track's language tag; feeds the dropdowns above and the Dashboard chart.
• Prune missing files: drops tracker entries for libraries you removed.

---

🔔 Webhook on Remux

ULDAS can send an HTTP request after each remux. (e.g. for triggering Autoscan/Autopulse/..) Enable it in the WebUI under Settings → Advanced → Webhook, or in config.yml.

Variable	Value
{path} / {path_enc}	Full path of the remuxed .mkv (raw / URL-encoded)
{dir} / {dir_enc}	Parent folder of the file
{filename}	File name with extension
{name_noext}	File name without extension
{old_path} / {old_path_enc}	Original pre-remux file path

Use the _enc variants whenever the value goes into a URL query string or a form body, since media paths contain spaces and special characters.

Extra options

Key	Description
webhook_headers	Extra request headers, one Key: Value per line (e.g. an API token)
webhook_timeout_seconds	Request timeout (default 10). The call is fire-and-forget — it never blocks or fails a run
webhook_path_from / webhook_path_to	Optional path remap, for when ULDAS's container mounts differ from your media server's. The leading from path is replaced with to before the {path} variables are built

The webhook only fires on an actual remux (the rename event), never on in-place language-tag edits, and is skipped entirely during dry_run.

---

📄 Supported File Formats

Always Processed:

• MKV files: Primary target format

With mp4_support: true

• MP4, M4V: Processed in place. Language tags are written directly into the file's track headers (the MP4 equivalent of what mkvpropedit does for MKV).
• MP4 limitations The MP4 container only has a per-track language field, so compared to MKV:
  • Subtitle tracks get a language tag only. No track name (English [Forced] [SDH]) and no forced flag are written, because MP4 has no standard place for them.
  • Forced-subtitle and SDH analysis (analyze_forced_subtitles, detect_sdh_subtitles) are skipped for MP4 files, since their result cannot be stored.
  • Some MP4s written by older/Apple tools store a legacy Macintosh language code instead of an ISO code. ffprobe reports the most common one (0) as eng, so ULDAS treats such tracks as already labeled unless reprocess_all is used.
  • Files with a compressed movie header (cmov) are not supported and are reported as failed.
• When mp4_support is on, remux_to_mkv no longer remuxes MP4/M4V files; the other formats below still are.

With remux_to_mkv: true

• MP4, AVI, MOV, WMV, FLV, WebM, M4V, M2TS, MTS, TS, VOB (MP4 and M4V only when mp4_support is off)
• Note: Original files are deleted after successful conversion

External subtitle File Formats:

• SRT, ASS, SSA, SUB, VTT, IDX

---

⌨️ CLI Reference

Utility Commands

Flag	Description
--version	Show the current ULDAS version and exit
--config PATH	Path to the configuration file (default: config/config.yml)
--create-config	Create a sample configuration file and exit
--find-mkv	Locate MKVToolNix installation (Windows only)
--clear-tracking	Clear all file processing tracking data and exit
--skip-update-check	Skip checking for updates on startup
--once	Run once and exit, even if a schedule is configured (Docker: command: --once with restart: "no")

Logging & Output

Flag	Description
--verbose, -v	Enable verbose/debug output (sets show_details to true)
--quiet, -q	Suppress most console output (sets show_details to false)
--show-details	Show detailed processing information
--no-show-details	Hide detailed processing information

Paths & General

Flag	Description
--directory DIR [DIR ...]	Override directory/directories to scan. Accepts multiple paths
--remux-to-mkv	Remux non-MKV video files to MKV before processing
--no-remux-to-mkv	Disable remuxing non-MKV files to MKV
--mp4-support	Label MP4/M4V files in place instead of remuxing or skipping them
--no-mp4-support	Disable in-place MP4/M4V labeling
--model {tiny,base,small,medium,large}	Whisper model size to use for audio language detection
--dry-run	Simulate all changes without modifying any files
--temp-dir DIR	Override the temporary directory used for intermediate files

Voice Activity Detection (VAD)

Flag	Description
--vad	Enable VAD filter (default)
--no-vad	Disable VAD filter
--vad-min-speech-duration-ms MS	Minimum speech duration in milliseconds for VAD
--vad-max-speech-duration-s S	Maximum speech duration in seconds for VAD

Device & Compute

Flag	Description
--device {auto,cpu,cuda}	Device for Whisper inference
--compute-type {auto,int8,int8_float16,int16,float16,float32}	Compute type for Whisper inference
--cpu-threads N	Number of CPU threads (0 = auto)

Confidence & Reprocessing

Flag	Description
--confidence-threshold F	Confidence threshold for audio language detection (0.0��1.0)
--reprocess-all	Reprocess all audio tracks, even those already tagged
--reprocess-language CODE	One-shot run that re-detects audio tracks currently tagged CODE (e.g. zxx)
--relabel-language FROM:TO	One-shot run that changes every audio track tagged FROM to TO (e.g. zxx:en) without running detection
--index-languages	One-shot, read-only run that records the language tag of every track in the language index
--force-reprocess	Force reprocessing, ignoring the tracking cache entirely

Tracking

Flag	Description
--tracking	Enable file processing tracking (default)
--no-tracking	Disable file processing tracking

Subtitle Processing

Flag	Description
--process-subtitles	Process embedded subtitle tracks
--no-process-subtitles	Disable processing of embedded subtitle tracks
--process-external-subtitles	Process external subtitle files
--no-process-external-subtitles	Disable processing of external subtitle files
--analyze-forced	Analyze and tag forced subtitles
--no-analyze-forced	Disable forced subtitle analysis
--detect-sdh	Detect and tag SDH (Subtitles for the Deaf and Hard of Hearing)
--no-sdh-detection	Disable SDH subtitle detection
--subtitle-confidence-threshold F	Confidence threshold for subtitle language detection (0.0–1.0)
--reprocess-all-subtitles	Reprocess all subtitle tracks, even those already tagged

Timeouts

Flag	Description
--operation-timeout S	Timeout in seconds for long operations such as full audio track extraction

Forced Subtitle Thresholds

Flag	Description
--forced-sub-low-coverage F	Low coverage threshold (%) — below this, subtitles are likely forced
--forced-sub-high-coverage F	High coverage threshold (%) — above this, subtitles are likely full
--forced-sub-low-density F	Low density threshold (subtitles/min) — below this, likely forced
--forced-sub-high-density F	High density threshold (subtitles/min) — above this, likely full
--forced-sub-min-count N	Minimum subtitle count — below this, likely forced
--forced-sub-max-count N	Maximum subtitle count — above this, likely full

CLI ↔ Config File Mapping

Every CLI option corresponds to a key in the YAML configuration file. CLI arguments always take precedence over config file values. For boolean options with toggle pairs (--flag / --no-flag), the positive flag wins if both are specified.

CLI Flag	Config Key	Default
--directory	path	["."]
--remux-to-mkv	remux_to_mkv	false
--mp4-support	mp4_support	false
--show-details	show_details	true
--model	whisper_model	base
--dry-run	dry_run	false
--temp-dir	temp_dir	""
--vad / --no-vad	vad_filter	true
--vad-min-speech-duration-ms	vad_min_speech_duration_ms	250
--vad-max-speech-duration-s	vad_max_speech_duration_s	30
--device	device	auto
--compute-type	compute_type	auto
--cpu-threads	cpu_threads	0
--confidence-threshold	confidence_threshold	0.9
--reprocess-all	reprocess_all	false
--force-reprocess	force_reprocess	false
--tracking / --no-tracking	use_tracking	true
--process-subtitles	process_subtitles	false
--process-external-subtitles	process_external_subtitles	false
--analyze-forced	analyze_forced_subtitles	false
--detect-sdh / --no-sdh-detection	detect_sdh_subtitles	true
--subtitle-confidence-threshold	subtitle_confidence_threshold	0.85
--reprocess-all-subtitles	reprocess_all_subtitles	false
--operation-timeout	operation_timeout_seconds	600
--forced-sub-low-coverage	forced_subtitle_low_coverage_threshold	25.0
--forced-sub-high-coverage	forced_subtitle_high_coverage_threshold	50.0
--forced-sub-low-density	forced_subtitle_low_density_threshold	3.0
--forced-sub-high-density	forced_subtitle_high_density_threshold	8.0
--forced-sub-min-count	forced_subtitle_min_count_threshold	50
--forced-sub-max-count	forced_subtitle_max_count_threshold	300

---

🏞️ Example screenshots:

Audio Processing

• example run with reprocess_all: true: Samsara is indeed a documentary without spoken dialogue.

Subtitle Processing

---

⚠️ Need Help or have Feedback?

[!NOTE]

Audio Tracks

A warning will be given at the end of a run for any files that were marked as 'zxx' (no linguistic content).
'zxx' is only written when voice activity detection finds practically no speech in the whole track, or when the only "speech" it finds is music or singing (silent movies, old Disney cartoons, etc). Whisper reports such music as Latin, so ULDAS never tags audio as Latin. Tracks that contain speech but no confident language are left as 'und' and flagged Inconclusive in the log, rather than guessed. You may want to manually check these files.

Subtitle Tracks

Tracks with confidence below the subtitle_confidence_threshold are automatically skipped and shown in the summary. For image-based (PGS) subtitles without OCR support, language detection will be skipped.

Failed Files

If a file is marked as failed, it is likely corrupt. Manually remux or replace it. Renaming of external subtitle files can fail if the targetted name is already in use by another file, or if the file is set to read-only.

• Join our Discord

---

❤️ Support the Project

If you find this project useful, starring the repository is appreciated! ⭐
Big thanks to DaLeberkasPepi for extensive testing.