Requirements
- Target platform
- OpenClaw
- Install method
- Manual import
- Extraction
- Extract archive
- Prerequisites
- OpenClaw
- Primary doc
- SKILL.md
Tencent SkillHub ยท Developer Tools
statsfm
Music data tool powered by the stats.fm API. Look up album tracklists, artist discographies, and global charts. With a stats.fm username, also query personal...
skill openclawclawhub Free
Music data tool powered by the stats.fm API. Look up album tracklists, artist discographies, and global charts. With a stats.fm username, also query personal...
โฌ 0 downloads โ
0 stars Unverified but indexed
Install for OpenClaw
Quick setup
- Download the package from Yavira.
- Extract the archive and review SKILL.md first.
- Import or place the package into your OpenClaw setup.
Package facts
- Download mode
- Yavira redirect
- Package format
- ZIP package
- Source platform
- Tencent SkillHub
- What's included
- SKILL.md, scripts/statsfm.py, references/api.md
Validation
- Use the Yavira download entry.
- Review SKILL.md after the package is downloaded.
- Confirm the extracted package contains the expected setup assets.
Install with your agent
Agent handoff
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
New install
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
Upgrade existing
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
Trust & source
Release facts
- Source
- Tencent SkillHub
- Verification
- Indexed source record
- Version
- 2.5.2
Provenance
- Publisher
- space0mel
- Source page
- View original listing
- Canonical URL
- Open canonical page
Documentation
stats.fm CLI
Comprehensive Python CLI for querying stats.fm API (Spotify listening analytics). Requirements: Python 3.6+ (stdlib only, no pip installs needed) Script location: scripts/statsfm.py in this skill's directory. Examples use ./statsfm.py assuming you're in the scripts folder.
Prerequisites
Stats.fm account (optional) A stats.fm account is only needed for personal listening data (history, top tracks, now playing, etc.) Without an account, you can still use public features: album tracklists, artist discographies, search, and global charts Don't have one? Visit stats.fm and sign up with Spotify or Apple Music (AM untested, Plus status unknown) Already have one? Copy your username from your profile
Setup
No account needed for public commands: search, album, artist-albums, charts-top-tracks, charts-top-artists, charts-top-albums. For personal stats (profile, top-artists, top-tracks, recent, np, etc.), pass your username with --user USERNAME / -u USERNAME. These commands exit with code 1 if no user is provided.
Quick Start
# View your profile ./statsfm.py profile # Top tracks this month ./statsfm.py top-tracks --limit 10 # Track stats for 2025 ./statsfm.py track-stats 188745898 --start 2025 --end 2026
User Profile
profile - Show username, pronouns, bio, Plus status, timezone, Spotify sync info
Top Lists
top-tracks - Your most played tracks top-artists - Your most played artists top-albums - Your most played albums top-genres - Your top music genres
Current Activity
now-playing (aliases: now, np) - Currently playing track recent - Recently played tracks
Detailed Stats
artist-stats <artist_id> - Your play count, listening time, and monthly breakdown for this artist track-stats <track_id> - Your play count, listening time, and monthly breakdown for this track (shows track name + album) album-stats <album_id> - Your play count, listening time, and monthly breakdown for this album stream-stats - Your overall streaming summary (total streams, total time, avg track length, shortest/longest, unique counts for tracks/artists/albums)
Lookups
artist <artist_id> - Artist info and discography. Shows genres, followers, popularity score (100 = very popular, 50 = underground, 0 = no data). --type album|single|all (default: all) --limit N - Items per section (default: 15) album <album_id> - Album info and full tracklist (release date, label, genres, tracks with duration and [E] tags) artist-albums <artist_id> - All albums/singles by artist, grouped by type (Albums, Singles & EPs, Compilations), newest first. Deduped by ID, 15 per section by default, shows "(N more)" overflow. --type album|single|all (default: all) --limit N - Items per section
Drill-Down
top-tracks-from-artist <artist_id> - Your most played tracks from this artist top-tracks-from-album <album_id> - Your most played tracks from this album top-albums-from-artist <artist_id> - Your most played albums from this artist
Global Charts
charts-top-tracks - Global top tracks chart charts-top-artists - Global top artists chart charts-top-albums - Global top albums chart
Search
search <query> - Search for artists, tracks, or albums. Use --type artist|track|album to filter results to one category
Date Ranges
All stats commands support both predefined ranges and custom dates: Predefined ranges: --range today or --range 1d - Today only --range 4w - Last 4 weeks (default) --range 6m - Last 6 months --range all - All time (lifetime) Duration ranges (resolved to custom timestamps): --range 7d - Last 7 days --range 14d - Last 14 days --range 30d - Last 30 days --range 90d - Last 90 days Custom date ranges: --start YYYY - Start year (e.g., --start 2025) --start YYYY-MM - Start month (e.g., --start 2025-07) --start YYYY-MM-DD - Start date (e.g., --start 2025-07-15) --end YYYY[-MM[-DD]] - End date (same formats) Examples: # All of 2025 ./statsfm.py top-artists --start 2025 --end 2026 # Just July 2025 ./statsfm.py top-tracks --start 2025-07 --end 2025-08 # Q1 2025 ./statsfm.py artist-stats 39118 --start 2025-01-01 --end 2025-03-31
Granularity
--granularity monthly - Monthly breakdown (default) --granularity weekly - Weekly breakdown (shows week number + start date) --granularity daily - Daily breakdown (shows date + day name) Works with artist-stats, track-stats, album-stats
Other Flags
--limit N / -l N - Limit results (default: 15) --user USERNAME / -u USERNAME - Specify the stats.fm username to query --no-album - Hide album names in track listings (albums show by default)
Usage Examples
# Search for an artist, then drill down ./statsfm.py search "madison beer" --type artist ./statsfm.py artist-stats 39118 --start 2025 ./statsfm.py top-tracks-from-artist 39118 --limit 20 # Weekly breakdown of a track ./statsfm.py track-stats 188745898 --start 2025 --end 2026 --granularity weekly # Custom date range ./statsfm.py top-artists --start 2025-06 --end 2025-09 # Album tracklist and discography ./statsfm.py album 1365235 ./statsfm.py artist-albums 39118 --type album # Global charts ./statsfm.py charts-top-tracks --limit 20
Automatic Monthly Breakdowns
Stats commands (artist-stats, track-stats, album-stats) automatically show: Total plays and listening time Monthly breakdown with plays and time per month Works for both predefined ranges and custom date ranges Example output: Total: 505 plays (29h 53m) Monthly breakdown: 2025-02: 67 plays (3h 52m) 2025-03: 106 plays (6h 21m) 2025-04: 40 plays (2h 24m) ...
Display Information
Track listings: Show position, track name, artist, album (by default), play count, time Album listings: Show position, album name, artist, play count, time Artist listings: Show position, artist name, play count, time, genres Charts: Show global rankings with stream counts Recent streams: Show timestamp, track, artist, album (by default)
Plus vs Free Users
Stats.fm Plus required for: Stream counts in top lists Listening time (play duration) Detailed statistics Free users get: Rankings/positions Track/artist/album names Currently playing Search functionality Monthly breakdowns (via per-day stats endpoint) The script handles both gracefully, showing [Plus required] for missing data.
API Information
Base URL: https://api.stats.fm/api/v1 Authentication: None needed for public profiles Response format: JSON with item (single) or items (list) wrapper Rate limiting: Be reasonable with requests. Avoid more than ~10 calls in rapid succession during deep dives.
Error Handling
All errors print to stderr and exit with code 1. Scenariostderr outputWhat to doNo user setError: No user specified.Pass --user USERNAME flagAPI error (4xx/5xx)API Error (code): messageCheck if user exists, profile is public, or ID is validConnection failureConnection Error: reasonRetry after a moment, check networkEmpty resultsNo error, just no outputUser may be private, or no data for that period โ try --range allPlus-only dataShows [Plus required] inlineAcknowledge gracefully, show what's available
Finding IDs
Use search to find artist/track/album IDs: # Find artist ./statsfm.py search "sabrina carpenter" --type artist # Returns: [22369] Sabrina Carpenter [pop] # Find track ./statsfm.py search "espresso" --type track # Returns: [188745898] Espresso by Sabrina Carpenter # Find album ./statsfm.py search "short n sweet" --type album # Returns: [56735245] Short n' Sweet by Sabrina Carpenter Then use the ID numbers in other commands.
Tips
Use custom dates for analysis: --start 2025 --end 2026 to see full year stats Chain discoveries: Search โ Get ID โ Detailed stats โ Drill down Compare periods: Run same command with different date ranges Export data: Pipe output to file for records: ./statsfm.py top-tracks --start 2025 > 2025_top_tracks.txt Albums show by default: Match the stats.fm UI behavior (album art is prominent) Monthly breakdowns: All stats commands show month-by-month progression automatically
For AI Agents
Setup: Check memory for a stats.fm username. If missing, ask. All personal data commands need --user USERNAME. Multiple time ranges: Always compare multiple ranges (--range today, 7d, 30d, 90d, all) to show how taste shifts over time. Lifetime stats alone miss current trends.
Time Translations
"This year" โ --start 2025 --end 2026 "Last summer" โ --start 2025-06 --end 2025-09 "When did I discover X" โ artist-stats <id> --range all (first month in breakdown)
Command Reference
IntentCommandKey flagsYour plays of a tracktrack-stats <id>--start/--end, --granularityYour plays of an artistartist-stats <id>--start/--end, --granularityYour plays of an albumalbum-stats <id>--start/--end, --granularityYour overall statsstream-stats--range, --start/--endYour rankingstop-tracks, top-artists, top-albums, top-genres--range, --start/--end, --limitCurrently playingnow-playingRecent tracksrecent--limitArtist overviewartist <id>--limitArtist's discographyartist-albums <id>--limitAlbum tracklistalbum <id>Your top tracks by artisttop-tracks-from-artist <id>--range, --limitYour top tracks on albumtop-tracks-from-album <id>--range, --limitYour top albums by artisttop-albums-from-artist <id>--range, --limitGlobal chartscharts-top-tracks, charts-top-artists, charts-top-albums--range, --limitFind IDssearch <query>--type artist|track|album
Edge Cases
Free users: Play counts are not available for top tracks โ rankings and breakdowns still work, lead with those Empty results: Try --range all as fallback. Could also be a private profile. Search duplicates: Use the first result Apple Music: Untested, may have gaps
References
Github Repo: statsfm/statsfm-cli API Endpoints: references/api.md Official JS Client: statsfm/statsfm.js
Category context
Code helpers, APIs, CLIs, browser automation, testing, and developer operations.
Source: Tencent SkillHub
Largest current source with strong distribution and engagement signals.
Package contents
Included in package
2 Docs1 Scripts
- SKILL.md
- references/api.md
- scripts/statsfm.py