                       ---------------------------------
                        OSCAR - OSDb client application
                       ---------------------------------
                           
                           
 Introduction
--------------
  This is a simple application allowing quick download/retrieval of subtitle
  files (in text format) for your video files.


 What is it?
-------------
  OSDb - Open Subtitles DataBase
  
  OSDb is a protocol first introduced on the OpenSubtitles web site
  (http://www.opensubtitles.org).
  Using this protocol you get:
    a) EXACT MATCHES - instead of having a lot of subtitles matched to a single
       movie title, you assign them directly to a video file (using a specific
       fast hash function). So when searching for subtitles to a specific video
       file you'll only get those that (according to otherusers) match your
       video file 100%.
    
    b) SPEED - instead of searching for subtitles on the web site, you are
       provided with a user-friendly application that allows easy and fast
       search and download of subtitles.    
 
  OSDb is based on Gabest's ISDb design (http://isdb.saxtus.gr/) which is an
  online distributed subtitle database that first introduced this concept
  along with a 'distributed database' approach.
  
  To learn more visit the OpenSubtitles web site and its forum (see Links below). 


 Requirements
--------------
  Windows operating system (tested on WinXP SP2)
  internet connection


 Quick-start guide
-------------------
  We tried to make this application as user-friendly as possible. On the first
  start it will try to detect language used on your operating system and switch
  the user interface to this language (if available). It will also try to detect
  your proxy settings to enable online communication with the OSDb servers
  right away.
  
  Once the application is started you can add your video files by either
  dragging them from Explorer or by clicking the 'Add video' or 'Add folder'
  buttons.
  
  Once all the video files have been added press the 'Search for subtitles'
  button (magnifying glass icon in the lower right corner).
  
  The application will connect to the remote OSDb server and ask for subtitle
  files for your videos. This might take some time but should be fast enough.
  
  You can then browse thru them, select the ones you like most and download
  them to your local hard-disk drive.
  
  Most of the functionality for downloading is in the popup menus accessible
  thru right-clicking on subtitle or video files. You can either check all the
  subtitles you want and then choose 'Download selected' or you can download
  one-by-one by right-clicking a specific subtitle file and choosing 'Download'.
  
  Subtitle files are (by default) downloaded to the same directory as your video
  file and are renamed to match your video file. Most players should be able to
  find them and display them when you play your video file (tested on
  Media Player Classic). You can choose a different approach to this in the
  'Preferences'.
  
  
 Setting preferences
---------------------
  Preferences/settings are divided into 3 parts:
    a) Proxy: here you can set your proxy server settings to allow communication
              with OSDb servers. If you're not sure what it means, there's an
              'Auto-detect' button to try to figure out these settings for you.
              Try it!
    b) OSDb:  These settings apply to remote OSDb servers you want to use.   
              The most important is the server's URL. The default is:
                http://www.opensubtitles.org:80/xml-rpc
              You can change it if you want to try a different server supporting
              the OSDb protocol. If you're registered on the OSDb server, input
              your username/password here. You can also select your preferred
              subtitle languages here. Search will be performed only for
              languages selected/checked here.
              
    c) Options: several miscellaneous options can be set here.
                Template: here you can specify how you'd like your
                  subtitle files named. Available placeholders to use are:
                    %VPATH% - video file path
                    %VNAME% - video file name
                    %LANG%  - language description (e.g. "English")
                    %LANG2% - language ISO639 alpha-2 code (e.g. "en")
                    %LANG3% - language ISO639 alpha-3 code (e.g. "eng")
                    %USER%  - nickname of uploader
                    %ID%    - unique identifier of subtitle file on OSDb server
                    
                  An example will explain it best:
                    if you enter here: %VNAME%.%LANG3%_%USER%
                    then an english subtitle for video file 'Shawshank redemption.avi'
                    that resides in folder 'c:\movies\' will be saved to:
                      c:\movies\Shawshank redemption.eng_uploader.srt
                    
                  To help you out while editing a sample output filename is
                  displayed in the statusbar area, so don't be afraid to
                  experiment a little bit.
                  
                Other options should be self-explanatory.


 Hints
-------
  - if you can't make it work, try looking in the Log window for any error
      messages. They might give you an idea where the problem is so you can fix it.
  - don't forget to check your proxy settings if communication with OSDb server
      is failing.

      
 Developer notes
-----------------
  - this application is mainly meant as a 'testing grounds' for the OSDb Delphi
      class I'm developing now to allow fellow Delphi programmers to add OSDb
      functionality into their own applications (e.g. subtitle translators).
      Once this class/component is ready and tested I will release it too.
  - please keep in mind that this is a new concept (as opposed to other subtitle
      web sites that are here for quite some time) so the number of available
      subtitles is lower than can be found on the web. Nevertheless the more
      people use this system, the more subtitles will be available over time.
      So don't give up on us, we believe this is a concept worth looking into
      and contributing.
  - to find out what's new in the latest release see changelog.txt file
  - this file (notes.txt) is only a quick first draft and will be improved later.


 To-do list
------------
  - report incorrect subtitle attributes (IMDb ID, language, ...)
  - rate subtitles
  - batch uploading
  - OSDb server(s) management
  - there are a few issues regarding multi-language support that must be addressed
	- file overwrite prompts
	- Unicode support
	- GetTranslations() support
	- improve caching


 Known bugs/limitations
------------------------
  - some actions are not multi-threaded yet
  - IMDb search doesn't use the same proxy module as OSDb functions
  - it is NOT recommended to clear the 'Content' window (video and subtitle files)
      while search or download is underway.
  - the subtitle 'Show' feature only supports the basic subtitle formats
      (MicroDVD, SubRip)


 Links
-------
  OpenSubtitles.org  - http://www.opensubtitles.org
                         (impressive subtitles web page, home of OSDb)
  Gabest, guliverkli - http://sourceforge.net/projects/guliverkli
                         (home of Media Player Classic, VobSub, ISDb)
  SubDownloader      - http://subdownloader.sourceforge.net/
                         (another OSDb application also available for Linux platform,
                          also supports ISDb)
  OSDb XML-RPC API   - http://trac.opensubtitles.org/projects/opensubtitles/wiki/XMLRPC
                         (if you're interested in writing your own OSDb client 
                          application, take a look here at the possibilities offered)
                       
                         
[Majky, Dungeon Research 2007 - 2011]
