videosite/readme.txt

   1 There are two different kind of plugins in this directory:
   2 grabbers and getters.
   3
   4 Grabbers
   5 ========
   6
   7 The job of the Grabbers is to determine the download URL of the
   8 actual media file we want to get (in case of flash video sites
   9 that means to find out the URL which contains the actual flash
  10 video file, in contrast to the URL of the page where the flash
  11 plugin is embedded in).
  12
  13 All Grabbers inherit from GrabberBase, which defines some methods
  14 shared by all Grabbers.
  15
  16 In order to be loaded, a Grabber module must be named *Grabber.pm
  17 (i.e., the file name of the module must end with Grabber.pm).
  18
  19
  20 Methods
  21 -------
  22
  23 get(line):
  24 This method is called for each of the installed grabbers, in turn
  25 (there is no guaranteed order for this) for each line received by
  26 irssi in any channel you are connected to.
  27
  28 If the Grabber determines that a URL it can handle is mentioned in
  29 this line it is supposed to determine the metadata hash (more of this
  30 later) and return it. If the Grabber does not think the line interesting
  31 it returns undef, and the line is passed to the next Grabber.
  32
  33 Note:
  34 Usually, you do _not_ need to overload this method in your Grabber.
  35 The default method looks for a property called 'PATTERNS' in your
  36 Grabber and treats this as an array reference, containing regex patterns
  37 matching the URLs the Grabber is interested in. If one of these patterns
  38 matches line, the method _parse is called like this:
  39 return $self->_parse(line, pattern);
  40
  41 If you define your own Grabber, overload _parse instead, unless you
  42 want a totaly different approach.
  43
  44
  45 Properties
  46 ----------
  47
  48 NAME:
  49 A name for your Grabber. Has to be unique among all Grabbers and Getters
  50 installed.
  51
  52 PATTERNS:
  53 See the description for get() under Methods.
  54
  55
  56 Getters
  57 =======
  58
  59 The job of a Getter is to actually download a media file, the metadata of
  60 which has been determined by a Grabber.
  61
  62 All Getters inherit from GetterBase, which defines some methods shared by all
  63 Getters.
  64
  65 In order to be loaded, a Getter module must be named *Getter.pm
  66 (i.e., the file name of the module must end with Getter.pm).
  67
  68
  69 Methods
  70 -------
  71
  72 get(metadata):
  73 This method is called with a metadata hash containing the data of a file that
  74 is to be downloaded. See below for a description of the content of the hash.
  75
  76 The implementation of the actual download method is entirely left to the
  77 Getter. The Getter should return 1 on success, and 0 on failure.
  78
  79
  80 Properties
  81 ----------
  82
  83 NAME:
  84 A name for your Getter. Has to be unique among all Getters and Grabbers
  85 installed.
  86
  87
  88 The Metadata
  89 ============
  90
  91 The Metadata is a hash describing various properties of a media file to be
  92 downloaded. A Grabber produces a Metadata hash if it has found an URL of
  93 interest and was able to determine all data necessary to download the media
  94 file. The Metadata is then passed to a Getter, which uses the data to
  95 download the file and give it a recognizable name. The Metadata should
  96 (at least) contain the following fields:
  97
  98 TITLE:
  99 A short, textual description of the file, usually taken from the site the
 100 file was taken from.
 101
 102 ID:
 103 A number or string describing the file in the context of the site the file is
 104 from. This is usually unique for a single site, but does not have to be across
 105 different sites (or, in other words, the tuple [ID, SOURCE] should be unique)
 106
 107 SOURCE:
 108 A short string describing the site the file is from. Should be a single word,
 109 like 'youtube' or '4chan'.
 110
 111 URL:
 112 The URL of the site the media file was embedded in (this is usually the URL
 113 that was accepted and parsed by the Grabber).
 114
 115 DLURL:
 116 The URL of the actual media file. This is the file that should be downloaded
 117 by the Getter.
 118
 119 TYPE:
 120 A short string describing the nature of the media file. Should be a single
 121 word, like 'video' or 'image'.
 122
 123
 124
 125 Parameters
 126 ==========
 127
 128 If you want your Grabber or Getter to have user settable parameters, which are
 129 saved across different runs of the plugin you can use the built-in parameter
 130 handling, which will take care of automagically saving and loading your
 131 parameters.
 132
 133 In order to use it three steps are necessary:
 134
 135 a) in your constructor, define a property called '_PARAMS'. This is a
 136 reference to a hash of array references, tke key being the name of your
 137 parameter, and the array containing the default value of the parameter as the
 138 first field, and a textual description string as the second field.
 139
 140 For example, a parameter called FOO, having a default value of 42 and a
 141 description of 'This is the FOO parameter, twiddle it to do stuff' would be
 142 declared as follows:
 143
 144 sub new {
 145     my $class = shift;
 146     my $self = $class->SUPER::new(
 147         _PARAMS => {'FOO' => [42, 'This is the FOO parameter, twiddle it to do stuff']},
 148         @_,
 149     );
 150     return bless($self, $class);
 151 }
 152
 153 b) to access one of the parameters, call the _getval() method, giving the name
 154 of the parameter as first argument. This will return the current value of that
 155 parameter (either the default value or the user defined value).