From 310743fb9ebbf68b253b923a309cc5f635da89a1 Mon Sep 17 00:00:00 2001 From: Antti Ajanki Date: Fri, 23 Jul 2010 20:55:11 +0300 Subject: release 0.3.0 --- doc/developers.txt | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 doc/developers.txt (limited to 'doc') diff --git a/doc/developers.txt b/doc/developers.txt new file mode 100644 index 0000000..8259e9c --- /dev/null +++ b/doc/developers.txt @@ -0,0 +1,152 @@ +libwebvi interface +================== + +See src/libwebvi/libwebvi.h for C API, src/unittest/testlibwebvi.c for +example code in C, and src/libwebvi/webvi/api.py for Python API. + + +XSLT templates for video sites +============================== + +libwebvi transforms the HTML of the web pages into a simple XML-based +format using the sites specific XSLT stylesheets stored under +templates directory. The XML describes navigation links and video +streams found on the web pages. The VDR plugin or the command line +client interprets the XML and displays a menu to the user. + +The following is an example libwebvi XML response for navigation page +(WEBVIREQ_MENU) query: + + + Page title + + + + wvt:///youtube/description.xsl?srcurl=... + wvt:///youtube/video.xsl?srcurl=... + + + + + + + + + + + Relevance + Date Added + View Count + Rating + + + + + + is the root node of a menu page. Possible children are +, <link>, <textfield>, <itemlist>, <textarea>, and <button> +nodes. + +The content of <title> will be shown as the title of the menu. + +<link> is a navigation link. It must have a child <label>, which +contains the text that will be shown to the user, and at least one of +<ref> (a navigation reference) or <stream> (a media stream reference). +The user interface provides three ways for selecting the link: a +navigation action loads a new menu page by retrieving the reference in +<ref> node from the library (using request type WEBVIREQ_MENU), a file +action downloads the stream by requesting <stream> reference from the +library (WEBVIREQ_FILE), stream URL action retrieves a direct URL to +the stream by requesting reference <stream> (WEBVIREQ_STREAMURL). + +<textarea> defines a text widget. Again, child node <label> contains +the text that will be displayed to the user. + +<textfield> defines a control for entering a string. + +<itemlist> defines a control for selecting one of the specified +<item>s. + +<button> is a special kind of link. It encodes the state of +<textfield>s and <itemlist>s into its reference. When the <button> is +selected the state of other controls is send to the library. The +reference is constructed by concatenating encoded values of each +<textfield> and <itemlist> to the content of <submission> node. Each +control is encoded as string "subst=name,value" where name is +URL encoded presentation of the name nodes name attribute, and value +is URL encoded presentation of the <textfield>'s UTF-8 input or value +attribute of currently selected <item> in an <itemlist>. The encodings +are joined by putting a "&" between them. + + +Format of wvt:// references +=========================== + +In libwebvi, the navigation and menu requests are encoded encoded as +URIs with scheme wvt:// . Typically, these references are extracted +from <ref> or <stream> nodes in the XML menu documents. This section +explains the format of the references. + +The references are of the form + +wvt://templatedir/template.xsl?srcurl=...&other_params=value + +The value of the srcurl parameter is a URL (typically an HTTP URL) of +a web page on a video site. templatedir/template.xsl specifies a name +of the XSLT template that is applied to the srcurl to get an XML menu. +srcurl can be empty. + +templatedir called bin is a special directory. It contains executable +programs or scripts instead of XSLT templates. When a reference to the +bin directory is encountered, the named script is executed. Script's +standard output is returned as the results of the operation. The +script should return 0 on success. + +Parameters that affect the template processing can be appended to the +reference. The parameter name and value are separated by '=', +different parameters are separated by '&'. Following parameters are +understood: + +param=name,value + +name and value are passed to the XSLT processor as an external +parameter. + +subst=name,value + +Replaces string {name} in srcurl with value before retrieving it. This +is used in search pages as discussed in previous section. + +contenttype=value + +value is used as content type if the server does not send a proper +content type header. + +arg=value + +Used to pass command line arguments to the external scripts in the bin +directory. There can be multiple args. + +minquality=value +maxquality=value + +Only the streams whose quality ("priority" attribute of the "url" tag) +is between minquality and maxquality are considered as candidates when +selecting a stream to play. The default limits are 0 and 100. + +postprocess=json2xml + +The source is a JSON document which should be converted to XML before +the XSLT transformation. + +http-header=headername,headervalue + +Append a HTTP header to the request. Ignored on transfers that use +some other protocol besides HTTP. + +The reference to the main menu is wvt:///?srcurl=mainmenu . -- cgit v1.2.3