Read First for Developers

Hello and welcome. Maybe you decided developing web-based or standalone application/script which use opensubtitles.org - that's great. According more and more developers who asks same questions we decided make small FAQ for this area, please read all topics.

How to request for new user agent

According to API documentation you need UserAgent string. You can choose own, we are not restrict (for now) to this, please choose your application name and version, so proper UserAgent name should be something like: MyApplication v0.1 and please mail us, you are using this UserAgent

How to implement opensubtitles.org support

We are not again too much restrict in this area. Everybody knows using just API makes no or minimum real visits to website, where are some banners and stuff, which can make some money at least to donate servers costs, so just follow these simple steps - it is only about promoting our website and making OS brand:

• in about menu in application add opensubtitles.org logo/favicon with clickable www.OpenSubtitles.org link/logo to ​http://www.opensubtitles.org and write something like "Subtitles service allowed by www.OpenSubtitles.org"
• in subtitles menu/context menu write something like "Download from OpenSubtitles.org"
• if your application doesn't (but in future should be - more uploaded subtitles using program - more subtitles available - more users happy...) support upload please add Upload menu pointing browser to: ​http://www.opensubtitles.org/upload
• please put link search on opensubtitles.org - which will open browser to: ​http://www.opensubtitles.org/search/sublanguageid-all/moviebytesize-$moviesize/moviehash-$moviehash
• please put ​http://www.opensubtitles.org link on your application webpage
• write about opensubtitles.org support at webpage, readme.txt and user guide

Your movie player should support automatic uploading

Idea is very simple. User is watching some movie with subtitles. If he watched more than 80% of movie with subtitles (and he did not change delay/fps for subtitles) we can say, those subtitles are suitable for watched movie. So why don't upload them? In many cases it should be done in automated way in background (default setting). In player preferences of course user should change login/password, automatic upload enabled/disabled and all other settings.

• workflow:
  • after 80% of watching movie (that means user can forward, backward movie, but he must watch at least 80% of current time of movie) launch automatic uploader module in player
  • LogIn()
  • we got movie and subtitles, call TryUploadSubtitles()
  • if subtitles are not in database, get IMDB ID from .nfo file or CheckMovieHash()
  • if we don't have IMDB ID, user must find it using SearchMoviesOnIMDB()
  • UploadSubtitles()

Getting video information

Users don't like to fill fields and clicking too much when working with program, so here you can find information how to pre-fill some fields and hints about your program behavior.

Finding more CDs In file explorer show to user video files. Let's say he will pick up one video file and movie is distributed in more than 1 file (2CD...), so we want to detect 2nd CD. Subtitles should be easy to detect, just search in same directory subtitles with same name as movie and different extension. Here are the most common directory structures for movies:

1CD release with subtitles, most left directory is scene release name

Restraint.2008.DVDSCR.XviD-PreVail\prv-rstrnt.dvdscr.xvid.avi
Restraint.2008.DVDSCR.XviD-PreVail\prv-rstrnt.dvdscr.xvid.sub
Restraint.2008.DVDSCR.XviD-PreVail\prv-rstrnt.dvdscr.xvid.nfo

2CD release with subtitles in same directory

Atonement.DVDRip.XviD-SVD\svd-tnmnt.nfo
Atonement.DVDRip.XviD-SVD\svd-tnmnta.avi
Atonement.DVDRip.XviD-SVD\svd-tnmnta.sub
Atonement.DVDRip.XviD-SVD\svd-tnmntb.avi
Atonement.DVDRip.XviD-SVD\svd-tnmntb.sub

2CD release with subtitles in more directories

Atonement.DVDRip.XviD-SVD\svd-tnmnt.nfo
Atonement.DVDRip.XviD-SVD\CD1\svd-tnmnta.avi
Atonement.DVDRip.XviD-SVD\CD1\svd-tnmnta.sub
Atonement.DVDRip.XviD-SVD\CD2\svd-tnmntb.avi
Atonement.DVDRip.XviD-SVD\CD2\svd-tnmntb.sub

Video files extensions

opensubtitles.org site/api does not restrict any extension for video files, nor movie filesize is not problem (movie file must be bigger than 128 kb:). If you want list of common videofiles here it is according ​wikipedia and ​filezed:

• *.3g2, , *.3gp, *.3gp2, *.3gpp, *.60d, *.ajp, *.asf, *.asx, *.avchd, *.avi, *.bik, *.bix, *.box, *.cam, *.dat, *.divx, *.dmf, *.dv, *.dvr-ms, *.evo, *.flc, *.fli, *.flic, *.flv, *.flx, *.gvi, *.gvp, *.h264, *.m1v, *.m2p, *.m2ts, *.m2v, *.m4e, *.m4v, *.mjp, *.mjpeg, *.mjpg, *.mkv, *.moov, *.mov, *.movhd, *.movie, *.movx, *.mp4, *.mpe, *.mpeg, *.mpg, *.mpv, *.mpv2, *.mxf, *.nsv, *.nut, *.ogg, *.ogm, *.omf, *.ps, *.qt, *.ram, *.rm, *.rmvb, *.swf, *.ts, *.vfw, *.vid, *.video, *.viv, *.vivo, *.vob, *.vro, *.wm, *.wmv, *.wmx, *.wrap, *.wvx, *.wx, *.x264, *.xvid

Subtitle files extensions

opensubtitles.org is supporting these subtitle formats: *.srt, *.sub, *.smi, *.txt, *.ssa, *.ass, *.mpl - please don't upload UTF 16/32 files, if you need some support for other formats - contact us and send example of subtitle file. We will not support scene subtitles IDX/RAR.

RAR support

Most of movies are released on warez scene first and according their rulez (​1, ​2, ​3) they package video to RAR archives using STORE compression (that means no compression at all is used). So movie is just divided into some parts and header/footer (?) is added to .rar files - if you need some example, just compress your movie with rar using store compression and set one archive to 15.000.000 bytes. It should be really nice, if players are supporting this. So, if your player is supporting this, add downloading/uploading subtitles for movies, which are stored in RAR archive, please. Also if you have some source codes for RAR support, please share them with us, so other developers can use them.