Update NEWS for v0.9.20131130
[libquvi-scripts.git] / 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