share/lua/website/README

   1
   2 1. Foreword
   3 ===========
   4
   5 This directory contains the webscripts quvi uses to parse the media
   6 stream URLs. Should the parsing ever break, these are the scripts that
   7 should be looked at first.
   8
   9 Refer to the libquvi API documentation at <http://quvi.sourceforge.net/doc/>
  10 for a tutorial.
  11
  12 These scripts are written in lua. If you are new to lua,
  13 <http://www.lua.org/pil/> is a good place to start.
  14
  15
  16 2. Webscript
  17 =================
  18
  19 Each webscript is expected to have the following functions:
  20   * ident (identifies the script to the library)
  21   * parse (parses the media details and returns them to the library)
  22
  23 To access the "utility functions" from your script, e.g.:
  24   local U = require 'quvi/util'
  25   local s = U.unescape(url)
  26
  27 See the 'util.lua' script in the lua/website/quvi/ directory for the
  28 available functions.
  29
  30
  31 table ident(self) [REQUIRED]
  32 ----------------------------
  33
  34 Identifies the script to the library. The library calls this function to
  35 check if the script can handle the user specified URL.
  36
  37 Parameters:
  38   * self (table)
  39     - page_url (string)   -- User specified page URL
  40     - script_dir (string) -- Path to the directory containing this script
  41
  42 Returns: table containing the following details:
  43
  44   * domain (string)
  45     - Identifies the script, this is essentially a pattern, e.g.
  46       "video.google." (note the lack of TLD) or "youtube.com"
  47     - Should cover any additional TLDs and website domain names
  48     - If the script can handle >1 (_different_) websites, put the
  49       domain names into an array, each domain name separated by '|',
  50       see collegehumor.lua for an example of this
  51
  52   * formats (string)
  53     - Array of available format IDs (e.g. "default|best|hq|hd")
  54     - Contains at least "default"
  55     - Add "best" to the list *only if* there are more than one format
  56       ("default") IDs and the script contains an algorithm for parsing
  57       these additional formats
  58
  59   * categories (number)
  60     - Bit pattern defining which categories this script belongs to
  61     - See quvi/const.lua for the available category bits (e.g. proto_*)
  62     - You can also use bit_or of quvi/bit.lua for multi-categorization
  63     - Most scripts usually set this to proto_http
  64
  65   * handles (boolean)
  66     - Whether this script can handle the user specified page URL
  67     - For better results, use:
  68
  69         local U   = require 'quvi/util'
  70         r.handles = U.handles(self.page_url,
  71             domain_patterns, path_patterns, query_patterns)
  72
  73         See quvi/util.lua for "handles" function.
  74
  75
  76 self query_formats(self) [REQUIRED]
  77 -----------------------------------
  78
  79 Queries the URL for available formats.
  80
  81 Parameters:
  82   * self (table)
  83     - page_url (string) -- User specified page URL
  84
  85 Sets:
  86   * self.formats (string) -- Each format string separated by '|'
  87   Optional:
  88   * redirect_url (string, see collegehumor.lua)
  89
  90 Returns:
  91   * Updated `self' table
  92
  93
  94 self parse(self) [REQUIRED]
  95 ---------------------------
  96
  97 Parses the media details.
  98
  99 Parameters:
 100   * self (table)
 101     - page_url         (string) -- User specified page URL
 102     - requested_format (string) -- User requested format ID
 103
 104 Sets:
 105   * host_id (string)
 106   * title   (string)
 107   * id      (string)
 108   * url     (array of strings)
 109   Optional:
 110   * redirect_url  (string, see academicearth.lua)
 111   * start_time    (string, see youtube.lua)
 112   * thumbnail_url (string)
 113   * duration      (numeric, msec)
 114
 115 Returns:
 116   * Updated `self' table
 117
 118
 119 3. quvi object
 120 ==============
 121
 122 string quvi.fetch(url, options)
 123 -------------------------------
 124
 125 Fetches data from the specified URL.
 126
 127 Parameters:
 128   * url     (string) -- URL to fetch
 129   * options (table)  -- Additional options [OPTIONAL]
 130     - fetch_type       (string)   ("page"|"config"|"playlist") =page
 131     - arbitrary_cookie (string)   e.g. "foo=1;bar=2"
 132         - <http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE>
 133     - user_agent       (string)   e.g. "foo/0.1"
 134
 135 Returns:
 136   * Fetched data
 137
 138 Examples:
 139   local data = quvi.fetch(url) -- fetch_type default is "page"
 140   local data = quvi.fetch(url, {fetch_type = 'config'})
 141   local data = quvi.fetch(url, {arbitrary_cookie = 'foo=1'})
 142   local data = quvi.fetch(url, {user_agent = 'foo/1.0'})
 143
 144
 145 string quvi.resolve(url)
 146 ------------------------
 147
 148 Check whether the specified `url' redirects to a new location.
 149
 150 Parameters:
 151   * url (string) - URL to be checked
 152
 153 Returns:
 154   * New location or an empty string
 155
 156 Example:
 157   local n = quvi.resolve('http://is.gd/foobar')
 158   if #n > 0 then
 159     print('redirects to', n)
 160   end