Tip
New to GitHub Actions? Check out the GitHub Actions documentation to get started.
- Create a Last.fm API account: Visit Last.fm API
- Get your API key: You'll receive an API key immediately after account creation
- Save your API key: You'll need this for the next step
Warning
Keep your API key secure and never commit it directly to your repository.
Step 1: Navigate to your repository's secrets:
Your Repository → Settings → Secrets and variables → Actions → New repository secret
Step 2: Add the required secrets:
| Secret Name | Description | Required |
|---|---|---|
LASTFM_API_KEY |
Your Last.fm API key from the previous step | ✅ Yes |
GH_TOKEN |
GitHub Personal Access Token with repo scopeOnly needed for cross-repository updates |
Important
This step is crucial for the action to update your README file.
Path: Settings → Actions → General → Workflow permissions
Setting: Select "Read and write permissions"
Add HTML comments to your README.md where you want your Last.fm data to appear:
<!-- Add this where you want your music stats -->
<!--START_LASTFM_ARTISTS-->
<!--END_LASTFM_ARTISTS-->
<!--START_LASTFM_RECENT-->
<!--END_LASTFM_RECENT-->Create .github/workflows/lastfm.yml in your repository:
name: 🎵 Update Last.fm Stats
on:
# Run automatically every 6 hours
schedule:
- cron: '0 */6 * * *'
# Allow manual runs
workflow_dispatch:
jobs:
update-lastfm:
name: 🎤 Update Music Stats
runs-on: ubuntu-latest
steps:
- name: 🎵 Update Last.fm README
uses: dxnter/lastfm-readme@v1
with:
LASTFM_API_KEY: ${{ secrets.LASTFM_API_KEY }}
LASTFM_USER: your-lastfm-username
# Optional: Customize the commit message
COMMIT_MESSAGE: '🎵 Update music stats'
# Optional: For cross-repository updates
# GH_TOKEN: ${{ secrets.GH_TOKEN }}
# REPOSITORY: username/repository
# Optional: Target a different file
# TARGET_FILE: profile/README.md⏰ Scheduling Examples
| Frequency | Cron Expression |
|---|---|
| Every hour | 0 * * * * |
| Every 6 hours | 0 */6 * * * |
| Daily at midnight | 0 0 * * * |
| Weekly | 0 0 * * 0 |
For different scheduling needs, refer to the crontab.guru website.
| Parameter | Required | Default | Description |
|---|---|---|---|
LASTFM_API_KEY |
✅ Yes | — | Your Last.fm API key |
LASTFM_USER |
✅ Yes | — | Last.fm username to fetch data for |
GH_TOKEN |
🔶 Optional | ${{ github.token }} |
GitHub token for cross-repo updates |
REPOSITORY |
🔶 Optional | Current repository | Target repository (owner/repo) |
TARGET_FILE |
🔶 Optional | README.md |
Path to the file to update |
COMMIT_MESSAGE |
🔶 Optional | chore: update Last.fm sections |
Custom commit message |
SHOW_TITLE |
🔶 Optional | true |
Show section titles with Last.fm logo |
LOCALE |
🔶 Optional | en-US |
BCP 47 locale for number formatting |
DATE_FORMAT |
🔶 Optional | MM/dd/yyyy |
date-fns format for dates |
Note
Each section is defined by HTML comment markers with optional JSON configuration for customization.
<!-- Default configuration -->
<!--START_LASTFM_ARTISTS-->
<!--END_LASTFM_ARTISTS--><!-- Custom configuration with JSON -->
<!--START_LASTFM_ARTISTS:{"period": "overall", "rows": 3}-->
<!--END_LASTFM_ARTISTS-->💡 Configuration Tips
- JSON must be valid: Use double quotes for keys and string values
- No spaces: Keep the configuration compact
- Multiple sections: You can use the same section type multiple times with different configs
Example of multiple artist sections:
<!-- This week's top artists -->
<!--START_LASTFM_ARTISTS:{"period": "7day", "rows": 5}-->
<!--END_LASTFM_ARTISTS-->
<!-- All-time favorites -->
<!--START_LASTFM_ARTISTS:{"period": "overall", "rows": 3}-->
<!--END_LASTFM_ARTISTS-->Display the top listened to albums over a given period of time.
<!-- Default: Top 8 artists from the past week -->
<!--START_LASTFM_ARTISTS-->
<!--END_LASTFM_ARTISTS-->
<!-- Custom: Top 5 artists from the past 6 months -->
<!--START_LASTFM_ARTISTS:{"period": "6month", "rows": 5}-->
<!--END_LASTFM_ARTISTS-->
<!-- All-time favorites -->
<!--START_LASTFM_ARTISTS:{"period": "overall", "rows": 10}-->
<!--END_LASTFM_ARTISTS-->| Option | Type | Default | Options | Description |
|---|---|---|---|---|
period |
string | 7day |
7day, 1month, 3month, 6month, 12month, overall |
Time period for data aggregation |
rows |
number | 8 |
1-50 |
Number of artists to display |
Display the top listened to albums over a given period of time.
<!-- This month's top albums -->
<!--START_LASTFM_ALBUMS:{"period": "1month", "rows": 5}-->
<!--END_LASTFM_ALBUMS-->
<!-- All-time classic albums -->
<!--START_LASTFM_ALBUMS:{"period": "overall", "rows": 3}-->
<!--END_LASTFM_ALBUMS-->| Option | Type | Default | Options | Description |
|---|---|---|---|---|
period |
string | 7day |
7day, 1month, 3month, 6month, 12month, overall |
Time period for data aggregation |
rows |
number | 8 |
1-50 |
Number of albums to display |
Display the top listened to tracks over a given period of time.
<!-- This month's most played songs -->
<!--START_LASTFM_TRACKS:{"period": "1month", "rows": 5}-->
<!--END_LASTFM_TRACKS-->
<!-- Your all-time favorites -->
<!--START_LASTFM_TRACKS:{"period": "overall", "rows": 10}-->
<!--END_LASTFM_TRACKS-->| Option | Type | Default | Options | Description |
|---|---|---|---|---|
period |
string | 7day |
7day, 1month, 3month, 6month, 12month, overall |
Time period for data aggregation |
rows |
number | 8 |
1-50 |
Number of tracks to display |
Display most recently played music with real-time "now playing" status.
Default
Track currently playing
<!-- Default: Last 8 tracks -->
<!--START_LASTFM_RECENT-->
<!--END_LASTFM_RECENT-->
<!-- Custom: Last 5 tracks -->
<!--START_LASTFM_RECENT:{"rows": 5}-->
<!--END_LASTFM_RECENT-->| Option | Type | Default | Options | Description |
|---|---|---|---|---|
rows |
number | 8 |
1-50 |
Number of recent tracks to display |
Showcase your Last.fm profile statistics and listening milestones.
Default
Custom Configuration
<!-- Default: Show all available statistics -->
<!--START_LASTFM_USER_INFO-->
<!--END_LASTFM_USER_INFO-->
<!-- Custom: Only show play count and artist count -->
<!--START_LASTFM_USER_INFO:{"display": ["playcount", "artistCount"]}-->
<!--END_LASTFM_USER_INFO-->
<!-- Minimal: Just registration date -->
<!--START_LASTFM_USER_INFO:{"display": ["registered"]}-->
<!--END_LASTFM_USER_INFO-->| Option | Type | Default | Available Options | Description |
|---|---|---|---|---|
display |
array | All fields | registered, playcount, artistCount, albumCount, trackCount |
List of statistics to display |
📊 Available Statistics Fields
| Field | Description | Example Output |
|---|---|---|
registered |
Account registration date | Registered: 12/25/2015 |
playcount |
Total scrobbled tracks | Playcount: 50,247 |
artistCount |
Unique artists listened to | Artists: 2,847 |
albumCount |
Unique albums in library | Albums: 8,429 |
trackCount |
Unique tracks in library | Tracks: 45,821 |
This project was inspired by and builds upon the excellent work of:
Resources
Last.fm - Readme is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.
Resources
Last.fm - Readme is not certified by GitHub. It is provided by a third-party and is governed by separate terms of service, privacy policy, and support documentation.