@rmdes/indiekit-endpoint-funkwhale

@rmdes/indiekit-endpoint-funkwhale

Funkwhale listening activity endpoint for Indiekit.

Display your Funkwhale listening history, favorite tracks, and listening statistics on your IndieWeb site.

Installation

Install from npm:

npm install @rmdes/indiekit-endpoint-funkwhale

Features

• Admin Dashboard - Overview of your listening activity in Indiekit's admin UI
• Now Playing Widget - Shows currently playing or recently played tracks
• Listening History - Browse your listening history with album art
• Favorites - Display your favorite tracks
• Statistics - View listening stats (plays, unique tracks, unique artists)
• Background Sync - Automatically syncs listening data to MongoDB
• Public JSON API - For integration with static site generators like Eleventy

Configuration

Add to your indiekit.config.js:

import FunkwhaleEndpoint from "@rmdes/indiekit-endpoint-funkwhale";

export default {
  plugins: [
    new FunkwhaleEndpoint({
      mountPath: "/funkwhale",
      instanceUrl: process.env.FUNKWHALE_INSTANCE,
      username: process.env.FUNKWHALE_USERNAME,
      token: process.env.FUNKWHALE_TOKEN,
      cacheTtl: 900_000,      // 15 minutes
      syncInterval: 300_000,  // 5 minutes
      limits: {
        listenings: 20,
        favorites: 20,
        topArtists: 10,
        topAlbums: 10
      }
    }),
  ],
};

Environment Variables

Variable	Required	Description
FUNKWHALE_INSTANCE	Yes	Your Funkwhale instance URL (e.g., https://funkwhale.example.com)
FUNKWHALE_TOKEN	Yes	API access token (Bearer token)
FUNKWHALE_USERNAME	Yes	Your username on the Funkwhale instance

Getting an API Token

1. Log in to your Funkwhale instance
2. Go to Settings > Applications
3. Create a new application with read permissions
4. Copy the access token

Routes

Admin Routes (require authentication)

Route	Description
GET /funkwhale/	Dashboard overview with stats, recent plays, favorites
POST /funkwhale/sync	Trigger manual sync

Public API Routes (JSON)

These endpoints are publicly accessible and can be used by static site generators like Eleventy to display listening activity on your site.

Route	Description
GET /funkwhale/api/now-playing	Current/recent track
GET /funkwhale/api/listenings	Recent listenings
GET /funkwhale/api/favorites	Favorites list
GET /funkwhale/api/stats	All statistics (summary, top artists, top albums)
GET /funkwhale/api/stats/trends	Trend data for charts (30 days)

Example: Eleventy Integration

Fetch data from the public API in your Eleventy _data file:

// _data/funkwhale.js
import EleventyFetch from "@11ty/eleventy-fetch";

export default async function() {
  const baseUrl = process.env.SITE_URL || "https://example.com";

  const [nowPlaying, listenings, stats] = await Promise.all([
    EleventyFetch(`${baseUrl}/funkwhale/api/now-playing`, { duration: "15m", type: "json" }),
    EleventyFetch(`${baseUrl}/funkwhale/api/listenings`, { duration: "15m", type: "json" }),
    EleventyFetch(`${baseUrl}/funkwhale/api/stats`, { duration: "15m", type: "json" }),
  ]);

  return { nowPlaying, listenings, stats };
}

Options

Option	Default	Description
mountPath	/funkwhale	URL path for the endpoint
instanceUrl	-	Funkwhale instance URL
token	-	API access token
username	-	User to track
cacheTtl	900000	Cache TTL in ms (15 min)
syncInterval	300000	Background sync interval in ms (5 min)
limits.listenings	20	Listenings per page
limits.favorites	20	Favorites per page
limits.topArtists	10	Top artists to show
limits.topAlbums	10	Top albums to show

Now Playing Logic

• Now Playing: Track listened to within the last 60 minutes
• Recently Played: Track listened to within the last 24 hours
• Last Played: Older tracks show timestamp only

Requirements

• Indiekit >= 1.0.0-beta.25
• MongoDB (for statistics aggregation and sync)
• Funkwhale instance with API v2

License

MIT