🎵 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:

⚙️ 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/[email protected]
        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

| 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

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

• 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

💿 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

🎵 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

🔊 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

ℹ️ 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

| 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