share/lua/website/README

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