Update NEWS for v0.9.20131130
[libquvi-scripts.git] / share / lua / website / README
Commit [+]AuthorDateLineData
62cc25f1
TG
Toni Gundogdu2011-09-19 19:39:08 +03001
21. Foreword
3===========
4
5This directory contains the webscripts quvi uses to parse the media
6stream URLs. Should the parsing ever break, these are the scripts that
7should be looked at first.
8
9Refer to the libquvi API documentation at <http://quvi.sourceforge.net/doc/>
10for a tutorial.
11
12These 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
162. Webscript
17=================
18
19Each 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
23To access the "utility functions" from your script, e.g.:
24 local U = require 'quvi/util'
25 local s = U.unescape(url)
26
27See the 'util.lua' script in the lua/website/quvi/ directory for the
28available functions.
29
30
31table ident(self) [REQUIRED]
32----------------------------
33
34Identifies the script to the library. The library calls this function to
35check if the script can handle the user specified URL.
36
37Parameters:
38 * self (table)
39 - page_url (string) -- User specified page URL
40 - script_dir (string) -- Path to the directory containing this script
41
42Returns: 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
76self query_formats(self) [REQUIRED]
77-----------------------------------
78
79Queries the URL for available formats.
80
81Parameters:
82 * self (table)
83 - page_url (string) -- User specified page URL
84
85Sets:
86 * self.formats (string) -- Each format string separated by '|'
87 Optional:
88 * redirect_url (string, see collegehumor.lua)
89
90Returns:
91 * Updated `self' table
92
93
94self parse(self) [REQUIRED]
95---------------------------
96
97Parses the media details.
98
99Parameters:
100 * self (table)
101 - page_url (string) -- User specified page URL
102 - requested_format (string) -- User requested format ID
103
104Sets:
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
115Returns:
116 * Updated `self' table
117
118
1193. quvi object
120==============
121
122string quvi.fetch(url, options)
123-------------------------------
124
125Fetches data from the specified URL.
126
127Parameters:
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
135Returns:
136 * Fetched data
137
138Examples:
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
145string quvi.resolve(url)
146------------------------
147
148Check whether the specified `url' redirects to a new location.
149
150Parameters:
151 * url (string) - URL to be checked
152
153Returns:
154 * New location or an empty string
155
156Example:
157 local n = quvi.resolve('http://is.gd/foobar')
158 if #n > 0 then
159 print('redirects to', n)
160 end