[[PageOutline(2, Navigation)]] = Read First for Developers = Hello and welcome! Maybe you've decided to develop a web-based or standalone application/script using opensubtitles.org. If so, that's great news! Due to the increasing number of developers who've been asking the same questions, we decided to make a small FAQ for this area. Please read all topics carefully. == How to request a new user agent == According to the [wiki:XMLRPC API documentation], you need a !UserAgent string, if you will not fill valid !UserAgent, you will get error. ONLY for testing and developing purposes you can use special user agent "!TemporaryUserAgent". Never use this UA as default/public/in production code, we periodically change this and your APP will stop work! Also don't abuse usage of this test user agent. IF you need to download bulk sets of subtitles, User Agent will not help you. There is [https://www.opensubtitles.org/en/support#vip limitation] per day for downloads per IP/User. For registering your own user agent follow these instructions: Please first register as an user on www.opensubtitles.org, if you will ask for UA as not registered, your mail will be ignored. You can choose your own useragent name (there is not guarantee you will have it, because somebody could register same name of UA before you), and please choose version number as required. An example of a valid !UserAgent (you pass it there with version!) in XML-RPC would be something like: '''My Application v0.1''' (please avoid using a weird version numbering, such as v2r1, because we're parsing version using regexp). IMPORTANT: If you are developing wrapper/module/script, which will use OTHER DEVELOPERS, never put there your !UserAgent there as default. It is important, every application/program/script will have own UA. Please fill the following form and email it to: admin at opensubtitles.org with the subject "Register User Agent Request". You will then get a confirmation mail, we are adding UAs manually yet, so it can take couple of days, if you think it is taking too long, contact us again. {{{ Required info ============= Your name: your real name Your registered OS username: your username on opensubtitles.org Contact mail: your mail Title of useragent: your name of useragent Version of useragent: for example: v1 Programming language: C++/Java/PHP/Python... Approximate users of program: how many approx. users are using your program? Opensource: yes/no Upload feature: yes/no/maybe in future Optional info ============= Application URL: where is possible find homepage of application Developer URL: developers homepage }}} If you provide an application URL, and subtitles are uploaded through your application in future, your application URL will appear on the details page for those subtitles. If you also provide a Developer URL, a link will point to your homepage instead of your 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 Subdownloader 1.2.4 developed by capiscuas }}} Please also send an email when your application goes public, or to let us know if you want to test it with us first. == Implementing opensubtitles.org support == Everybody knows that using an API creates few or no real visits to the site, which means no advertising revenue to cover server costs, nor publicity for us. In order to help us keep the site going, please follow these simple steps to help us promote the site and build our brand: * In the "about" menu in your application, add an opensubtitles.org logo or icon, with a clickable link to http://www.opensubtitles.org. You could also write something like "Subtitles service powered by www.!OpenSubtitles.org". Here are some logos for you to use: ([http://static.opensubtitles.org/favicon.ico Favicon], [http://eduo.info/soleol-support/OpenSubtitlesFavIcon.gif Favicon (GIF)], [http://static.opensubtitles.org/gfx/logo.gif Logo], [http://static.opensubtitles.org/gfx/logo-transparent.png Logo (transparent)]) * In the application's "subtitles" menu/context menu, write something like "Download subtitles from !OpenSubtitles.org" * If your application doesn't support automatic uploading (see later - more uploaded subs with your application's link means more subs available, and more happy users!), please add a manual Upload option, pointing the user to: http://www.opensubtitles.org/upload * Put a search link pointing to opensubtitles.org, using the following syntax: http://www.opensubtitles.org/search/sublanguageid-all/moviebytesize-$moviesize/moviehash-$moviehash * Please put an http://www.opensubtitles.org link on your application webpage. * Write about opensubtitles.org support at your webpage, in the readme.txt and in the user guide, if applicable. * Disable automatic search feature without user action, '''call opensubtitles.org API methods per user request only''' * There is download limit per IP, so if you wish to download subtitles on your server, contact us for more information, otherwise you might hitting download limit. * When implementing, it is preferred that user can insert his opensubtitles.org USERNAME and PASSWORD - for higher limits for downloading, there might be also problems if he access using proxy, TOR and so on. * When you put link on webpage, dont use rel="nofollow" tag. Hey, API is for free, so at least we got some backlink from you. Please use HTML for linking back to us. * There is script which is checking for link to opensubtitles.org in your Application URL or Developer URL, if none back-link present you will get warning and maybe later disabling your UA, so please link to us, it is important. * If you are registering User Agent to raise download limits from opensubtitles - it is wrong and it will not work. Download Limits are per User IP and User ID, it doesn't have nothing common with UA. == Supporting Automatic Subtitle Uploading == The idea's very simple - if a user watching a movie with subtitles, already saw 80% or more of the movie (without modifying the delay or framerate subtitles, or fast forward the movie, he really must watch it), we can safely say that those subtitles are suitable for the movie. In that case, why don't you upload them? In many cases this should be done in automated way, in the background (as the default setting). In your player preferences, user should of course be able to change login/password, enable/disable automatic upload, as well as changing any other settings. * Workflow: * After 80% of '''watching''' movie (this means user can skip back and forth, but must watch at least 80% of the movie in real-time), launch the automatic uploader module in player, * !LogIn() * [wiki:XMLRPC#TryUploadSubtitles TryUploadSubtitles()] * If subtitles are not in the database, we need IMDB ID: * use [wiki:XMLRPC#CheckMovieHash CheckMovieHash()] * and/or get IMDB ID from .nfo file. Make sure, you scan all the .nfo files in directory, if directory name is {{{ /^CD\d+$/ }}} (CD1,CD2) search in parent directory, use this regex {{{ /imdb\.\w{2,3}\/title\/tt(\d+)/ }}} (http://www.imdb.com/title/tt1735898/ http://www.imdb.it/title/tt1735898/) - match all, and then make sure, there is only ONE match after UNIQUE OF IMDB IDs. If you find more matches, it means, there is more .nfo in directory (for example users put in one directory whole TV-Series, or more movies with nfos), and result will be wrong. * If we don't have IMDB ID, user should be prompted to 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 }}} 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 [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. Here are some source codes for reading RAR (store compression) files: [wiki:RarSourceCodes Rar Source Codes] == Movie identification == see [wiki:MovieIdentification Movie Identification] == How to get and dump our data == For website developers who wants print our data on their page, we got several [http://www.opensubtitles.org/en/downloads#exports dumps]. If you need parse our website data, use [wiki:PageInXML XML output].