wiki:DevReadFirst

Version 11 (modified by guest, 16 years ago) (diff)

--

Navigation

  1. How to request for new user agent
  2. How to implement opensubtitles.org support
  3. Your movie player should support automatic uploading
  4. Getting video information
  5. Video files extensions
  6. Subtitle files extensions
  7. RAR support
  8. Movie identification

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 - please register first on www.opensubtitles.org as user. You can choose own user agent name, please choose your application name and version, so proper UserAgent name should be something like: My Application v0.1 (please don't use some weird version numbering, such as v2r1 and so on, because we are parsing version). Please fill this form and send it to mail: admin at opensubtitles.org 

Required info
=============
Your name:
Your registered OS username:
Contact mail:
Title of useragent:
Version of useragent:
Programming language:
Opensource: yes/no
Upload feature: yes/no/maybe in future


Optional info
=============
Application URL:
Developer URL:

If you provide application URL, and some subtitles will be uploaded by your Application, on subtitle details you will have URL to Application, also if you provide Developer URL, link will point to your homepage instead profile page on opensubtitles. For example, this is html for SubDownloader on subtitle ​details page: 

Uploaded by <a target='_blank' href='http://www.subdownloader.net'>Subdownloader 1.2.4</a> developed by <a href='http://www.ivangarcia.org/blog/'>capiscuas</a>

Also please send mail, when your application comes to public, or you want test it first with us.

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:

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

For rar archive, just replace *.avi with *.rar -> *.rxx (xx is number), rest is same

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.

Movie identification

see MovieIdentification.