RFC: plyr.fm JavaScript SDK & Embeddable Web Components

plyrfm/                          # or @plyr/sdk — naming TBD
├── src/
│   ├── client.ts                # PlyrClient class
│   ├── types.ts                 # TypeScript interfaces (Track, Album, Playlist, Artist, etc.)
│   ├── audio.ts                 # Audio playback utilities (play counting, lossless detection, gated checks)
│   ├── index.ts                 # Headless SDK entrypoint
│   └── components/
│       ├── plyr-track.ts        # <plyr-track> Web Component
│       ├── plyr-playlist.ts     # <plyr-playlist> Web Component
│       ├── plyr-album.ts        # <plyr-album> Web Component
│       ├── styles.ts            # Shared CSS (design tokens, container queries)
│       └── index.ts             # Web Components entrypoint
├── package.json
├── tsconfig.json
└── README.md

{
  "exports": {
    ".": "./dist/index.js",
    "./components": "./dist/components/index.js"
  }
}

import { PlyrClient } from 'plyrfm'

const plyr = new PlyrClient()
const track = await plyr.getTrack(795)
console.log(track.title, track.r2_url)

<script type="module">
  import 'plyrfm/components'
</script>

<plyr-track track-id="795"></plyr-track>
<plyr-playlist playlist-id="8ec653a8-1166-4f2f-80db-93b7717e8410"></plyr-playlist>
<plyr-album handle="goose.art" slug="fuck"></plyr-album>

class PlyrClient {
  constructor(options?: { apiUrl?: string; token?: string })

  // Tracks
  listTracks(options?: { limit?: number; cursor?: string; artistDid?: string }): Promise<TracksListResponse>
  topTracks(options?: { limit?: number }): Promise<Track[]>
  getTrack(id: number): Promise<Track>
  reportPlay(id: number, options?: { ref?: string }): Promise<{ play_count: number }>

  // Albums
  listAlbums(): Promise<Album[]>
  getArtistAlbums(handle: string): Promise<Album[]>
  getAlbum(handle: string, slug: string): Promise<AlbumResponse>

  // Playlists
  getPlaylist(id: string): Promise<PlaylistWithTracks>

  // Artists
  getArtist(handleOrDid: string): Promise<Artist>
  getArtistAnalytics(did: string): Promise<ArtistAnalytics>
  batchArtists(dids: string[]): Promise<Record<string, Artist>>

  // Search
  search(query: string, options?: { type?: string; limit?: number }): Promise<SearchResponse>
  semanticSearch(query: string, options?: { limit?: number }): Promise<SemanticSearchResponse>

  // Audio utilities
  getAudioUrl(fileId: string): Promise<string>
  checkGatedAccess(fileId: string): Promise<'ok' | 'auth-required' | 'supporter-required'>

  // oEmbed
  getOEmbed(url: string, options?: { maxwidth?: number; maxheight?: number }): Promise<OEmbedResponse>
}

interface Track {
  id: number
  title: string
  artist: string
  artist_handle: string
  artist_did?: string
  artist_avatar_url?: string
  file_id: string
  file_type: string
  features: unknown[]
  r2_url?: string
  image_url?: string
  thumbnail_url?: string
  play_count: number
  like_count?: number
  comment_count?: number
  tags?: string[]
  album?: AlbumSummary | null
  gated?: boolean
  support_gate?: SupportGate | null
  original_file_id?: string | null
  original_file_type?: string | null
  description?: string | null
  audio_storage?: 'r2' | 'pds' | 'both'
  created_at?: string
  atproto_record_uri?: string
  atproto_record_cid?: string
  atproto_record_url?: string | null
  is_liked?: boolean
  copyright_flagged?: boolean | null
  copyright_match?: string | null
  pds_blob_cid?: string
}

// Play count tracking — fires POST /tracks/{id}/play after threshold
function createPlayCounter(client: PlyrClient): PlayCounter

// Lossless format detection — checks browser canPlayType
function canPlayLossless(fileType: string): boolean

// Gated content check — request to /audio/{fileId} (exact gating behavior TBD — needs verification with a gated track)
async function checkAccess(fileId: string): Promise<'ok' | 'auth-required' | 'supporter-required'>

// Resolve best audio URL for a track (prefer lossless if supported)
function resolveAudioSrc(track: Track): string

<plyr-track
  track-id="795"
  autoplay
  accent-color="#6a9fff"
></plyr-track>

<plyr-playlist
  playlist-id="8ec653a8-1166-4f2f-80db-93b7717e8410"
></plyr-playlist>

<plyr-album
  handle="goose.art"
  slug="fuck"
></plyr-album>

const el = document.querySelector('plyr-track')
el.play()
el.pause()
el.currentTime = 30
el.volume = 0.5