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