share/lua/website/README

   1
   2 1. Foreword
   3 ===========
   4
   5 This directory contains the website scripts quvi uses to parse the video
   6 links. Should video link parsing ever break (and they will eventually),
   7 these are the scripts that one should take a look at first.
   8
   9 These scripts are written in Lua. If you are new to Lua,
  10 <http://www.lua.org/pil/> is a good place to start.
  11
  12
  13 2. Structure of an quvi website script
  14 ======================================
  15
  16 Each website script must contain the following functions:
  17   * ident
  18   * parse
  19
  20
  21 2.1. function ident (page_url)
  22 ------------------------------
  23
  24 quvi calls this function to check if the script can handle
  25 the user specified video page URL.
  26
  27 Parameters:
  28   * page_url (string)
  29
  30 Returns:
  31   * A table containing the following keys
  32
  33     - domain (string)
  34       - This string is used to match page URL to domain
  35       - Returned to an application with quvi_next_supported_website
  36       - The string must cover any TLDs and additional domain names
  37       - e.g. "youtube.com", "video.google."
  38
  39     - formats (string)
  40       - An "array" of the supported video format IDs, e.g. "default|best|hq|hd"
  41       - All scripts should at least define "default" in this string
  42       - Should include "best" if there are more than just "default" ID
  43
  44     - handles (boolean)
  45       - Used to check whether the script can handle the user specified URL
  46
  47
  48 2.2. function parse (video)
  49 ---------------------------
  50
  51 quvi calls this function to fetch and parse the user specified URL.
  52 This function looks typically very different for each website. Compare
  53 buzzhumor.lua and youtube.lua for an example of this.
  54
  55 The "parse" function is expected set/update the following video details:
  56   * host_id (string)
  57   * title (string)
  58   * id (string)
  59   * url (array of strings)
  60   * redirect (string) [see notes below]
  61
  62 Each of these belong to the `video' table passed to the function
  63 as a parameter. e.g. video.host_id = 'youtube' or video.id = '1234'
  64
  65 Parameters:
  66   * quvi sets the following table keys before it runs the script
  67     - page_url (string)         -- user specified URL
  68     - requested_format (string) -- user requested video format ID
  69
  70 Returns:
  71   * The updated `video' table
  72
  73 Notes:
  74   * "redirect", special field, if set (default:empty):
  75     - Drop user specified URL and follow to the redirect URL instead
  76     - This replaces the original user defined URL (set by quvi_parse)
  77     - See academicearth.lua script for an example
  78
  79
  80 3. Exposed C functions
  81 ======================
  82
  83 quvi exposes the following C functions to the website scripts. Each of
  84 these are in the "quvi" object, e.g. quvi.fetch.
  85
  86
  87 3.1. Function: string quvi.fetch (url, what, arbitrary_cookie)
  88 --------------------------------------------------------------
  89
  90 Fetches data from the specified URL.
  91
  92 Parameters:
  93   * url (string)                - URL to fetch
  94   * what (string)               - "page", "config" or "playlist" (optional)
  95   * arbitrary_cookie (string)   - e.g. "foo=bar" (optional)
  96
  97 quvi converts the `what' string to a matching QUVIstatusstype (see
  98 quvi/quvi.h). If `what' is nil (undefined), quvi defaults to "page".
  99
 100 arbitrary_cookie value is passed (as it is) to libcurl, see:
 101   http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE
 102
 103 Returns:
 104   * Fetched data
 105
 106
 107 3.2. Function: string quvi.unescape (string)
 108 --------------------------------------------
 109
 110 Returns an unescaped `string'.
 111
 112 Parameters:
 113   * string
 114
 115 Returns:
 116   * Unescaped string