
1. Foreword
===========

This directory contains the webscripts quvi uses to parse the media
stream URLs. Should the parsing ever break, these are the scripts that
should be looked at first.

Refer to the libquvi API documentation at <http://quvi.sourceforge.net/doc/>
for a tutorial.

These scripts are written in lua. If you are new to lua,
<http://www.lua.org/pil/> is a good place to start.


2. Webscript
=================

Each webscript is expected to have the following functions:
  * ident (identifies the script to the library)
  * parse (parses the media details and returns them to the library)

To access the "utility functions" from your script, e.g.:
  local U = require 'quvi/util'
  local s = U.unescape(url)

See the 'util.lua' script in the lua/website/quvi/ directory for the
available functions.


table ident(self) [REQUIRED]
----------------------------

Identifies the script to the library. The library calls this function to
check if the script can handle the user specified URL.

Parameters:
  * self (table)
    - page_url (string)   -- User specified page URL
    - script_dir (string) -- Path to the directory containing this script

Returns: table containing the following details:

  * domain (string)
    - Identifies the script, this is essentially a pattern, e.g.
      "video.google." (note the lack of TLD) or "youtube.com"
    - Should cover any additional TLDs and website domain names
    - If the script can handle >1 (_different_) websites, put the
      domain names into an array, each domain name separated by '|',
      see collegehumor.lua for an example of this

  * formats (string)
    - Array of available format IDs (e.g. "default|best|hq|hd")
    - Contains at least "default"
    - Add "best" to the list *only if* there are more than one format
      ("default") IDs and the script contains an algorithm for parsing
      these additional formats

  * categories (number)
    - Bit pattern defining which categories this script belongs to
    - See quvi/const.lua for the available category bits (e.g. proto_*)
    - You can also use bit_or of quvi/bit.lua for multi-categorization
    - Most scripts usually set this to proto_http

  * handles (boolean)
    - Whether this script can handle the user specified page URL
    - For better results, use:

        local U   = require 'quvi/util'
        r.handles = U.handles(self.page_url,
            domain_patterns, path_patterns, query_patterns)

        See quvi/util.lua for "handles" function.


self query_formats(self) [REQUIRED]
-----------------------------------

Queries the URL for available formats.

Parameters:
  * self (table)
    - page_url (string) -- User specified page URL

Sets:
  * self.formats (string) -- Each format string separated by '|'
  Optional:
  * redirect_url (string, see collegehumor.lua)

Returns:
  * Updated `self' table


self parse(self) [REQUIRED]
---------------------------

Parses the media details.

Parameters:
  * self (table)
    - page_url         (string) -- User specified page URL
    - requested_format (string) -- User requested format ID

Sets:
  * host_id (string)
  * title   (string)
  * id      (string)
  * url     (array of strings)
  Optional:
  * redirect_url  (string, see academicearth.lua)
  * start_time    (string, see youtube.lua)
  * thumbnail_url (string)
  * duration      (numeric, msec)

Returns:
  * Updated `self' table


3. quvi object
==============

string quvi.fetch(url, options)
-------------------------------

Fetches data from the specified URL.

Parameters:
  * url     (string) -- URL to fetch
  * options (table)  -- Additional options [OPTIONAL]
    - fetch_type       (string)   ("page"|"config"|"playlist") =page
    - arbitrary_cookie (string)   e.g. "foo=1;bar=2"
        - <http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE>
    - user_agent       (string)   e.g. "foo/0.1"

Returns:
  * Fetched data

Examples:
  local data = quvi.fetch(url) -- fetch_type default is "page"
  local data = quvi.fetch(url, {fetch_type = 'config'})
  local data = quvi.fetch(url, {arbitrary_cookie = 'foo=1'})
  local data = quvi.fetch(url, {user_agent = 'foo/1.0'})


string quvi.resolve(url)
------------------------

Check whether the specified `url' redirects to a new location.

Parameters:
  * url (string) - URL to be checked

Returns:
  * New location or an empty string

Example:
  local n = quvi.resolve('http://is.gd/foobar')
  if #n > 0 then
    print('redirects to', n)
  end
