Building a Dynamic Music Section with Last.fm and Multi-Source Artist Data
Tech Stack: Next.js, TypeScript, Last.fm API, MusicBrainz API, Spotify API, Vercel KV
Building a Dynamic Music Section with Last.fm and Multi-Source Artist Data
When building my personal website, I wanted to showcase my music listening habits in a dynamic, visually appealing way. What started as a simple Last.fm integration evolved into a comprehensive system that pulls data from multiple sources to create a rich music experience. This journey taught me valuable lessons about API orchestration, intelligent caching, and creating resilient fallback systems.
1. The Vision: Beyond Basic Scrobble Display
Most Last.fm integrations simply display recent tracks or top artists. I wanted something more comprehensive:
- Real-time Updates: Show what I'm currently listening to
- Rich Artist Information: Display artist images, genres, and biography snippets
- Album Artwork: Show album covers for recent tracks
- Multiple Time Ranges: Weekly, monthly, and all-time statistics
- Performance: Fast loading with intelligent caching
- Resilience: Graceful degradation when APIs are unavailable
The challenge was that Last.fm's API, while excellent for listening data, has limitations for media assets. This led me to create a multi-source integration system.
2. Architecture Overview
The music section consists of several interconnected components:
System architecture overview for music integration
// Core architecture
- Last.fm API: Primary source for listening data
- MusicBrainz: Artist metadata and identifiers
- Spotify API: High-quality artist images
- Wikipedia: Artist biographies and additional images
- Vercel KV: Redis-based caching layer
- Image Manager: Centralized image handling with fallbacks
This multi-layered approach ensures that even if one service is down, the music section continues to function with graceful degradation.
3. Last.fm Integration: The Foundation
Last.fm provides the core listening data through their REST API:
Last.fm API service class for music data integration
/**
* Last.fm Service
*
* Handles all interactions with the Last.fm API including
* recent tracks, top artists, and user statistics
*/
export class LastFmService {
private readonly apiKey: string;
private readonly username: string;
private readonly baseUrl = 'https://ws.audioscrobbler.com/2.0/';
constructor() {
this.apiKey = process.env.LASTFM_API_KEY!;
this.username = process.env.LASTFM_USERNAME!;
}
async getRecentTracks(limit: number = 10): Promise<Track[]> {
const params = new URLSearchParams({
method: 'user.getrecenttracks',
user: this.username,
api_key: this.apiKey,
format: 'json',
limit: limit.toString(),
extended: '1' // Include artist info
});
const response = await fetch(this.baseUrl + '?' + params);
const data = await response.json();
return this.formatTracks(data.recenttracks.track);
}
async getTopArtists(period: TimePeriod = '1month'): Promise<Artist[]> {
const params = new URLSearchParams({
method: 'user.gettopartists',
user: this.username,
api_key: this.apiKey,
format: 'json',
period,
limit: '12'
});
const response = await fetch(this.baseUrl + '?' + params);
const data = await response.json();
return this.formatArtists(data.topartists.artist);
}
}
Handling Real-time "Now Playing" Status
One unique aspect of Last.fm is the "now playing" attribute for currently playing tracks:
Track data formatting with 'now playing' status detection
private formatTracks(tracks: any[]): Track[] {
return tracks.map(track => ({
name: track.name,
artist: track.artist.name,
album: track.album['#text'],
url: track.url,
image: this.getLargestImage(track.image),
date: track.date ? new Date(track.date.uts * 1000) : undefined,
nowPlaying: track['@attr']?.nowplaying === 'true'
}));
}
4. Multi-Source Artist Data Enrichment
Last.fm provides basic artist information, but for a rich visual experience, I needed more. This led to implementing a multi-source data enrichment system:
Multi-source data enrichment pipeline for artist information
/**
* Artist Data Enrichment Pipeline
*
* Attempts to fetch artist data from multiple sources
* with intelligent fallback mechanisms
*/
export class ArtistDataService {
async enrichArtistData(artist: BasicArtist): Promise<EnrichedArtist> {
// Start with Last.fm data
let enrichedData = { ...artist };
// Try MusicBrainz for metadata
try {
const mbData = await this.fetchMusicBrainzData(artist.name);
if (mbData) {
enrichedData.mbid = mbData.id;
enrichedData.genres = mbData.genres;
}
} catch (error) {
console.log('MusicBrainz lookup failed for ' + artist.name);
}
// Try Spotify for high-quality images
try {
const spotifyData = await this.fetchSpotifyData(artist.name);
if (spotifyData?.images?.[0]) {
enrichedData.image = spotifyData.images[0].url;
enrichedData.spotifyId = spotifyData.id;
}
} catch (error) {
console.log('Spotify lookup failed for ' + artist.name);
}
// Fallback to Wikipedia for images
if (!enrichedData.image) {
try {
const wikiImage = await this.fetchWikipediaImage(artist.name);
if (wikiImage) {
enrichedData.image = wikiImage;
}
} catch (error) {
console.log('Wikipedia lookup failed for ' + artist.name);
}
}
return enrichedData;
}
}
5. Intelligent Caching with Vercel KV
To avoid hitting rate limits and improve performance, I implemented a multi-tier caching strategy using Vercel KV (Redis):
Redis caching strategy for music data with different TTL values
/**
* Caching Strategy
*
* Different TTLs for different data types based on update frequency
*/
export class MusicCacheService {
private readonly kv = createClient({
url: process.env.KV_REST_API_URL,
token: process.env.KV_REST_API_TOKEN,
});
// Cache durations
private readonly TTL = {
RECENT_TRACKS: 60, // 1 minute (near real-time)
TOP_ARTISTS: 3600, // 1 hour
ARTIST_DATA: 604800, // 1 week
ALBUM_ART: 2592000, // 30 days
};
async getRecentTracks(): Promise<Track[]> {
const cached = await this.kv.get('lastfm:recent-tracks');
if (cached) {
return JSON.parse(cached);
}
// Fetch fresh data
const tracks = await lastFmService.getRecentTracks();
// Cache with short TTL for near real-time updates
await this.kv.setex(
'lastfm:recent-tracks',
this.TTL.RECENT_TRACKS,
JSON.stringify(tracks)
);
return tracks;
}
async getArtistData(artistName: string): Promise<EnrichedArtist> {
const cacheKey = 'artist:' + this.sanitizeKey(artistName);
const cached = await this.kv.get(cacheKey);
if (cached) {
return JSON.parse(cached);
}
// Fetch and enrich data
const artistData = await artistDataService.enrichArtistData({ name: artistName });
// Cache for longer period
await this.kv.setex(
cacheKey,
this.TTL.ARTIST_DATA,
JSON.stringify(artistData)
);
return artistData;
}
}
Cache Warming Strategy
To ensure smooth user experience, I implemented cache warming for frequently accessed data:
Cache warming strategy for music data with cron job implementation
// Cron job that runs every hour
export async function warmMusicCache() {
// Pre-fetch top artists for all time periods
const periods: TimePeriod[] = ['7day', '1month', '12month', 'overall'];
for (const period of periods) {
const artists = await lastFmService.getTopArtists(period);
// Enrich artist data in parallel
await Promise.all(
artists.map(artist =>
musicCacheService.getArtistData(artist.name)
)
);
}
}
6. Image Management System
One of the biggest challenges was handling artist images reliably. I created a centralized image management system:
/**
* Artist Image Manager
*
* Handles image fetching, caching, and fallback logic
*/
export class ArtistImageManager {
private readonly sources = [
{ name: 'spotify', fetch: this.fetchSpotifyImage },
{ name: 'lastfm', fetch: this.fetchLastFmImage },
{ name: 'musicbrainz', fetch: this.fetchMusicBrainzImage },
{ name: 'wikipedia', fetch: this.fetchWikipediaImage }
];
async getArtistImage(artistName: string): Promise<string> {
// Check cache first
const cached = await this.getCachedImage(artistName);
if (cached) return cached;
// Try each source in order
for (const source of this.sources) {
try {
const imageUrl = await source.fetch(artistName);
if (imageUrl && await this.validateImage(imageUrl)) {
await this.cacheImage(artistName, imageUrl, source.name);
return imageUrl;
}
} catch (error) {
console.log(source.name + ' image fetch failed for ' + artistName);
}
}
// Return placeholder if all sources fail
return '/placeholder-artist.svg';
}
private async validateImage(url: string): Promise<boolean> {
try {
const response = await fetch(url, { method: 'HEAD' });
const contentType = response.headers.get('content-type');
return response.ok && contentType?.startsWith('image/');
} catch {
return false;
}
}
}
Handling Edge Cases
The image system handles several edge cases:
Edge case handling for artist names and image URL normalization
// Handle artists with special characters
private sanitizeArtistName(name: string): string {
return name
.toLowerCase()
.replace(/[^\w\s-]/g, '') // Remove special characters
.replace(/\s+/g, '-'); // Replace spaces with hyphens
}
// Handle different image formats from various APIs
private normalizeImageUrl(url: string, source: string): string {
switch (source) {
case 'spotify':
// Spotify provides multiple sizes, get the largest
return url.replace(/\/\d+x\d+\//, '/640x640/');
case 'lastfm':
// Last.fm uses size indicators
return url.replace(/\/\d+s\//, '/300s/');
default:
return url;
}
}
7. Building the UI Components
With the data layer solid, I created React components that showcase the music data:
Top Artists Component
React component for displaying top artists with animated grid layout
'use client';
export function TopArtists({ period = '1month' }: { period?: TimePeriod }) {
const [artists, setArtists] = useState<EnrichedArtist[]>([]);
const [loading, setLoading] = useState(true);
const [imageLoadStates, setImageLoadStates] = useState<Record<string, boolean>>({});
useEffect(() => {
const fetchArtists = async () => {
try {
const response = await fetch('/api/lastfm/top-artists?period=' + period);
const data = await response.json();
setArtists(data);
} catch (error) {
console.error('Failed to fetch artists:', error);
} finally {
setLoading(false);
}
};
fetchArtists();
}, [period]);
if (loading) {
return <ArtistGridSkeleton />;
}
return (
<div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-6 gap-4">
{artists.map((artist, index) => (
<motion.div
key={artist.name}
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ delay: index * 0.05 }}
className="group cursor-pointer"
>
<div className="relative aspect-square mb-2 overflow-hidden rounded-lg bg-muted">
<Image
src={artist.image || '/placeholder-artist.svg'}
alt={artist.name}
fill
className={cn(
"object-cover transition-all duration-300",
"group-hover:scale-110",
imageLoadStates[artist.name] ? "opacity-100" : "opacity-0"
)}
onLoad={() => setImageLoadStates(prev => ({ ...prev, [artist.name]: true }))}
sizes="(max-width: 640px) 50vw, (max-width: 768px) 33vw, (max-width: 1024px) 25vw, 16.66vw"
/>
{/* Loading skeleton */}
{!imageLoadStates[artist.name] && (
<div className="absolute inset-0 animate-pulse bg-gradient-to-br from-muted to-muted-foreground/10" />
)}
{/* Play count overlay */}
<div className="absolute bottom-0 left-0 right-0 bg-gradient-to-t from-black/70 to-transparent p-2">
<p className="text-xs text-white/90">
{artist.playcount} plays
</p>
</div>
</div>
<h3 className="font-medium text-sm truncate group-hover:text-primary transition-colors">
{artist.name}
</h3>
</motion.div>
))}
</div>
);
}
Recent Tracks with "Now Playing" Indicator
Recent tracks component with real-time now playing status and polling
export function RecentTracks() {
const [tracks, setTracks] = useState<Track[]>([]);
const [isLive, setIsLive] = useState(false);
useEffect(() => {
const fetchTracks = async () => {
const response = await fetch('/api/lastfm/recent-tracks');
const data = await response.json();
setTracks(data);
// Check if currently playing
setIsLive(data[0]?.nowPlaying === true);
};
// Initial fetch
fetchTracks();
// Poll more frequently if currently playing
const interval = setInterval(fetchTracks, isLive ? 30000 : 60000);
return () => clearInterval(interval);
}, [isLive]);
return (
<div className="space-y-3">
{tracks.map((track, index) => (
<div
key={track.name + '-' + track.date}
className={cn(
"flex items-center gap-3 p-3 rounded-lg transition-all",
track.nowPlaying && "bg-primary/5 border border-primary/20"
)}
>
{/* Album artwork */}
<div className="relative w-12 h-12 flex-shrink-0">
<Image
src={track.image || '/placeholder.svg'}
alt={track.album + ' cover'}
fill
className="object-cover rounded"
/>
{/* Now playing indicator */}
{track.nowPlaying && (
<div className="absolute -top-1 -right-1">
<NowPlayingIndicator />
</div>
)}
</div>
{/* Track info */}
<div className="flex-1 min-w-0">
<p className="font-medium truncate">{track.name}</p>
<p className="text-sm text-muted-foreground truncate">
{track.artist} • {track.album}
</p>
</div>
{/* Timestamp */}
<div className="text-xs text-muted-foreground">
{track.nowPlaying ? (
<span className="text-primary font-medium">Now Playing</span>
) : (
<TimeAgo date={track.date} />
)}
</div>
</div>
))}
</div>
);
}
8. API Route Handlers
The API routes orchestrate data fetching and caching:
// app/api/lastfm/top-artists/route.ts
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const period = searchParams.get('period') as TimePeriod || '1month';
try {
// Try cache first
const cacheKey = 'top-artists:' + period;
const cached = await kv.get(cacheKey);
if (cached) {
return NextResponse.json(JSON.parse(cached));
}
// Fetch from Last.fm
const artists = await lastFmService.getTopArtists(period);
// Enrich with additional data
const enrichedArtists = await Promise.all(
artists.map(async (artist) => {
const enriched = await artistDataService.enrichArtistData(artist);
// Ensure we have an image
enriched.image = enriched.image || await artistImageManager.getArtistImage(artist.name);
return enriched;
})
);
// Cache the result
await kv.setex(cacheKey, 3600, JSON.stringify(enrichedArtists));
return NextResponse.json(enrichedArtists);
} catch (error) {
console.error('Error fetching top artists:', error);
// Try to return stale cache if available
const staleCache = await kv.get(cacheKey + ':stale');
if (staleCache) {
return NextResponse.json(JSON.parse(staleCache));
}
return NextResponse.json({ error: 'Failed to fetch artists' }, { status: 500 });
}
}
9. Handling API Failures Gracefully
A critical aspect of the system is graceful degradation when APIs fail:
/**
* Fallback System
*
* Ensures the music section always displays something meaningful
*/
export class MusicFallbackService {
async getTopArtistsWithFallback(period: TimePeriod): Promise<Artist[]> {
try {
// Try primary source
return await lastFmService.getTopArtists(period);
} catch (error) {
console.error('Last.fm API failed:', error);
// Try cache
const cached = await this.getCachedArtists(period);
if (cached) return cached;
// Last resort: return static fallback data
return this.getStaticFallbackArtists();
}
}
private async getStaticFallbackArtists(): Promise<Artist[]> {
// Return a predefined list of artists with local assets
return [
{
name: "Favorite Artist 1",
playcount: "1000",
image: "/images/artists/fallback-1.jpg",
url: "#"
},
// ... more fallback artists
];
}
}
Client-Side Error Boundaries
React error boundaries ensure UI doesn't break:
export function MusicSection() {
return (
<ErrorBoundary
fallback={<MusicSectionFallback />}
onError={(error) => console.error('Music section error:', error)}
>
<Suspense fallback={<MusicSectionSkeleton />}>
<MusicContent />
</Suspense>
</ErrorBoundary>
);
}
10. Performance Optimizations
Several optimizations ensure the music section loads quickly:
Image Optimization
// Preload critical images
export function preloadArtistImages(artists: Artist[]) {
if (typeof window === 'undefined') return;
// Preload first 6 artists (above the fold)
artists.slice(0, 6).forEach(artist => {
if (artist.image) {
const link = document.createElement('link');
link.rel = 'preload';
link.as = 'image';
link.href = artist.image;
document.head.appendChild(link);
}
});
}
Progressive Enhancement
// Start with server-rendered content
export default async function HomePage() {
// Fetch initial data server-side
const topArtists = await musicCacheService.getTopArtists('1month');
const recentTracks = await musicCacheService.getRecentTracks();
return (
<>
{/* Server-rendered initial state */}
<TopArtistsServer initialData={topArtists} />
<RecentTracksServer initialData={recentTracks} />
{/* Client components enhance with interactivity */}
<MusicSectionClient
initialArtists={topArtists}
initialTracks={recentTracks}
/>
</>
);
}
Request Deduplication
// Prevent duplicate requests for the same data
const requestCache = new Map<string, Promise<any>>();
export async function deduplicatedFetch<T>(
key: string,
fetcher: () => Promise<T>
): Promise<T> {
if (requestCache.has(key)) {
return requestCache.get(key)!;
}
const promise = fetcher();
requestCache.set(key, promise);
try {
const result = await promise;
return result;
} finally {
// Clean up after request completes
setTimeout(() => requestCache.delete(key), 100);
}
}
11. Lessons Learned and Best Practices
Building this music integration taught me several valuable lessons:
API Orchestration
- Always have fallbacks: Every external API will fail eventually
- Cache aggressively: But with appropriate TTLs for different data types
- Batch requests: Combine multiple API calls when possible
- Rate limit proactively: Don't wait for 429 errors
Performance
- Server-side render: Initial data should come from the server
- Progressive enhancement: Add interactivity without breaking SSR
- Image optimization: Crucial for artist grids with many images
- Request deduplication: Prevent redundant API calls
User Experience
- Show stale data: Better than showing nothing
- Loading states: Keep users informed during data fetches
- Smooth transitions: Use animations to mask loading delays
- Real-time updates: Poll for now-playing status
Resilience
- Multiple data sources: Don't rely on a single API
- Graceful degradation: Each component should fail independently
- Error boundaries: Contain failures to prevent app-wide crashes
- Static fallbacks: Last resort when everything else fails
Conclusion
What started as a simple Last.fm widget evolved into a comprehensive music tracking system that showcases the power of modern web development. By combining multiple APIs, implementing intelligent caching, and focusing on resilience, I created a music section that's both feature-rich and reliable.
The key to success was treating each external dependency as potentially unreliable and building layers of fallbacks. This defensive programming approach ensures users always see something meaningful, even when APIs are down or rate limits are hit.
For developers building similar integrations, remember:
- Start simple with one data source, then layer in enhancements
- Cache everything, but with appropriate expiration times
- Build fallbacks from day one, not as an afterthought
- Monitor API usage to stay within rate limits
- Focus on perceived performance with optimistic UI updates
The result is a music section that not only displays my listening habits but does so reliably and performantly, creating an engaging experience for visitors while showcasing technical implementation skills.
For more information on the APIs used: