🎵 Last.fm README GitHub Action

Dynamically update your GitHub README.md with Last.fm metrics.

🚀 Quick Start

Tip

New to GitHub Actions? Check out the GitHub Actions documentation to get started.

🔧 Setup

🎵 Last.fm API Key

1. Create a Last.fm API account: Visit Last.fm API
2. Get your API key: You'll receive an API key immediately after account creation
3. 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.

🔒 Configure Repository Secrets

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 scope Only needed for cross-repository updates	⚠️ Conditional

⚙️ Configure Workflow Permissions

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 Section Markers to Your README

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 Your Workflow

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.

⚙️ Configuration

📥 Input Parameters

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

📊 Available Sections

Note

Each section is defined by HTML comment markers with optional JSON configuration for customization.

🎯 Basic Usage

<!-- Default configuration -->
<!--START_LASTFM_ARTISTS-->
<!--END_LASTFM_ARTISTS-->

🛠️ Advanced Configuration

<!-- 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-->

---

🎤 Top Artists

Display the top listened to albums over a given period of time.

🖼️ Preview

💻 Usage Examples

<!-- 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-->

⚙️ Configuration Options

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

💿 Top Albums

Display the top listened to albums over a given period of time.

🖼️ Preview

💻 Usage Examples

<!-- 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-->

⚙️ Configuration Options

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

🎵 Top Tracks

Display the top listened to tracks over a given period of time.

🖼️ Preview

💻 Usage Examples

<!-- 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-->

⚙️ Configuration Options

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

🔊 Recent Tracks

Display most recently played music with real-time "now playing" status.

🖼️ Preview

Default

Track currently playing

💻 Usage Examples

<!-- Default: Last 8 tracks -->
<!--START_LASTFM_RECENT-->
<!--END_LASTFM_RECENT-->

<!-- Custom: Last 5 tracks -->
<!--START_LASTFM_RECENT:{"rows": 5}-->
<!--END_LASTFM_RECENT-->

⚙️ Configuration Options

Option	Type	Default	Options	Description
rows	number	8	1-50	Number of recent tracks to display

ℹ️ User Statistics

Showcase your Last.fm profile statistics and listening milestones.

🖼️ Preview

Default

Custom Configuration

💻 Usage Examples

<!-- 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-->

⚙️ Configuration Options

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

🌟 Acknowledgements

This project was inspired by and builds upon the excellent work of:

• JasonEtco/rss-to-readme
• vnphanquang/monkeytype-readme
• athul/waka-readme
• actions-js/profile-readme