[[PageOutline(2, Navigation)]]

= 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 [wiki:XMLRPC 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:
Contact mail:
Title of useragent:
Version of useragent:

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 [http://www.opensubtitles.org/en/subtitles/3348814/girl-scouts-en 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>
}}}

== 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
   * [wiki:XMLRPC#CheckMovieHash LogIn()]
   * we got movie and subtitles, call [wiki:XMLRPC#TryUploadSubtitles TryUploadSubtitles()]
   * if subtitles are not in database, get IMDB ID from .nfo file or [wiki:XMLRPC#CheckMovieHash CheckMovieHash()]
   * if we don't have IMDB ID, user must find it using [wiki:XMLRPC#SearchMoviesOnIMDB SearchMoviesOnIMDB()]
   * [wiki:XMLRPC#UploadSubtitles 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 [wiki:DevReadFirst#Videofilesextensions 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 [wiki:DevReadFirst#Subtitlefilesextensions 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 [http://en.wikipedia.org/wiki/List_of_file_formats#Video wikipedia] and [http://www.filezed.com/file-types/1/movie-video-multimedia-files.html 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 ([http://en.wikipedia.org/wiki/Standard_(warez) 1], [http://www.scenereleases.info/2006/06/scene-rules.html 2], [http://www.sbytes.info/blog/static.php?page=static051030-153644 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.