VLC and OpenSubtitles downloader

I’ve recently found a nice VLC script for adding subtitles to any video using the great OpenSubtitles portal on this VLC Forum post. Such script does exactly what it sais: it crawls the OpenSubtitles website looking for the matching movie (no osdb hash function involved) and adds the subtitle into the VLC media player.

I’ve edited such LUA script (so, I’m not the original author of such script) also allowing the subtitle downloading for an off-line usage, the downloaded file is placed in the same movie folder, renamed as the movie itself with the language suffix. It’s my first attempt into LUA scripting language, it’s quite easy, but I’ve used about 3 hours to find out all the LUA features and the (sometimes not documented) VLC scripting functions.


  • Due to a issse in VLC, all lua plugins that use GUIs (like SubtitlesFinder) aren’t supported under MAC OSx [citation missing]



  • [version 1.3-beta]
  • 2013-04-05: Show plugin version in “Plugin details” dialog
  • 2013-04-05: fixed auto-show of search dialog (by Mederi)
  • 2013-04-05: Fixed typos in Italian language (by Mederi and Ciprus)
  • [version 1.2]
  • 2013-04-03: Fixed Linux subtitle file saving (thanks to AbrahamΒ vanΒ Helpsing)
  • 2013-04-03: Various fixes and improvements (thanks to Mederi)
  • 2013-04-03: Removed standard downloader since WebDownloader retrieves the most updated plugin
  • .. full changelog on SubtitlesFinder commit log

For an alternative of VLC-Subtitles-Finder, try VLCSub (written by Guillaume Le Maout) available at my GIT repository, installer also available in the project download section. VLCSub can’t search by movie title, but implements the Opensubtitles.org HASHing function (sometimes more accurate).


119 thoughts on “VLC and OpenSubtitles downloader

  1. Tried to use, installed fine, showed up under extensions/plugins. That was it, though, tried finding subs for 1953’s Peter Pan (which was on OSD website) but to no avail. Is it possible to include some sort of feedback for the extension so that I know if it is/did do(ing) anything? I love the idea, it’s a crucial concept that should be employed in future releases of VLC and I plan on using it DAILY if I can get it to work. Again, nice concept, any support would be great. Keep up the good work and thanks.

  2. Hi, thank you for your comment! Unfortunately I only code the “save” part, not the “search and use” one! For debug messages look under “Tools -> Messages”, and set the verbose level to 2. The subtitle script provides bunch of messages to track what’s going on πŸ™‚


  3. Looks like it could use a little more polish, but otherwise fantastically done! This feature is the ONLY reason I was still using Media Player Classic! It would be nice if it searched for the hash first (like in MPC), then automatically reverted to the file name if that fails.

    Any chance of this being merged into the official build of VLC?

  4. Unfortunately I don’t own OSX to help you. On VLC forums I found that:

    You can add your own Lua scripts in this directory or in your VLC’s preferences folder “lua/playlist” subdirectory on Windows or Mac OS X and in your local VLC shared data folder on Linux (~/.local/share/vlc/lua/playlist).

  5. Hi , its awesome modification.
    I was making it for another site but the problem is they check HTTP referrer
    is it possible to send custom HTTP referrer while requesting the url?

  6. I’m not a LUA expert, but you can try to figure out how send HTTP-headers on the LUA online documentation.
    Let me know if you get any results, and I’ll provide a link to your modified extension (or update mine here for you).

  7. Well , Lua DOES allow to send HTTP-headers via curl library , but lua vlc doesnt have curl in it πŸ™
    I came around a fix for that by routing the subtitle through my server and it works like a charm ^_^
    I made it to work with addic7ed.com (Tv Subtitle site, This is the site who sync’s the subs for tv shows not steal them)
    But yet another problem is , they allow only 10ish subs per day to be downloaded , so i cant really share the mod since the files are routed through my server , and it stops working after 10 subs.
    But anyways , its working for me thats more than enough xD

  8. Great work Ankit! Maybe you can share your code and your edits (without the link to your server).
    A “hackish” solution to the 10 download limit could be this: your server (or another online resources) allow ONLY to search the subtitle, while the real download process will be executed from the user host.. what do you think?

  9. searching is not the problem , problem is downloading.
    while downloading , the site checks HTTP-referrer so what i did was created a php script that would send HTTP-referrer and output the subtitle.
    Only solution that comes to mind is : user installing apache + php on their comp , converting it into a server and then php script can be executed from client end.
    But I Dont think someone would be willing to do that for TV subtitles πŸ˜›

  10. Ankit: you’re right! requiring an (half) LAMP system for subtitle downloading isn’t a great deal! πŸ™‚ Further ideas that came to my mind:
    1. Ask VLC to include LUA-curl library
    2. Provide and invoke a “private” LUA-curl library with the script

    my 2cents..

  11. Already posted in their forums about that.
    Tried private LUA-curl library , didnt seem to be working.
    May be can use this small nano server
    its just 900 KBs!

    maybe i can make a tutorial of setting everything up , would take a few minutes for user to set it up but would worth it later.

  12. The guys at addic7ed made it perfectly clear that they’ll add more barriers if I release the plugin to public =_=;

  13. Damn, that’s a bad news! 😐 I think that we should give up: if they implements a Catchpa or a similar solution for subtitles download the plugin will be useless! πŸ™
    Anyone have a better solution?

  14. Yea, I dont wanna loose my addic7ed plugin , heh.
    I watch a lot of shows and am DAMN lazy to browse through site :/

  15. The best subtitle-downloader implementation I’ve seen is the one in XBMC. You can configure a dozen of websites and all I can say is it works really well.

  16. AFAIK the XBMC platform is released under GPL license: we could extract that feature and implement a VLC plugin (maybe using QT and not LUA scripting language)?
    That should be a *great* addition to VLC itself.. what do you think?

  17. I am in total love with my edited lua script for addic7ed , i dont need anything else for now πŸ˜€
    idk xbmc , i’ll give it a try.

  18. I am in total love with my edited lua script for addic7ed , i dont need anything else for now πŸ˜€
    idk xbmc , i’ll give it a try…

  19. First thank you for your initiative. I just found the first version, which did not save. And as a result, I resumed my search and found your version πŸ™‚ So … thank you πŸ™‚
    I just tried on linux (debian based distrib). Did not work. Not a big difficulty to solve.
    In subtitles-mod.lua the line 41:
    name = vlc.strings.decode_uri(string.gsub(name, “file:///”, “”))
    Has to be changed to:
    name = vlc.strings.decode_uri(string.gsub(name, “file:///”, “/”))

    else the file wont be saved nor be loaded. With this, it seems to work now πŸ™‚
    If it helps anyone than your welcome.

  20. Hi Tester, I try your edits but I can’t get the plugin working after using string.gsub(name, "file:///","/")
    Can you test it on Linux?

  21. I am very sorry for asking this,but am a total noob at VLC mod…i did put the mod file in extension folder and yes it did appear in the vlc extention box..but nothin else happned…sorry am asking ,was this script suppose to download srt files or searchit or do somethin else?…must be me,but nothing is happnin in my vlc…any help would be deeply appreciated… πŸ™‚ ..coz if this is what i think it is ..its a brilliant idea!!!!..great work…even tho i cudn get it to work…ur hard work is deeply appreciated…tnx πŸ™‚

  22. After the plugin is installed you’ll have a “Open Subtitle donwloader” menu item under “View”.
    Open a movie video and click the menu item once, it will show you four different features.. one of them is “Download”… try searching your favorite language and the subtitle will be opened within the current video. The subtitle source (a file ending in .SRT for exsample) will be saved in the same folder of the video you’re watching..

    That’s it! πŸ™‚

  23. Doesn’t seem to work if the video-file is located on a network-path, like \servervideosmymoviemymovie.mkv πŸ™ If i move the file to C:videos, it works as intended.

  24. Unfortunately I the “save” procedure needs some efforts to make it compatible with network-paths and UNIX paths. I thins the main issue is with “/” and “\” path separator.


  25. Well, I downloaded your lua file. I can see the subtitles link in the “view” menu and it can research the internet for the file (i use little snitch in a Windows XP inside a Parallels). The problem is nothing happens afterwards. I also tried Tester’s tip and it did not work. Do you have a new version?

  26. Ok guys. I really really new here. I downloaded the file. unzip it now what?? where do i put it. or how do I install it?? tried to copy it in C:\Program Files\VideoLAN\VLC\lua\playlist but nothing is happening. please help

  27. Hi RegΓ©rio, please check if the subtitle file is created in your movie folder after the download takes place.
    If it’s not there enable VLC debug console and provide the plugin log to further investigate your issue! πŸ™‚
    Thank you

  28. Hi Dotty, on VLC documentation you can find more details on lua plugins, by the way in my Windows7 system, the lua script is placed in:
    You have to figure out where your user folder is!
    Hope it works! πŸ™‚

  29. OK it works for movies. I was trying with series and it didn’t show. later I was watching a movie and it showed the sub. thx is there a fix for series???

  30. When searching for subtitles for the TV-show name, try to edit the search text with only the tv-show name and episode, it will find more subtitles… unfortunately I didn’t implemented any hashing-function to search on open-subtitles website and only keyword searches are performed..

  31. Fantastic addon! Added a new issue on GitHub suggesting the search by file size… Much more accurate:

    function urlOpenSub(search_term,lang)
    — base = “http://api.opensubtitles.org/xml-rpc”
    — lang = “eng”

    if lang == “all” then
    lang =”en”

    local item = vlc.input.item()
    local path = item:uri()
    vlc.msg.dbg(“File path “..path..””)
    local filename = vlc.strings.decode_uri(string.gsub(path,”file://”,””))
    vlc.msg.dbg(“File path “..filename..””)
    local filesize = vlc.net.stat(filename).size
    vlc.msg.dbg(“Filesize “..filesize..” Kb “)

    base = “http://api.opensubtitles.org/”..lang..”/search/”
    — if(lang) then base = base .. “sublanguageid-” .. lang .. “/”
    search_term = string.gsub(search_term, “%%”, “%%37″)
    search_term = string.gsub(search_term, ” “, “%%20”)

    return base .. “moviebytesize-” .. filesize .. “/simplexml”

  32. Hey!
    I’m using mac OS and have located the lua folder and extensions and then placed the .loa file within it. But I’m not able to locate where in the program I should find it because the the mac OS version doesn’t have a view menu, so where can I find it?


  33. hi guys, I’m not a coder and didn’t understand a bit of what you saying here, so I’m a dumb, can you please help me to install this on mac os x lion? is it possible?

  34. Hello,
    I’m also using mac OSX and I’m having the same issue as Mojitoo, I can’t seem to find the downloader anywhere in VLC.

    I’d be really glad if someone could help me.

  35. Unfortunately I don’t have a mac, I’ll try to ask to my colleagues to install VLC and test the downloader plugin..

Leave a Reply

Your email address will not be published. Required fields are marked *

By submitting this form, you accept the Mollom privacy policy.