X-Git-Url: https://git.camperquake.de/gitweb.cgi?a=blobdiff_plain;f=videosite%2Freadme.txt;fp=videosite%2Freadme.txt;h=943e4302dfa426321db886446329669da01855f1;hb=33b92ba121e365e552b0a602fd0c6d1f625926c2;hp=0000000000000000000000000000000000000000;hpb=60da6f4bc6779c9faa41a1e1dba6c0afbe9706ee;p=videosite.git diff --git a/videosite/readme.txt b/videosite/readme.txt new file mode 100644 index 0000000..943e430 --- /dev/null +++ b/videosite/readme.txt @@ -0,0 +1,162 @@ +There are two different kind of plugins in this directory: +grabbers and getters. + +Grabbers +======== + +The job of the Grabbers is to determine the download URL of the +actual media file we want to get (in case of flash video sites +that means to find out the URL which contains the actual flash +video file, in contrast to the URL of the page where the flash +plugin is embedded in). + +All Grabbers inherit from GrabberBase, which defines some methods +shared by all Grabbers. + +In order to be loaded, a Grabber module must be named *Grabber.pm +(i.e., the file name of the module must end with Grabber.pm). + + +Methods +------- + +get(line): +This method is called for each of the installed grabbers, in turn +(there is no guaranteed order for this) for each line received by +irssi in any channel you are connected to. + +If the Grabber determines that a URL it can handle is mentioned in +this line it is supposed to determine the metadata hash (more of this +later) and return it. If the Grabber does not think the line interesting +it returns undef, and the line is passed to the next Grabber. + +Note: +Usually, you do _not_ need to overload this method in your Grabber. +The default method looks for a property called 'PATTERNS' in your +Grabber and treats this as an array reference, containing regex patterns +matching the URLs the Grabber is interested in. If one of these patterns +matches line, the method _parse is called like this: +return $self->_parse(line, pattern); + +If you define your own Grabber, overload _parse instead, unless you +want a totaly different approach. + + +Properties +---------- + +NAME: +A name for your Grabber. Has to be unique among all Grabbers and Getters +installed. + +PATTERNS: +See the description for get() under Methods. + + +Getters +======= + +The job of a Getter is to actually download a media file, the metadata of +which has been determined by a Grabber. + +All Getters inherit from GetterBase, which defines some methods shared by all +Getters. + +In order to be loaded, a Getter module must be named *Getter.pm +(i.e., the file name of the module must end with Getter.pm). + + +Methods +------- + +get(metadata): +This method is called with a metadata hash containing the data of a file that +is to be downloaded. See below for a description of the content of the hash. + +The implementation of the actual download method is entirely left to the +Getter. The Getter should return 1 on success, and 0 on failure. + + +Properties +---------- + +NAME: +A name for your Getter. Has to be unique among all Getters and Grabbers +installed. + + +The Metadata +============ + +The Metadata is a hash describing various properties of a media file to be +downloaded. A Grabber produces a Metadata hash if it has found an URL of +interest and was able to determine all data necessary to download the media +file. The Metadata is then passed to a Getter, which uses the data to +download the file and give it a recognizable name. The Metadata should +(at least) contain the following fields: + +TITLE: +A short, textual description of the file, usually taken from the site the +file was taken from. + +ID: +A number or string describing the file in the context of the site the file is +from. This is usually unique for a single site, but does not have to be across +different sites (or, in other words, the tuple [ID, SOURCE] should be unique) + +SOURCE: +A short string describing the site the file is from. Should be a single word, +like 'youtube' or '4chan'. + +URL: +The URL of the site the media file was embedded in (this is usually the URL +that was accepted and parsed by the Grabber). + +DLURL: +The URL of the actual media file. This is the file that should be downloaded +by the Getter. + +TYPE: +A short string describing the nature of the media file. Should be a single +word, like 'video' or 'image'. + + + +Parameters +========== + +If you want your Grabber or Getter to have user settable parameters, which are +saved across different runs of the plugin you can use the built-in parameter +handling, which will take care of automagically saving and loading your +parameters. + +In order to use it three steps are necessary: + +a) in your constructor, define a property called '_PARAMS'. This is a +reference to a hash of array references, tke key being the name of your +parameter, and the array containing the default value of the parameter as the +first field, and a textual description string as the second field. + +For example, a parameter called FOO, having a default value of 42 and a +description of 'This is the FOO parameter, twiddle it to do stuff' would be +declared as follows: + +sub new { + my $class = shift; + my $self = $class->SUPER::new(); + + $self->{'_PARAMS'} = {'FOO' => [42, 'This is the FOO parameter, twiddle it to do stuff']}; + bless($self, $class); + $self->_prepare_parameters(); + + return $self; +} + +b) as seen in the example above, after declaring the parameter hash, call the +method _prepare_parameters() on your class instance. This will convert the +hash into the internally used data structure and prepare it for automatic +loading and saving. + +c) to access one of the parameters, call the _getval() method, giving the name +of the parameter as first argument. This will return the current value of that +parameter (either the default value or the user defuned value).