Skip to content
Find, Rename and match subtitle for TV series files
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE.txt update readme Jun 4, 2019

CircleCI Maintainability Gem Version

This Gem only works for video files with S[Number]E[Number] (i.e., S01E02) format in their names.


You have a TV series without subtitles. Open the terminal, go to the folder where you saved your files, and run subfinder. It will find the similar subtitle files (only .srt) on the folder and rename it to video file. If the subtitles are not exists on your disk, then it will download, from the subscene URL you provided, extract and rename them.

It works fine with the video file names which followed S01E01 naming format.


First you need to have Ruby and Gem on your machine.

Then simply run:

$ gem install subfinder

Without any switches, this will unzip all zipped or compressed files and find/rename them to correspondent video file. Also you can provide the URL for list page with -u and it would download the correct file and do the rest.


$ subfinder -u -l fa

  • Use -l or --languagefor subtitle language you want. Default is English. Right now only fa and en are supported.

  • Use -u or --url to specify a URL page of a TV series on website.

  • Also see sunfinder -h for help


  • Please report any broken thing using Github issues *

To run tests, run rake test.

To see all logs, run with -d or --degub

Clone the project. Make changes and then rake build inside the project folder to create Gem.

Then gem install pkg/subfinder-0.0.1.gem to install it locally.

Create a temp folder and run movies_list_creator.rb inside that folder. It will create fake files.


The gem is available as open source under the terms of the MIT License.


  • get sub title language

  • extract all files

  • list all files

  • match srt for each video file

  • rename all matches

  • move all other files to extract folder

  • if not available then find it online test

  • if not available then find it online code

  • if language sub is not available then find English

  • download match subtitle

  • check for internet connectivity or issue for accessing blocked websites

  • add all language codes

  • move all other files from sub folders to main folder when extracting

  • add messages for timeout on web browsing

  • save user entered config for later use

  • Writing article about it (VCR)

You can’t perform that action at this time.