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. Hi Polo, unfortunately I found on VLC that LUA support under OSX is not complete: LUA scripts that uses GUIs (like mine) aren’t supported yet! 😐

  2. You can open the .lua script and at the bottom of the file you’ll find the language sets.
    Which language you need? I can add it and publish in GITHub source code! πŸ™‚ let me know!

  3. heya, thanks for a script, such script is the only thing that keeps me from switching from BS player to vlc.

    i am trying to use but cant figure out how.

    i do see it in plugins and extensions menu of vlc, but how to make it work (i.e. start looking for and downloading subs)

  4. Hi K, I’ll try to post some more details about the plugin soon!
    In short:

    1. Open a movie in VLC
    2. Stop the movie
    3. Open the the VLC menu: “View->Subtitles Finder” (this activates the plugin)
    4. Open the the plugin menu: “View->Subtitles Finder->Download”

    That’s it! πŸ™‚

  5. hi thePanz, i just paste the file downloaded from here in the extensions folder in the vcl.app and doesn’t show me the options that you posted to K, there isn’t any view option, so if you have the time i need a little help please. Thank you

  6. I’ve updated this post with new details, please read it πŸ™‚
    Unfortunately I found out that VLC do not support LUA scripts with GUIs on Mac OSx 😐

  7. I get the following error, after trying to download

    VLC can’t recognize the input’s format:
    The format of ‘http://www.opensubtitles.org/en/http://dl.opensubtitles.org/en/download/subad/3861433’ cannot be detected. Have a look at the log for details.

    The file I played was downton.abbey.s01e01.hdtv.xvid-bia.avi

  8. Firstly, many thanks for this. working perfectly on windows
    Tip: adding more source websites such as subscene.com would increase the script’s usability.

  9. Download is broken due to OpenSubtitles changing to zipped archives for all of their files now! Do you have any plans to update the add on with zip support?

  10. BryanC: maybe they changed also some URI addresses, ZIP files were supported from the beginning!

    Dracula (nice nickname πŸ˜‰ ) : Romanian language added! πŸ™‚

  11. Nice script. Apparently there’s an error with the download url though. Like few others said, the link this script tries to download subs from, has an extra β€˜http://www.opensubtitles.org/{selected language}/’ in it.

    For example I get following error
    ‘VLC can’t recognize the input’s format:
    The format of ‘http://www.opensubtitles.org/fi/http://dl.opensubtitles.org/fi/download/subad/4257718′ cannot be detected. Have a look at the log for details’

    Of course the input format cannot be detected ’cause that’s not a vlid url! πŸ™‚ The proper download link would be ‘http://dl.opensubtitles.org/fi/download/subad/4257718’ not ‘http://www.opensubtitles.org/fi/http://dl.opensubtitles.org/fi/download/subad/4257718’.

  12. Actually there seems to be something else going on too… I modified the -lua script on line 645

    fullURL = baseurl .. “/” .. suburl[i]
    fullURL = suburl[i]

    And now I get an error saying
    ‘VLC can’t recognize the input’s format:
    The format of ‘http://dl.opensubtitles.org/fi/download/subad/4257718′ cannot be detected. Have a look at the log for details’ so the url is now ok, but for some reason the script doesn’t seem to understand the zip file.

  13. No worries Panz. I have absolutely no experience in Lua, but I can give it a shot if I find some time.

  14. Avira is now detcting your webinstaller – I sent a false positive report to Avira, but this was their reply:

    26969201 SubtitlesFinder-w…ll.exe 86.51 KB RISK

    Filename Result
    SubtitlesFinder-w…ll.exe RISK

    The file ‘SubtitlesFinder-webinstall.exe’ has been determined to be ‘RISK’. Our analysts named the threat APPL/Vittalia.A. The term APPL/ denotes an application of dubious origin or which might be hazardous to use. In case you would like to use the application anyway you may want to exclude it from scanning. Further information can be found here. Detection is added to our virus definition file (VDF) starting with version .
    Please note that Avira’s proactive heuristic detection module AHeAD detected this threat up front without the latest VDF update as: Clean.

  15. The script is awsome but i don’t have my native language. Could you please add Croatian or put instructions so i can try to add it myself? Thank you in advance. Keep up the good work

  16. @Antonio: added “Croatian” language. Try web-installer to download the latest version.
    If you look at the source code, you’ll find the language list at the bottom, it’s quite easy to understand how it works πŸ˜‰

  17. Wow u are fast πŸ˜€ I tried to edit the script myself but i inputed thw rong tag for my language so it didn’t work. Thank you once again

  18. I get this a lot: Your input can’t be opened:
    VLC is unable to open the MRL ‘zip://http://www.opensubtitles.org/hr/http://dl.opensubtitles.org/hr/download/subad/3973880!/Prevod.sub’. Check the log for details.

    Is that because the files are zipped?

  19. This is great – Caused a couple of crashes, but it’s nothing major. I tested this out on some media, it found the exact version of the media and even downloaded the SRT file into the folder where the media was.

  20. hello,

    thanks for the script;
    can you make a modification for the romanian language: is “rum”, not “rom”.

    I tried to do it myself, but it doesn’t recognize the extension anymore.


  21. The updated script does not seem to work in my case: it hangs at the ‘Download subtitles’ stage. (I’m in Ubuntu Quantal, VLC The original one from here (http://addons.videolan.org/content/show.php?content=141787&forumpage=0) works, but does not keeps subtitles for future use.

    What I want to know is: while the script says ‘Download subtitles’ I imagine they are downloaded temporarily during playback: where are they downloaded? can I manually save/safekeep them?

  22. Also, the script works fine with the Windows version of VLC 2.0.5 running under Wine+Ubuntu, while it does not with VLC 2.0.5 for Ubuntu

  23. Helooo

    I love the plugin !
    But i would really like swedish to be available as well.
    I tried to figure out a way to add it myself, but i failed =(


  24. @Lucian and @Tomas: latest VLC-Subtitles-Finder has been updated with your suggestions. Check last commit-log and use the Web-Installer to fetch the new version.
    Let me know if you find any other issue!

  25. @Cipricus: there is an issue with “file-paths” as slash and backslash are used differently in Windows and Linux. Further research is needed to fix it.

  26. Linux path has extra prefix “/”. I have just checked vlc.net.url_parse and windowPath in VLsub extension, how it handles Linux and Windows paths. Really good solution.

  27. It is also possible to use Lua function os.getenv (“OS”)
    If returned string contains “Win” then we are in Windows, if nil or anything else, then it is Linux.

  28. I submitted a pull request. It needs testing on Windows before you merge it. I can only validate that it works on Linux and “should” work on Windows.

Leave a Reply

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

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