subtitle searcher | Winfred van Kuijk

subtitle searcher

By • Published: January 6, 2014 • Last updated: November 26, 2014 • Filed in: Software

subtitleSearcher example resultA script that helps to automate searching & adding subtitles for movies and TV shows. It uses subliminal for the actual search+download and MP4Box for the actual adding of the subtitles. The script is there to make all of it easier: it gives you a command line interface (CLI) to add subtitles for all video files in a certain folder, for all video files recursively, or for a specific file.

[Download not found]

See requirements, usage and examples or the source code of the script.


$ subtitleSearcher -f "Elephants.Dream (2006).m4v"
processing: ./Elephants.Dream (2006).m4v
- missing: en:English nl:Dutch
INFO: Listing subtitles for
INFO: Found 2 subtitles total
INFO: Downloading subtitle with score 20
INFO: Downloading subtitle with score 20
INFO: Saving to u'./Elephants.Dream (2006)'
INFO: Saving to u'./Elephants.Dream (2006)'
2 subtitles downloaded
- available on disk: en:English nl:Dutch
- setting comment: "subtitles: EN NL"
- adding subtitles (en:English nl:Dutch) to ./Elephants.Dream (2006).m4v
Timed Text (SRT) import - text track 1024 x 576, font Serif (size 18)
Timed Text (SRT) import - text track 1024 x 576, font Serif (size 18)
Setting up iTunes/iPod file...
Saving ./Elephants.Dream (2006).m4v: 0.500 secs Interleaving

summary of added subtitles:
- ./Elephants.Dream (2006).m4v: en:English nl:Dutch


The subtitle search script depends on:

  • subliminal
    • a Python script to download subtitles from various sources
    • on my Mac I install it with: sudo easy_install subliminal
  • MP4Box
    • a toolbox for (MP4) video files, in our case it is used to add subtitles files and update the iTunes comment
    • on my Mac I install it with homebrew, a super simple package installer. With homebrew installed, you install MP4Box with: brew install mp4box

Note: the subtitleSearcher script is as good as these two tools are. The script depends on subliminal to search/download and depends on MP4Box to add the subtitles. You will still need other tools to automatically add metadata (e.g. iFlicks) or sync the subtitles (e.g. iSubtitle).


Download and unzip the script, save it where you like, e.g. in /usr/local/bin.
If the script does not run, make sure it has execution permissions (chmod +x scriptname).
It was created on a Mac, but should work on most Linux type systems.


subtitleSearcher [-d directory] [-f file] [-r] [-c|s|m] [-b] [-k] [-u] [-h]
-d : what directory to search in (default: current directory)
-f : what video file to process
-r : recursive search (default: only single directory)
-c : check only - will only check what subtitles are missing
-s : subliminal only - will download subtitles, but not add them to the video
-m : mp4box only - will skip subliminal, only add already existing srt subtitle files
-b : create backup of original video file
-k : keep the srt files (default: move the srt files after processing)
-u : update comment only
-h : display this usage summary


Edit the script if you would like to change the following settings:

  1. subliminal location: default is /usr/local/bin/subliminal
  2. MP4Box location: default is /usr/local/bin/mp4box
  3. languages: default en:English nl:Dutch (code is needed for subliminal, name is needed for mp4box)
  4. formats: default mp4, m4v, mkv, avi
  5. srt archive folder: default /var/tmp; after processing the srt files will be moved here


  1. subtitleSearcher
    Search and add subtitles for all video files in the current folder
  2. subtitleSearcher -c
    Check the video files in the current folder, show what subtitles are in the video and already on disk.
  3. subtitleSearcher -u
    Update the comments (if applicable) for the video’s in the current folder, so it lists the subtitles in the video. Example: “subtitles: EN NL”
  4. subtitleSearcher -s -f Just.Do.It.2011.720p.x264-VODO.mkv
    Download the subtitle for the specific video Just Do It. It will only download the srt file, it will not be added to the video.
  5. subtitleSearcher -r -m
    In the current directory and subdirectories add the subtitles that have already been downloaded (with the -s option and/or manually). Afterwards the subtitle files will be archived.
  6. subtitleSearcher -r -k -b
    Recursively search and add subtitles, make a backup of the original video file, after processing keep the subtitle files in the same folder as the video.

source code

One Response to “subtitle searcher”

  1. YIFY Movies says:

    Nice post! Thanks for sharing. You may take a look at our the new YIFY Movies website

Leave a Reply

« | Home | »