@elizaos/plugin-music 2.0.0-beta.1 → 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,192 +1,175 @@
-# @elizaos/plugin-music-library
-
-A comprehensive plugin for elizaOS that provides music data storage, user preferences, analytics, external music metadata APIs, and YouTube search functionality.
-
-## Features
-
-### Music Metadata & External APIs
-- **Track Information**: Extract metadata from YouTube URLs and track titles
-- **Artist Information**: Get artist details from multiple sources
-- **Album Information**: Retrieve album metadata
-- **Multiple Sources**: MusicBrainz, Last.fm, Genius, TheAudioDB, Wikipedia
-- **Fallback Chain**: Automatically tries multiple sources for best results
-- **Rate Limiting**: Built-in rate limiting for all APIs
-- **Retry Logic**: Automatic retry with exponential backoff
-- **Service Health Monitoring**: Tracks status of all integrated APIs
-
-### YouTube Integration
-- **YouTube Search**: Search for tracks, artists, albums on YouTube
-- **Smart Query Parsing**: Detects artist, genre, mood intents
-- **URL Extraction**: Parse and validate YouTube URLs
-
-### Music Library & Data Storage
-- **Track Database**: Store and discover tracks, albums, artists
-- **Play History**: Track what's been played and when
-- **Request Tracking**: Log who requested which tracks
-- **High-Quality Music Storage**: Store original high-quality audio files for archival
-  - Organized by artist/album/track
-  - Full metadata indexing
-  - Optional high-quality vs standard quality modes
-
-### Playlists
-- **Create & Save**: Save playlists for users
-- **Load & List**: Load and list playlists
-- **Share**: Share playlists between users
-
-### User Preferences
-- **Favorite Tracks**: Track user favorite tracks
-- **Favorite Artists**: Track favorite artists
-- **Disliked Tracks**: Remember what users don't like
-- **Genre Preferences**: Learn genre preferences over time
-- **Room Preferences**: Aggregate preferences across users in a room
-
-### Analytics
-- **Play Tracking**: Track every play with duration and requester
-- **Session Tracking**: Track listening sessions
-- **Statistics**: Get analytics for rooms (top tracks, artists, genres)
-
-### Anti-Repetition
-- **Repetition Control**: Prevent tracks from replaying too soon
-- **Variety Scoring**: Score tracks by variety to encourage diverse playlists
+# @elizaos/plugin-music
+
+A comprehensive music plugin for elizaOS that provides music library management, playback, queue management, playlists, analytics, YouTube search, multi-source metadata APIs, AI music generation, and a streaming HTTP API for Eliza agents.
+
+## Capabilities
+
+### Music Playback
+- Stream audio from YouTube URLs or direct media URLs to Discord voice channels or web clients
+- Queue management: add, view, clear tracks
+- Transport controls: play, pause, resume, skip, stop
+- Multi-zone and multi-route audio (broadcast to multiple Discord guilds or web streams simultaneously)
+- Live HTTP streaming endpoint (OGG/Shoutcast/Icecast) for web players
+
+### Music Library & Playlists
+- Persistent song library with title, artist, album, and URL indexing
+- Create, save, load, and share user playlists
+- Play history and request tracking per user and room
+- Smart play query: find and queue the best match from YouTube for a natural-language request
+- Download audio to a local library archive
+
+### Metadata & Discovery
+- Track, artist, and album metadata from MusicBrainz (no API key needed), Last.fm, Genius, TheAudioDB, and Wikipedia
+- YouTube search with smart query parsing (artist, genre, mood)
+- Spotify-backed recommendations
+- Automatic fallback chain across sources
+
+### User Preferences & Analytics
+- Per-user favorite tracks and artists, disliked tracks, genre preferences
+- Aggregated room preferences for auto-fill and DJ logic
+- Anti-repetition scoring to encourage variety
+- Play count, session, and tip analytics
+
+### AI Music Generation (Suno)
+- Generate original music from a text prompt (`generate`)
+- Extend existing audio (`extend`)
+- Custom generation with style, BPM, key, and reference audio (`custom_generate`)
+- Requires `SUNO_API_KEY`
 
 ## Installation
 
-As this is a workspace package, it's installed as part of the elizaOS monorepo:
+This plugin is part of the elizaOS monorepo:
 
 ```bash
 bun install
 ```
 
-## Configuration
+Add to a character config:
 
-The plugin works out of the box with MusicBrainz (free, no API key needed). For enhanced features, configure additional APIs:
+```json
+{
+  "plugins": [
+    "@elizaos/plugin-sql",
+    "@elizaos/plugin-music"
+  ]
+}
+```
 
-### Storage Configuration
+`@elizaos/plugin-sql` is recommended for persistent library, playlist, and preference storage.
 
-```bash
-# High-quality music storage directory (default: ./storage/music)
-MUSIC_STORAGE_DIR=/path/to/storage
+## Auto-Enable
 
-# Store highest quality available (default: true)
-MUSIC_STORAGE_HIGH_QUALITY=true
-```
+The plugin auto-enables when any of these settings are present:
+`LASTFM_API_KEY`, `GENIUS_API_KEY`, `THEAUDIODB_API_KEY`, `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`.
 
-**Storage vs Cache**:
-- **Music Library Storage** (this plugin): Permanent high-quality storage for archival and library management
-  - Original quality files (WebM, MP4, etc.)
-  - Organized by artist/album/track
-  - Indexed for browsing and discovery
-  - No expiration
-- **Music Player Cache** (`plugin-music-player`): Temporary Discord-optimized cache for performance
-  - Pre-transcoded to Opus/WebM for Discord
-  - Flat cache directory
-  - 7-day TTL with automatic cleanup
-  - Trades disk space for reduced CPU/bandwidth
+## Configuration
 
-### Optional Configuration
+### Required System Dependencies
 
-Add these to your `.env` file for enhanced metadata:
+- **`yt-dlp`** — Must be in PATH for audio download and caching. Install via `brew install yt-dlp`, `pipx install yt-dlp`, or download from [github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp). Override path with `YT_DLP_PATH`.
+- **`ffmpeg` / `ffprobe`** — Bundled via `ffmpeg-static`/`ffprobe-static`; override with `FFMPEG_PATH` and `FFPROBE_PATH`.
 
-```bash
-# MusicBrainz (optional - custom User-Agent)
-MUSICBRAINZ_USER_AGENT=YourAppName/1.0.0 (https://yourapp.com)
+### Optional API Keys
 
-# Last.fm API (free tier with signup)
+Add to `.env` or character settings for enhanced metadata and features:
+
+```bash
+# Last.fm — artist/track metadata (free with signup)
 LASTFM_API_KEY=your_lastfm_api_key
 
-# Genius API (free tier with signup) - for lyrics URLs
+# Genius — lyrics URLs (free with signup)
 GENIUS_API_KEY=your_genius_api_key
 
-# TheAudioDB API (free tier with signup) - for high-quality artwork
+# TheAudioDB — high-quality artwork (free with signup)
 THEAUDIODB_API_KEY=your_theaudiodb_api_key
-```
 
-## Usage
+# Spotify — recommendations
+SPOTIFY_CLIENT_ID=your_spotify_client_id
+SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
 
-Add the plugin to your character configuration:
+# Suno — AI music generation
+SUNO_API_KEY=your_suno_api_key
 
-```json
-{
-  "plugins": [
-    "@elizaos/plugin-sql",
-    "@elizaos/plugin-music-library"
-  ]
-}
+# MusicBrainz — custom User-Agent (optional; free, no key needed)
+MUSICBRAINZ_USER_AGENT=YourAppName/1.0.0 (https://yourapp.com)
 ```
 
-### Service Usage
-
-Access services directly in your code:
+### Other Settings
 
-```typescript
-const musicLibrary = runtime.getService('musicLibrary');
+```bash
+# Audio cache directory (default: <cwd>/cache/audio)
+AUDIO_CACHE_DIR=/path/to/cache
 
-// Get track info
-const trackInfo = await musicLibrary.getTrackInfo('https://youtube.com/watch?v=...');
+# Download quality preference (default: mp3_320)
+MUSIC_QUALITY_PREFERENCE=mp3_320
 
-// Save a playlist
-const playlist = await musicLibrary.savePlaylist(userId, {
-  name: 'My Playlist',
-  tracks: [...]
-});
+# YouTube cookies file for age-restricted content
+YOUTUBE_COOKIES=/path/to/cookies.txt
 
-// Track analytics
-await musicLibrary.trackTrackPlayed(roomId, track, duration, requester);
+# Proxy for yt-dlp
+YTDLP_PROXY=http://proxy:port
 
-// Get user preferences
-const prefs = await musicLibrary.getUserPreferences(userId);
+# Enable verbose music debug logging
+ELIZA_MUSIC_DEBUG=1
 ```
 
-### Actions
+## Actions
 
-Available actions:
-- `MUSIC_LIBRARY` - Consolidated planner-facing action.
-  - `op=playlist`, `subaction=save|load|delete|add` - Manage playlists.
-  - `op=search-youtube` - Search YouTube for music.
-  - `op=play-query` - Smart music query parser.
-  - `op=download` - Download music to the local library.
+All music operations route through a single **`MUSIC`** action with a verb-shaped `action` parameter.
 
-Legacy planner action names such as `PLAYLIST_OP`, `PLAYLIST`,
-`SEARCH_YOUTUBE`, `PLAY_MUSIC_QUERY`, and `DOWNLOAD_MUSIC` are retained as
-similes for `MUSIC_LIBRARY`.
+| Subaction | Description |
+|-----------|-------------|
+| `play` | Play a track by URL or query |
+| `pause` | Pause current playback |
+| `resume` | Resume paused playback |
+| `skip` | Skip to next track (requires `confirmed: true`) |
+| `stop` | Stop playback (requires `confirmed: true`) |
+| `queue_view` | Show current queue |
+| `queue_add` | Add a track to the queue (requires `confirmed: true`) |
+| `queue_clear` | Clear the queue (requires `confirmed: true`) |
+| `playlist_play` | Load and play a saved playlist |
+| `playlist_save` | Save current queue as a playlist (requires `confirmed: true`) |
+| `search` | Search YouTube for music |
+| `play_query` | Smart natural-language music query (search + play) |
+| `download` | Download a track to the local library (requires `confirmed: true`) |
+| `play_audio` | Play a direct media URL |
+| `set_routing` | Configure audio routing mode |
+| `set_zone` | Configure audio zones |
+| `generate` | AI-generate music from prompt (Suno) |
+| `extend` | Extend existing Suno audio |
+| `custom_generate` | Custom Suno generation with style/BPM/key |
 
-## Integration with Other Plugins
+The `MUSIC` action aggregates similes from its sub-handlers, so legacy intent names such as `PAUSE_MUSIC`, `PLAY_YOUTUBE`, `PLAYLIST`, `SEARCH_YOUTUBE`, `PLAY_MUSIC_QUERY`, `DOWNLOAD_MUSIC`, and `GENERATE_MUSIC` still match. The verb-shaped aliases in `SUBACTION_ALIASES` (e.g. `playlist`, `search_youtube`, `routing`, `zones`, `next`, `unpause`) are also accepted for the `action` parameter.
 
-This plugin is designed to work with:
+## HTTP Streaming API
 
-- **@elizaos/plugin-music-player**: Provides data storage for playback
-- **@elizaos/plugin-radio**: Provides preferences and analytics for radio programming
-- **@elizaos/plugin-sql**: Required for data persistence
+The plugin registers routes on the agent's HTTP server (prefix `/api/<agentId>/music-player/`):
 
-## API
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/stream` | public | Live audio stream |
+| GET | `/now-playing` | public | Now-playing metadata |
+| GET | `/queue` | public | Queue JSON |
+| GET | `/status` | public | Playback status |
+| POST | `/control/pause` | authenticated | Pause |
+| POST | `/control/resume` | authenticated | Resume |
+| POST | `/control/stop` | authenticated | Stop |
+| POST | `/control/skip` | authenticated | Skip |
 
-### Services
+Authenticated endpoints accept `Authorization: Bearer <token>`, `X-Eliza-Token`, or `X-Api-Key`.
 
-#### MusicInfoService
-- `getTrackInfo(urlOrTitle: string)`: Get track metadata
-- `getArtistInfo(artistName: string)`: Get artist information
-- `getAlbumInfo(albumTitle: string, artistName?: string)`: Get album information
+## Services
 
-#### YouTubeSearchService
-- `search(query: string, maxResults?: number)`: Search YouTube
-- `extractVideoId(url: string)`: Extract video ID from URL
+Access from agent code via `runtime.getService(...)`:
 
-#### MusicLibraryService
-- `addSong(song)`, `getSong(url)`, `getRecentSongs(limit)`, `searchLibrary(query)`
-- `savePlaylist(entityId, playlist)`, `loadPlaylists(entityId)`
-- `trackTrackPlayed(roomId, track, duration)`, `trackTrackRequest(entityId, track)`
-- `getAggregatedRoomPreferences(roomId)` returns combined favorites/dislikes for auto-fill logic
-- Exposes `repetitionControl` utilities and a configured `spotifyClient`
+- `runtime.getService('music')` → `MusicService` — playback engine, queue, routing
+- `runtime.getService('musicLibrary')` → `MusicLibraryService` — library, playlists, preferences, analytics
 
-### Components
+## Integration
 
-See individual component files for detailed APIs:
-- `components/musicLibrary.ts` - Track/album/artist database
-- `components/playlists.ts` - Playlist management
-- `components/preferences.ts` - User preferences
-- `components/analytics.ts` - Analytics tracking
-- `components/repetitionControl.ts` - Anti-repetition logic
+This plugin works alongside:
 
-## License
+- **`@elizaos/plugin-discord`** — Provides voice channel playback (wired automatically on init)
+- **`@elizaos/plugin-sql`** — Required for persistent library and playlist storage
+- **`@elizaos/plugin-suno`** — Required for AI generation subactions
 
-MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/plugin-music",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.2",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -13,15 +13,31 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
-    "@elizaos/plugin-sql": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.3-beta.2",
+    "@elizaos/plugin-suno": "2.0.3-beta.2",
     "@vookav2/play-dl": "^1.9.9",
     "buffer": "^6.0.3",
     "ffmpeg-static": "^5.3.0",
@@ -39,7 +55,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit -p tsconfig.typecheck.json",
     "lint": "bunx @biomejs/biome check --write --unsafe .",
     "lint:check": "bunx @biomejs/biome check .",
     "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo",
@@ -54,5 +70,6 @@
   "agentConfig": {
     "pluginType": "elizaos:plugin:1.0.0",
     "pluginParameters": {}
-  }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
 }