1NAME 2 Music::Audioscrobbler::Submit - Module providing routines to submit 3 songs to last.fm using 1.2 protocol. 4 5DESCRIPTION 6 Music::Audioscrobbler::Submit is a scrobbler for MPD implementing the 7 1.2 protocol, including "Now Playing' feature. 8 9 Items are submitted and stored in a queue. This queue is stored as a 10 file using Tie::File. When you submit a track, it will add the queue to 11 the track and process the queue. If it submits all items in the queue, 12 the submit() method will return true. A method called 13 process_scrobble_queue() allows you to try again in case of failure. Do 14 not submit songs more than once! 15 16INSTALLATION 17 To install this module type the following: 18 19 perl Makefile.PL 20 make 21 make test 22 make install 23 24DEPENDENCIES 25 This module requires these other modules and libraries: 26 27 Encode 28 File::Spec 29 Digest::MD5 30 Config::Options 31 LWP 32 Tie::File 33 Music::Tag 34 35METHODS 36 new() 37 my $mas = Music::Audioscrobbler::Submit->new($options); 38 39 options() 40 Get or set options via hash. Here is a list of available options: 41 42 lastfm_username 43 lastfm username 44 45 lastfm_password 46 lastfm password. Not needed if lastfm_md5password is set. 47 48 lastfm_md5password 49 MD5 hash of lastfm password. 50 51 lastfm_client_id 52 Client ID provided by last.fm. Defaults to "tst", which is valid 53 for testing only. 54 55 lastfm_client_version 56 Set to the version of your program when setting a valid 57 client_id. Defaults to "1.0" 58 59 verbose 60 Set verbosity level (1 through 4) 61 62 logfile 63 File to output log info to. If set to "STDERR" or undef, will 64 print messages to STDERR. If set to "STDOUT" will print messages 65 to STDOUT. 66 67 scrobble_queue 68 Path to file to queue info to. Defaults to 69 ~/.musicaudioscrobbler_queue 70 71 get_mbid_from_mb 72 Use the Music::Tag::MusicBrainz plugin to get missing "mbid" 73 value. Defaults false. 74 75 musictag 76 True if you want to use Music::Tag to get info from file. This 77 is important if you wish to use filenames to submit from. 78 79 musictag_overwrite 80 True if you want to Music::Tag info to override file info. 81 Defaults to false, which with the unicode problems with 82 Music::Tag is a good thing. 83 84 music_tag_opts 85 Options for Music::Tag 86 87 proxy_server 88 URL for proxy_server in the form http://my.proxy.ca:8080 89 90 default_options() 91 Returns a reference to the default options. 92 93 now_playing() 94 Takes a file, hashref, or Music::Tag object and submits the song to 95 Last.FM now playing info. For example: 96 97 $mas->now_playing("/path/to/file.mp3"); 98 99 The hash reference is of the form: 100 101 { artist => "Artist Name", # Mandatory 102 title => "Song Title" # Mandatory 103 secs => 300, # Length of time in seconds (integers only please). Mandatory 104 album => "Album", # Optional 105 tracknum => 12, # Optional 106 mbid => '6299a467-95bc-4bc1-925d-71c4e556770d' # Optional 107 } 108 109 submit() 110 To submit a song pass an arrayref whose first entry is a File, 111 Music::Tag object, or hashref (see now_playing()) for format) and 112 whose second entry is an integer representing the seconds since 113 epoch (UNIX time). Several songs can be submitted simultaneously. 114 For example: 115 116 $mas->submit->(["/path/to/file.mp3", time]); 117 118 or: 119 120 $mas->submit->( ["/var/mp3s/song1.mp3", time - 600 ], 121 ["/var/mp3s/song2.mp3", time - 300 ], 122 ["/var/mp3s/song3.mp3", time ] ); 123 124 Returns true if song was scrobbled, false otherwise. submit calls 125 process_scrobble_queue(). If it fails, process_scrobble_queue() can 126 be called again. 127 128 The following is taken from 129 http://www.audioscrobbler.net/development/protocol/: 130 131 The client should monitor the user's interaction with the music 132 playing service to whatever extent the service allows. In order to 133 qualify for submission all of the following criteria must be met: 134 135 1. The track must be submitted once it has finished playing. Whether 136 it has finished playing naturally or has been manually stopped by 137 the user is irrelevant. 138 139 2. The track must have been played for a duration of at least 240 140 seconds or half the track's total length, whichever comes first. 141 Skipping or pausing the track is irrelevant as long as the 142 appropriate amount has been played. 143 144 3. The total playback time for the track must be more than 30 145 seconds. Do not submit tracks shorter than this. 146 147 4. Unless the client has been specially configured, it should not 148 attempt to interpret filename information to obtain metadata instead 149 of tags (ID3, etc). 150 151 process_scrobble_queue() 152 Processes the current scrobble queue. Call this if submit fails and 153 you wish to try again. Do not resubmit a song. 154 155 handshake() 156 Perform handshake with Last.FM. You don't need to call this, it will 157 be called by submit() or now_playing() when necessary. 158 159 music_tag_opts() 160 Get or set the current options for new Music::Tag objects. 161 162 logfileout() 163 Glob reference (or IO::File) to current log file. If passed a value, 164 will use this instead of what the logfile option is set to. Any glob 165 reference that can be printed to will work (that's all we ever do). 166 167 status() 168 Print to log. First argument is a level (0 - 4). For example: 169 170 $mas->status($level, @message); 171 172 scrobble_queue() 173 Returns a reference to the current scrobble_queue. This is a tied 174 hash using Tie::File. Useful to found out how many items still need 175 to be scrobbled after a failed submit(). 176 177 ua() 178 Returns the LWP::UserAgent used. If passed a value, will use that as 179 the new LWP::UserAgent object. 180 181 info_to_hash() 182 Takes a filename, hashref, or Music::Tag object and returns a hash 183 with the structure required by submit() or now_playing. Normally 184 this is called automatically by submit() or now_playing. See 185 now_playing for syntax of hash. 186 187 Examples: 188 189 my $hash = $mas->info_to_hash("/path/to/mp3/file.mp3"); 190 191 is functionally equivalent to 192 193 my $hash = $mas->info_to_hash(Music::Tag->new("/path/to/mp3/file.mp3", $mas->music_tag_opts() )); 194 195SEE ALSO 196 Music::Tag, Music::Audioscrobbler::MPD 197 198CHANGES 199 Release Name: 0.05 200 * Added new option: proxy_server to set proxy_server. Also now 201 reads proxy server from enviroment. 202 203 Release Name: 0.04 204 * I noticed that Music::Tag was called with a use function. 205 Removed this line to remove Music::Tag requirement. 206 207 * Added some more level 4 debuging messages. 208 209 Release Name: 0.03 210 * Added musictag_overwrite option. This is false by default. It is 211 a workaround for problems with Music::Tag and unicode. Setting 212 this to true allows Music::Tag info to overwrite info from MPD. 213 Do not set this to true until Music::Tag returns proper unicode 214 consistantly. 215 216 Release Name: 0.02 217 * Will print error and die if lastfm_password is not set. 218 219 * Will print error and die if BADAUTH is received. 220 221 Release Name: 0.01 222 * Initial Release 223 224AUTHOR 225 Edward Allen III <ealleniii _at_ cpan _dot_ org> 226 227COPYRIGHT 228 Copyright (c) 2007,2008 Edward Allen III. Some rights reserved. 229 230LICENSE 231 This program is free software; you can redistribute it and/or modify it 232 under the same terms as Perl itself, either: 233 234 a) the GNU General Public License as published by the Free Software 235 Foundation; either version 1, or (at your option) any later version, or 236 237 b) the "Artistic License" which comes with Perl. 238 239 This program is distributed in the hope that it will be useful, but 240 WITHOUT ANY WARRANTY; without even the implied warranty of 241 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU 242 General Public License or the Artistic License for more details. 243 244 You should have received a copy of the Artistic License with this Kit, 245 in the file named "Artistic". If not, I'll be glad to provide one. 246 247 You should also have received a copy of the GNU General Public License 248 along with this program in the file named "Copying". If not, write to 249 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 250 Boston, MA 02110-1301, USA or visit their web page on the Internet at 251 http://www.gnu.org/copyleft/gpl.html. 252 253