https://github.com/dxnter/lastfm-readme
đļ Dynamically update your GitHub README with Last.fm metrics
https://github.com/dxnter/lastfm-readme
actions github lastfm profile-readme readme
Last synced: 6 months ago
JSON representation
đļ Dynamically update your GitHub README with Last.fm metrics
- Host: GitHub
- URL: https://github.com/dxnter/lastfm-readme
- Owner: dxnter
- License: mit
- Created: 2023-02-04T07:48:16.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-20T23:17:30.000Z (over 1 year ago)
- Last Synced: 2025-06-02T02:00:25.537Z (about 1 year ago)
- Topics: actions, github, lastfm, profile-readme, readme
- Language: TypeScript
- Homepage: https://github.com/marketplace/actions/last-fm-readme
- Size: 3.23 MB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# đĩ Last.fm README GitHub Action
**Dynamically update your GitHub `README.md` with [Last.fm](https://www.last.fm) metrics.**
[![MIT License][license.badge]][license]
[![GitHub Release][github.release.badge]][github.release]
## đ Quick Start
> [!TIP]
> **New to GitHub Actions?** Check out the [GitHub Actions documentation](https://docs.github.com/en/actions) to get started.
### đ§ Setup
#### đĩ Last.fm API Key
1. **Create a Last.fm API account**: Visit [Last.fm API](https://www.last.fm/api/account/create)
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 NameDescriptionRequired
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:
```html
```
### đŧ Create Your Workflow
Create `.github/workflows/lastfm.yml` in your repository:
```yaml
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](https://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
```html
```
### đ ī¸ Advanced Configuration
```html
```
đĄ 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:**
```html
```
---
### đ¤ Top Artists
Display the top listened to albums over a given period of time.
#### đŧī¸ Preview
#### đģ Usage Examples
```html
```
#### âī¸ Configuration Options
OptionTypeDefaultOptionsDescription
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
```html
```
#### âī¸ Configuration Options
OptionTypeDefaultOptionsDescription
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
```html
```
#### âī¸ Configuration Options
OptionTypeDefaultOptionsDescription
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
```html
```
#### âī¸ Configuration Options
OptionTypeDefaultOptionsDescription
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
```html
```
#### âī¸ Configuration Options
OptionTypeDefaultAvailable OptionsDescription
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](https://github.com/JasonEtco/rss-to-readme)
- [vnphanquang/monkeytype-readme](https://github.com/vnphanquang/monkeytype-readme)
- [athul/waka-readme](https://github.com/athul/waka-readme)
- [actions-js/profile-readme](https://github.com/actions-js/profile-readme)
[license.badge]: https://img.shields.io/badge/license-MIT-red.svg
[license]: ./LICENSE
[github.release.badge]: https://img.shields.io/github/v/release/dxnter/lastfm-readme
[github.release]: https://github.com/dxnter/lastfm-readme/releases