README.md

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