0
# Music Objects
1
2
Comprehensive music entity objects (Artist, Track, Album) providing access to metadata, statistics, social features, and content discovery. These objects form the core of PyLast's music data interface with rich functionality for music information retrieval and social interaction.
3
4
## Capabilities
5
6
### Artist Objects
7
8
Represents music artists with comprehensive metadata, statistics, social features, and discovery capabilities.
9
10
```python { .api }
11
class Artist:
12
"""
13
Represents a music artist.
14
15
Args:
16
name (str): Artist name
17
network: Network instance (LastFMNetwork or LibreFMNetwork)
18
username (str, optional): Username for user-specific data
19
info (dict, optional): Preloaded artist information
20
"""
21
def __init__(self, name: str, network, username=None, info=None): ...
22
23
def get_name(self, properly_capitalized=False) -> str:
24
"""
25
Get artist name.
26
27
Args:
28
properly_capitalized (bool): Return properly capitalized name from Last.fm
29
30
Returns:
31
str: Artist name
32
"""
33
34
def get_correction(self) -> str:
35
"""Get corrected artist name from Last.fm if available."""
36
37
def get_playcount(self) -> int:
38
"""Get total play count for this artist."""
39
40
def get_userplaycount(self, username: str = None) -> int:
41
"""
42
Get play count for specific user.
43
44
Args:
45
username (str, optional): Username, uses authenticated user if None
46
47
Returns:
48
int: User's play count for this artist
49
"""
50
51
def get_listener_count(self) -> int:
52
"""Get total number of listeners for this artist."""
53
54
def get_mbid(self) -> str:
55
"""Get MusicBrainz ID for this artist."""
56
57
def get_similar(self, limit=None) -> list[SimilarItem]:
58
"""
59
Get similar artists.
60
61
Args:
62
limit (int, optional): Maximum number of results
63
64
Returns:
65
list[SimilarItem]: Similar artists with match percentages
66
"""
67
68
def get_top_albums(self, limit=None, cacheable=True) -> list[TopItem]:
69
"""Get top albums by this artist."""
70
71
def get_top_tracks(self, limit=None, cacheable=True) -> list[TopItem]:
72
"""Get top tracks by this artist."""
73
74
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
75
"""Get top tags for this artist."""
76
77
def get_top_fans(self, limit=None, cacheable=True) -> list[TopItem]:
78
"""Get top fans (users) of this artist."""
79
80
def get_bio_published_date(self) -> str:
81
"""Get artist biography publication date."""
82
83
def get_bio_summary(self, language=0) -> str:
84
"""
85
Get artist biography summary.
86
87
Args:
88
language (int): Language domain (default: DOMAIN_ENGLISH)
89
90
Returns:
91
str: Biography summary
92
"""
93
94
def get_bio_content(self, language=0) -> str:
95
"""Get full artist biography content."""
96
97
def get_url(self, domain_name=0) -> str:
98
"""
99
Get Last.fm URL for this artist.
100
101
Args:
102
domain_name (int): Language domain
103
104
Returns:
105
str: Artist's Last.fm URL
106
"""
107
108
def get_images(self, order="popularity", limit=None) -> list[Image]:
109
"""
110
Get artist images.
111
112
Args:
113
order (str): Sort order ("popularity" or "dateadded")
114
limit (int, optional): Maximum number of images
115
116
Returns:
117
list[Image]: Artist images with metadata
118
"""
119
```
120
121
### Track Objects
122
123
Represents music tracks with metadata, user interactions, similarity data, and social features.
124
125
```python { .api }
126
class Track:
127
"""
128
Represents a music track.
129
130
Args:
131
artist (str): Artist name
132
title (str): Track title
133
network: Network instance
134
username (str, optional): Username for user-specific data
135
info (dict, optional): Preloaded track information
136
"""
137
def __init__(self, artist: str, title: str, network, username=None, info=None): ...
138
139
def get_artist(self) -> Artist:
140
"""Get Artist object for this track's artist."""
141
142
def get_title(self) -> str:
143
"""Get track title."""
144
145
def get_name(self, properly_capitalized=False) -> str:
146
"""Get track name (alias for get_title)."""
147
148
def get_album(self) -> Album:
149
"""Get Album object that contains this track."""
150
151
def get_correction(self) -> str:
152
"""Get corrected track name from Last.fm if available."""
153
154
def get_duration(self) -> int:
155
"""
156
Get track duration in milliseconds.
157
158
Returns:
159
int: Duration in milliseconds, or None if unavailable
160
"""
161
162
def get_playcount(self) -> int:
163
"""Get total play count for this track."""
164
165
def get_userplaycount(self, username: str = None) -> int:
166
"""Get play count for specific user."""
167
168
def get_listener_count(self) -> int:
169
"""Get total number of listeners for this track."""
170
171
def get_userloved(self, username: str = None) -> bool:
172
"""
173
Check if user has loved this track.
174
175
Args:
176
username (str, optional): Username, uses authenticated user if None
177
178
Returns:
179
bool: True if user has loved this track
180
"""
181
182
def love(self) -> None:
183
"""Love this track (requires authentication)."""
184
185
def unlove(self) -> None:
186
"""Remove love from this track (requires authentication)."""
187
188
def get_similar(self, limit=None) -> list[SimilarItem]:
189
"""Get similar tracks."""
190
191
def get_top_fans(self, limit=None, cacheable=True) -> list[TopItem]:
192
"""Get top fans of this track."""
193
194
def get_cover_image(self, size=2) -> str:
195
"""
196
Get track cover art URL.
197
198
Args:
199
size (int): Image size (SIZE_SMALL to SIZE_MEGA)
200
201
Returns:
202
str: Cover image URL
203
"""
204
205
def get_wiki_published_date(self) -> str:
206
"""Get track wiki publication date."""
207
208
def get_wiki_summary(self, language=0) -> str:
209
"""Get track wiki summary."""
210
211
def get_wiki_content(self, language=0) -> str:
212
"""Get track wiki full content."""
213
214
def get_url(self, domain_name=0) -> str:
215
"""Get Last.fm URL for this track."""
216
```
217
218
### Album Objects
219
220
Represents music albums with track listings, metadata, and social features.
221
222
```python { .api }
223
class Album:
224
"""
225
Represents a music album.
226
227
Args:
228
artist (str): Artist name
229
title (str): Album title
230
network: Network instance
231
username (str, optional): Username for user-specific data
232
info (dict, optional): Preloaded album information
233
"""
234
def __init__(self, artist: str, title: str, network, username=None, info=None): ...
235
236
def get_artist(self) -> Artist:
237
"""Get Artist object for this album's artist."""
238
239
def get_title(self) -> str:
240
"""Get album title."""
241
242
def get_name(self, properly_capitalized=False) -> str:
243
"""Get album name (alias for get_title)."""
244
245
def get_tracks(self) -> list[Track]:
246
"""
247
Get list of tracks on this album.
248
249
Returns:
250
list[Track]: All tracks on the album
251
"""
252
253
def get_playcount(self) -> int:
254
"""Get total play count for this album."""
255
256
def get_userplaycount(self, username: str = None) -> int:
257
"""Get play count for specific user."""
258
259
def get_listener_count(self) -> int:
260
"""Get total number of listeners for this album."""
261
262
def get_cover_image(self, size=2) -> str:
263
"""
264
Get album cover art URL.
265
266
Args:
267
size (int): Image size (SIZE_SMALL to SIZE_MEGA)
268
269
Returns:
270
str: Cover image URL
271
"""
272
273
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
274
"""Get top tags for this album."""
275
276
def get_wiki_published_date(self) -> str:
277
"""Get album wiki publication date."""
278
279
def get_wiki_summary(self, language=0) -> str:
280
"""Get album wiki summary."""
281
282
def get_wiki_content(self, language=0) -> str:
283
"""Get album wiki full content."""
284
285
def get_url(self, domain_name=0) -> str:
286
"""Get Last.fm URL for this album."""
287
```
288
289
### Tag Management
290
291
All music objects (Artist, Track, Album) support tag management for categorization and discovery.
292
293
```python { .api }
294
# Tag management methods (available on Artist, Track, Album)
295
296
def add_tags(self, tags: tuple[str, ...]) -> None:
297
"""
298
Add tags to this music object.
299
300
Args:
301
tags (tuple[str, ...]): Tags to add
302
"""
303
304
def remove_tag(self, tag: str) -> None:
305
"""
306
Remove a tag from this music object.
307
308
Args:
309
tag (str): Tag to remove
310
"""
311
312
def get_tags(self) -> list[Tag]:
313
"""
314
Get tags applied to this music object.
315
316
Returns:
317
list[Tag]: Tags applied by the authenticated user
318
"""
319
320
def get_top_tags(self, limit=None, cacheable=True) -> list[TopItem]:
321
"""
322
Get top tags for this music object.
323
324
Returns:
325
list[TopItem]: Most popular tags with weights
326
"""
327
```
328
329
### Additional Music Object Methods
330
331
Additional utility methods available on music objects for URL generation and metadata access.
332
333
```python { .api }
334
# Additional methods (available on Artist, Track, Album)
335
336
def get_url(self, domain_name: int = 0) -> str:
337
"""
338
Get Last.fm URL for this music object.
339
340
Args:
341
domain_name (int): Language domain (DOMAIN_ENGLISH, DOMAIN_GERMAN, etc.)
342
343
Returns:
344
str: Last.fm URL for this object
345
"""
346
347
def get_mbid(self) -> str | None:
348
"""
349
Get MusicBrainz ID for this music object.
350
351
Returns:
352
str | None: MusicBrainz ID if available, None otherwise
353
"""
354
```
355
356
## Usage Examples
357
358
### Working with Artists
359
360
```python
361
import pylast
362
363
network = pylast.LastFMNetwork(api_key=API_KEY, api_secret=API_SECRET)
364
365
# Get artist and basic info
366
artist = network.get_artist("Radiohead")
367
print(f"Artist: {artist.get_name(properly_capitalized=True)}")
368
print(f"Listeners: {artist.get_listener_count():,}")
369
print(f"Play count: {artist.get_playcount():,}")
370
371
# Get similar artists
372
similar = artist.get_similar(limit=5)
373
for similar_artist in similar:
374
print(f"Similar: {similar_artist.item.get_name()} ({similar_artist.match}% match)")
375
376
# Get top tracks
377
top_tracks = artist.get_top_tracks(limit=10)
378
for track_item in top_tracks:
379
track = track_item.item
380
print(f"Top track: {track.get_title()} (weight: {track_item.weight})")
381
382
# Get artist biography
383
bio_summary = artist.get_bio_summary()
384
print(f"Bio: {bio_summary[:200]}...")
385
```
386
387
### Working with Tracks
388
389
```python
390
# Get track and interact with it
391
track = network.get_track("Radiohead", "Paranoid Android")
392
393
print(f"Track: {track.get_title()}")
394
print(f"Album: {track.get_album().get_title()}")
395
print(f"Duration: {track.get_duration() / 1000:.1f} seconds")
396
397
# Love the track (requires authentication)
398
if network.session_key:
399
track.love()
400
print("Track loved!")
401
402
# Add tags
403
track.add_tags(("alternative rock", "90s", "progressive"))
404
print("Tags added!")
405
406
# Get similar tracks
407
similar_tracks = track.get_similar(limit=5)
408
for similar_track in similar_tracks:
409
print(f"Similar: {similar_track.item.get_artist().get_name()} - {similar_track.item.get_title()}")
410
```
411
412
### Working with Albums
413
414
```python
415
# Get album and its tracks
416
album = network.get_album("Pink Floyd", "The Dark Side of the Moon")
417
418
print(f"Album: {album.get_title()}")
419
print(f"Artist: {album.get_artist().get_name()}")
420
421
# Get track listing
422
tracks = album.get_tracks()
423
for i, track in enumerate(tracks, 1):
424
duration = track.get_duration()
425
duration_str = f"{duration // 60000}:{(duration % 60000) // 1000:02d}" if duration else "Unknown"
426
print(f"{i:2d}. {track.get_title()} ({duration_str})")
427
428
# Get album artwork
429
cover_url = album.get_cover_image(size=pylast.SIZE_LARGE)
430
print(f"Cover art: {cover_url}")
431
```
432
433
### Batch Operations
434
435
```python
436
# Work with multiple artists
437
artist_names = ["The Beatles", "Led Zeppelin", "Pink Floyd", "The Rolling Stones"]
438
artists = [network.get_artist(name) for name in artist_names]
439
440
# Get statistics for all artists
441
for artist in artists:
442
stats = {
443
'name': artist.get_name(),
444
'listeners': artist.get_listener_count(),
445
'playcount': artist.get_playcount()
446
}
447
print(f"{stats['name']}: {stats['listeners']:,} listeners, {stats['playcount']:,} plays")
448
```