GitHub README Last.fm Metrics

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

⚡ Usage

Preparation

Last.fm API Key

Create a Last.fm API account if you don't have one to receive an API Key.

Save GitHub Action Secrets

Navigate to your repositories Settings → Secrets and variables → Actions → New repository secret to add the following secrets:

| Name | Value | | :--------------: | :-------------------------------------------------: | | LASTFM_API_KEY | A valid Last.fm API Key | | GH_TOKEN* | A GitHub Access Token with the repo scope granted |

* GH_TOKEN is only required when the intention is to modify a README.md file in a repository outside where the workflow is running.

Update the workflow permissions on your repository

Navigate to your repositories Settings → Actions → General → Workflow permissions and select the Read and write permissions option.

Add chart HTML comments to your README

The README.md file must contain HTML comments that identify where the charts should be inserted. Commonly, a profile repository is used to host the README.md file.

Note See the Charts section for configuration details.

Example Workflow

name: Last.fm Charts

on:
  workflow_dispatch: # Allow manual triggering of workflow
  schedule:
    # Run every 6 hours
    - cron: '0 */6 * * *'

jobs:
  lastfm-metrics:
    name: Update Last.fm Charts
    runs-on: ubuntu-latest
    steps:
      - uses: dxnter/lastfm-readme@v1
        with:
          LASTFM_API_KEY: ${{ secrets.LASTFM_API_KEY }}
          LASTFM_USER: dxnter
          # The following inputs below are only required when the intention is to modify a README.md file in a repository outside where the workflow is running
          #GH_TOKEN: ${{ secrets.GH_TOKEN }}
          #REPOSITORY: <gh_username/gh_username>

Inputs

| Setting | Default | Accepted Values | Description | | :--------------: | :------------------------------: | :---------------------------------------------------------------------------------: | :-------------------------------------------------------: | | LASTFM_API_KEY | N/A | Last.fm API Key | A valid Last.fm API Key | | LASTFM_USER | N/A | Last.fm username | The Last.fm user to fetch metrics from | | GH_TOKEN | ${{ github.token }} | GitHub access token | An access token with the repo scope granted. | | REPOSITORY | <gh_username>/<gh_username> | <gh_username>/<repo_name> | Repository that should have the README.md file updated. | | COMMIT_MESSAGE | chore: update Last.fm sections | Any string | Commit message used when sections are updated | | SHOW_TITLE | true | true / false | Toggle the title shown above sections | | LOCALE | en-US | BCP 47 tag | Locale used for formatting numbers | | DATE_FORMAT | MM/dd/yyyy | date-fns date format | Date format used in the User Info section |

📊 Charts

All charts are identified by HTML comments that contain a valid chart name and an optional JSON configuration object followed by a closing HTML comment.

Chart with the default configuration (period: "7day", rows: 8)
<!--START_LASTFM_...-->
<!--END_LASTFM_...-->

Chart with a custom configuration
<!--START_LASTFM_...:{"period": "overall", "rows": 3}-->
<!--END_LASTFM_...-->

🎤️ Top Artists

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

Example

<!--START_LASTFM_ARTISTS:{"period": "6month", "rows": 3}-->
<!--END_LASTFM_ARTISTS-->

Output

Configuration

| Option | Default | Options | Description | | :------: | :-----: | :--------------------------------------------------------: | :-------------------------------------: | | period | 7day | 7day, 1month, 3month, 6month, 12month, overall | The period of time to display data from | | rows | 8 | 1 ≤ integer ≤ 50 | The number of artists to display |

💿 Top Albums

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

Example

<!--START_LASTFM_ALBUMS:{"period": "1month", "rows": 3}-->
<!--END_LASTFM_ALBUMS-->

Output

Configuration

| Option | Default | Options | Description | | :------: | :-----: | :--------------------------------------------------------: | :-------------------------------------: | | period | 7day | 7day, 1month, 3month, 6month, 12month, overall | The period of time to display data from | | rows | 8 | 1 ≤ integer ≤ 50 | The number of albums to display |

🎵 Top Tracks

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

Example

<!--START_LASTFM_TRACKS:{"period": "1month", "rows": 3}-->
<!--END_LASTFM_TRACKS-->

Output

Configuration

| Option | Default | Options | Description | | :------: | :-----: | :--------------------------------------------------------: | :-------------------------------------: | | period | 7day | 7day, 1month, 3month, 6month, 12month, overall | The period of time to display data from | | rows | 8 | 1 ≤ integer ≤ 50 | The number of tracks to display |

🔊 Recent Tracks

Display recently listened to tracks.

Example

<!--START_LASTFM_RECENT:{"rows": 3}-->
<!--END_LASTFM_RECENT-->

Output

Default

Track currently playing

Configuration

| Option | Default | Options | Description | | :----: | :-----: | :--------------: | :------------------------------------: | | rows | 8 | 1 ≤ integer ≤ 50 | The number of recent tracks to display |

ℹ️ User Info

Display information about a Last.fm user. An optional configuration object can be passed to specify which properties to display.

Example (Default)

<!--START_LASTFM_USER_INFO-->
<!--END_LASTFM_USER_INFO-->

Output

Example (Custom Configuration)

<!--START_LASTFM_USER_INFO:{"display": ["playcount", "artistCount"]}-->
<!--END_LASTFM_USER_INFO-->

Output

Configuration

| Option | Default | Options | Description | | :-------: | :----------------------------------------------------------------------: | :----------------------------------------------------------: | :------------------------------------------------: | | display | ["registered", "playcount", "artistCount", "albumCount", "trackCount"] | registered, playcount, artistCount, albumCount, trackCount | A list of properties to be included in the section |

🌟 Acknowledgements

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