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

package/dist/index.d.ts

@@ -1,2263 +0,0 @@
-import { Action, UUID, IAgentRuntime, AgentRuntime, Service, Plugin } from '@elizaos/core';
-import { EventEmitter } from 'node:events';
-import { Readable, PassThrough } from 'node:stream';
-import { ServerResponse } from 'node:http';
-
-declare const musicAction: Action;
-
-/**
- * Analytics data for a guild/room
- */
-interface DJAnalytics {
-    totalTracksPlayed: number;
-    totalPlayTime: number;
-    mostPlayedTracks: Array<{
-        url: string;
-        title: string;
-        playCount: number;
-        lastPlayed: number;
-    }>;
-    mostRequestedBy: Array<{
-        entityId: UUID;
-        name: string;
-        requestCount: number;
-    }>;
-    popularTimes: Array<{
-        hour: number;
-        playCount: number;
-    }>;
-    popularDays: Array<{
-        day: number;
-        playCount: number;
-    }>;
-    milestones: Array<{
-        type: string;
-        value: number;
-        timestamp: number;
-    }>;
-    sessionStats: {
-        totalSessions: number;
-        averageSessionDuration: number;
-        longestSession: number;
-    };
-}
-interface ListenerSnapshot {
-    timestamp: number;
-    listenerCount: number;
-    humanListenerCount: number;
-    botListenerCount: number;
-}
-/**
- * Get analytics for a guild/room
- */
-declare function getAnalytics(runtime: IAgentRuntime, roomId: UUID): Promise<DJAnalytics | null>;
-/**
- * Track a track being played
- */
-declare function trackTrackPlayed(runtime: IAgentRuntime, roomId: UUID, track: {
-    url: string;
-    title: string;
-}, duration: number, requestedBy?: {
-    entityId: UUID;
-    name: string;
-}): Promise<void>;
-/**
- * Track a listening session
- */
-declare function trackSession(runtime: IAgentRuntime, roomId: UUID, duration: number): Promise<void>;
-/**
- * Track a listener snapshot for analytics
- * Called by the listener tracking service in plugin-radio
- */
-declare function trackListenerSnapshot(runtime: IAgentRuntime, roomId: UUID, snapshot: ListenerSnapshot): Promise<void>;
-
-/**
- * Per-Guild DJ Settings
- * Comprehensive settings for DJ behavior specific to each guild/room
- */
-interface DJGuildSettings {
-    autonomyLevel?: "MANUAL" | "BALANCED" | "AUTONOMOUS" | "RADIO";
-    enabled: boolean;
-    autoFillEnabled: boolean;
-    autoFillThreshold?: number;
-    timeBasedProgramming: boolean;
-    repetitionControlEnabled: boolean;
-    introsEnabled: boolean;
-    commentaryEnabled: boolean;
-    useLLMForCommentary: boolean;
-    jokesSetting: boolean;
-    autoTriviaEnabled: boolean;
-    autoTriviaMinTracks?: number;
-    autoTriviaMinMinutes?: number;
-    autoJokesEnabled: boolean;
-    autoJokesMinTracks?: number;
-    autoJokesMinMinutes?: number;
-    autoRecapEnabled: boolean;
-    autoRecapMinTracks?: number;
-    autoRecapMinMinutes?: number;
-    stationName?: string;
-    stationDescription?: string;
-    listenerTrackingEnabled: boolean;
-    audioQuality?: "high" | "medium" | "low";
-    crossFadeEnabled: boolean;
-    crossFadeDuration?: number;
-    createdAt: number;
-    updatedAt: number;
-    createdBy?: UUID;
-    lastModifiedBy?: UUID;
-}
-/**
- * Default guild settings
- */
-declare const DEFAULT_GUILD_SETTINGS: DJGuildSettings;
-/**
- * Get DJ guild settings for a room
- */
-declare function getDJGuildSettings(runtime: IAgentRuntime, roomId: UUID): Promise<DJGuildSettings>;
-/**
- * Set DJ guild settings for a room
- */
-declare function setDJGuildSettings(runtime: IAgentRuntime, roomId: UUID, settings: Partial<DJGuildSettings>, modifiedBy?: UUID): Promise<void>;
-/**
- * Reset DJ guild settings to defaults
- */
-declare function resetDJGuildSettings(runtime: IAgentRuntime, roomId: UUID, modifiedBy?: UUID): Promise<void>;
-/**
- * Enable/disable DJ for a guild
- */
-declare function toggleDJ(runtime: IAgentRuntime, roomId: UUID, enabled: boolean, modifiedBy?: UUID): Promise<void>;
-/**
- * Set autonomy level for a guild
- */
-declare function setAutonomyLevel(runtime: IAgentRuntime, roomId: UUID, level: "MANUAL" | "BALANCED" | "AUTONOMOUS" | "RADIO", modifiedBy?: UUID): Promise<void>;
-/**
- * Get all configured guilds
- */
-declare function getAllConfiguredGuilds(_runtime: IAgentRuntime): Promise<Array<{
-    roomId: UUID;
-    settings: DJGuildSettings;
-}>>;
-
-/**
- * DJ Intro Options
- * Advanced configuration for DJ track introductions and commentary
- */
-interface DJIntroOptions {
-    useLLM: boolean;
-    llmModel?: string;
-    style: "concise" | "detailed" | "casual" | "professional" | "energetic" | "chill";
-    personality?: string;
-    includeJokes: boolean;
-    jokeFrequency?: number;
-    includeFunFacts: boolean;
-    includeArtistInfo: boolean;
-    includeDedications: boolean;
-    dedicationStyle?: "brief" | "heartfelt" | "casual";
-    introDuration: "short" | "medium" | "long";
-    skipIntroChance?: number;
-    minTracksBetweenIntros?: number;
-    customTemplates?: string[];
-    templateVariety: boolean;
-    contextWindow?: number;
-    musicInfoIntegration: boolean;
-    listenerCountIntegration: boolean;
-}
-/**
- * Default DJ intro options
- */
-declare const DEFAULT_DJ_INTRO_OPTIONS: DJIntroOptions;
-/**
- * Get DJ intro options for a room
- */
-declare function getDJIntroOptions(runtime: IAgentRuntime, roomId: UUID): Promise<DJIntroOptions>;
-/**
- * Set DJ intro options for a room
- */
-declare function setDJIntroOptions(runtime: IAgentRuntime, roomId: UUID, options: Partial<DJIntroOptions>): Promise<void>;
-/**
- * Reset DJ intro options to defaults for a room
- */
-declare function resetDJIntroOptions(runtime: IAgentRuntime, roomId: UUID): Promise<void>;
-/**
- * Get intro prompt based on options
- */
-declare function buildIntroPrompt(options: DJIntroOptions, context: {
-    characterName: string;
-    trackTitle: string;
-    artistName?: string;
-    albumName?: string;
-    dedicatedTo?: string;
-    dedicationMessage?: string;
-    listenerCount?: number;
-    previousTracks?: string[];
-}): string;
-
-/**
- * DJ Tip record
- */
-interface DJTip {
-    from: string;
-    fromUserId: string;
-    amount: number;
-    currency: string;
-    message?: string;
-    timestamp: number;
-    transactionId?: string;
-    roomId?: UUID;
-}
-interface TopTipper {
-    userId: string;
-    username: string;
-    totalAmount: number;
-    currency: string;
-    tipCount: number;
-}
-/**
- * DJ Tip Statistics
- */
-interface DJTipStats {
-    totalTips: number;
-    totalAmount: Record<string, number>;
-    tips: DJTip[];
-    topTippers: TopTipper[];
-}
-/**
- * Track a DJ tip
- */
-declare function trackDJTip(runtime: IAgentRuntime, roomId: UUID, tip: Omit<DJTip, "roomId">): Promise<void>;
-/**
- * Get DJ tip statistics
- */
-declare function getDJTipStats(runtime: IAgentRuntime): Promise<DJTipStats>;
-/**
- * Get recent tips
- */
-declare function getRecentTips(runtime: IAgentRuntime, limit?: number): Promise<DJTip[]>;
-/**
- * Get top tippers
- */
-declare function getTopTippers(runtime: IAgentRuntime, limit?: number): Promise<DJTipStats["topTippers"]>;
-
-/**
- * Represents a song in the global music library
- */
-interface LibrarySong {
-    id: string;
-    url: string;
-    title: string;
-    artist?: string;
-    channel?: string;
-    duration?: number;
-    playCount: number;
-    lastPlayed: number;
-    firstAdded: number;
-    requestedBy: Set<string>;
-}
-/**
- * Get a song from the library by URL
- */
-declare function getSong(runtime: IAgentRuntime, url: string): Promise<LibrarySong | null>;
-/**
- * Add or update a song in the library
- */
-declare function addSongToLibrary(runtime: IAgentRuntime, songData: {
-    url: string;
-    title: string;
-    artist?: string;
-    channel?: string;
-    duration?: number;
-    requestedBy?: string;
-}): Promise<LibrarySong>;
-/**
- * Get recent songs from the library (sorted by last played)
- */
-declare function getRecentSongs(runtime: IAgentRuntime, limit?: number): Promise<LibrarySong[]>;
-/**
- * Search the library for songs matching a query
- */
-declare function searchLibrary(runtime: IAgentRuntime, query: string, limit?: number): Promise<LibrarySong[]>;
-/**
- * Get the most recently played song
- */
-declare function getLastPlayedSong(runtime: IAgentRuntime): Promise<LibrarySong | null>;
-/**
- * Get all songs sorted by play count
- */
-declare function getMostPlayedSongs(runtime: IAgentRuntime, limit?: number): Promise<LibrarySong[]>;
-/**
- * Get library statistics
- */
-declare function getLibraryStats(runtime: IAgentRuntime): Promise<{
-    totalSongs: number;
-    totalPlays: number;
-    mostPlayed?: LibrarySong;
-}>;
-
-/**
- * Represents a track in a playlist
- */
-interface PlaylistTrack {
-    url: string;
-    title: string;
-    duration?: number;
-    addedAt?: number;
-    requestedBy?: string;
-    dedicatedTo?: string;
-    dedicationMessage?: string;
-}
-/**
- * Represents a saved playlist
- */
-interface Playlist {
-    id: string;
-    name: string;
-    tracks: PlaylistTrack[];
-    createdAt: number;
-    updatedAt: number;
-    isFavorite?: boolean;
-}
-/**
- * Save a playlist to user's entity components
- */
-declare function savePlaylist(runtime: IAgentRuntime, entityId: UUID, playlist: Omit<Playlist, "id" | "createdAt" | "updatedAt"> & {
-    id?: string;
-    createdAt?: number;
-}): Promise<Playlist>;
-/**
- * Load all playlists for a user
- */
-declare function loadPlaylists(runtime: IAgentRuntime, entityId: UUID): Promise<Playlist[]>;
-/**
- * Delete a playlist
- */
-declare function deletePlaylist(runtime: IAgentRuntime, entityId: UUID, playlistId: string): Promise<boolean>;
-
-/**
- * User music preferences
- */
-interface UserMusicPreferences {
-    favoriteGenres?: string[];
-    favoriteArtists?: string[];
-    favoriteTracks?: Array<{
-        url: string;
-        title: string;
-        playCount?: number;
-    }>;
-    dislikedTracks?: string[];
-    skipHistory?: Array<{
-        url: string;
-        timestamp: number;
-    }>;
-    requestHistory?: Array<{
-        url: string;
-        title: string;
-        timestamp: number;
-    }>;
-    listeningSessions?: Array<{
-        startTime: number;
-        endTime?: number;
-        tracksPlayed: number;
-    }>;
-}
-/**
- * Update user music preferences
- */
-declare function updateUserPreferences(runtime: IAgentRuntime, entityId: UUID, preferences: Partial<UserMusicPreferences>, roomId?: UUID, worldId?: UUID): Promise<UserMusicPreferences>;
-/**
- * Get user music preferences
- */
-declare function getUserPreferences(runtime: IAgentRuntime, entityId: UUID): Promise<UserMusicPreferences | null>;
-/**
- * Get preferences for all users in a room
- */
-declare function getRoomPreferences(runtime: IAgentRuntime, roomId: UUID): Promise<Map<UUID, UserMusicPreferences>>;
-/**
- * Track a track request
- */
-declare function trackTrackRequest(runtime: IAgentRuntime, entityId: UUID, track: {
-    url: string;
-    title: string;
-}, roomId?: UUID, worldId?: UUID): Promise<void>;
-/**
- * Track a skip
- */
-declare function trackSkip(runtime: IAgentRuntime, entityId: UUID, trackUrl: string, roomId?: UUID, worldId?: UUID): Promise<void>;
-/**
- * Track favorite track
- */
-declare function trackFavorite(runtime: IAgentRuntime, entityId: UUID, track: {
-    url: string;
-    title: string;
-}, roomId?: UUID, worldId?: UUID): Promise<void>;
-
-/**
- * Track play history for repetition control
- */
-interface PlayHistoryEntry {
-    url: string;
-    title: string;
-    playedAt: number;
-}
-/**
- * Smart repetition control to avoid playing same songs too frequently
- */
-declare class RepetitionControl {
-    private playHistory;
-    private readonly MAX_HISTORY_SIZE;
-    private readonly MIN_REPLAY_INTERVAL;
-    /**
-     * Record a track play
-     */
-    recordPlay(guildId: string, url: string, title: string): void;
-    /**
-     * Check if a track can be played (not played too recently)
-     */
-    canPlay(guildId: string, url: string, minInterval?: number): boolean;
-    /**
-     * Get recently played tracks for a guild
-     */
-    getRecentlyPlayed(guildId: string, count?: number): PlayHistoryEntry[];
-    /**
-     * Filter tracks to avoid repetition
-     */
-    filterRepetition(guildId: string, tracks: Array<{
-        url: string;
-        title: string;
-    }>, minInterval?: number): Array<{
-        url: string;
-        title: string;
-    }>;
-    /**
-     * Get play count for a track in recent history
-     */
-    getRecentPlayCount(guildId: string, url: string, timeWindow?: number): number;
-    /**
-     * Score tracks based on variety (lower score = played less recently)
-     */
-    scoreByVariety(guildId: string, tracks: Array<{
-        url: string;
-        title: string;
-        playCount?: number;
-    }>): Array<{
-        url: string;
-        title: string;
-        playCount?: number;
-        varietyScore: number;
-    }>;
-    /**
-     * Clear history for a guild
-     */
-    clearHistory(guildId: string): void;
-    /**
-     * Get statistics for a guild
-     */
-    getStats(guildId: string): {
-        totalPlays: number;
-        uniqueTracks: number;
-        averageRepeatInterval: number;
-    };
-}
-declare const repetitionControl: RepetitionControl;
-
-/**
- * Detailed per-song memory and statistics
- * Tracks everything about a song across all rooms
- */
-interface SongMemory {
-    url: string;
-    title: string;
-    artist?: string;
-    album?: string;
-    duration?: number;
-    totalPlays: number;
-    totalPlayTime: number;
-    lastPlayed: number;
-    firstPlayed: number;
-    totalRequests: number;
-    uniqueRequesters: number;
-    topRequesters: Array<{
-        entityId: UUID;
-        name: string;
-        count: number;
-    }>;
-    totalLikes: number;
-    totalDislikes: number;
-    skipCount: number;
-    completionRate: number;
-    playedInRooms: Array<{
-        roomId: UUID;
-        playCount: number;
-        lastPlayed: number;
-    }>;
-    dedicationCount: number;
-    dedications: Array<{
-        from: string;
-        to: string;
-        message?: string;
-        timestamp: number;
-    }>;
-    popularHours: number[];
-    popularDays: number[];
-    averageListenerCount: number;
-    peakListenerCount: number;
-    listenerEngagement: number;
-    createdAt: number;
-    updatedAt: number;
-    tags?: string[];
-    notes?: string;
-}
-/**
- * Get song memory
- */
-declare function getSongMemory(runtime: IAgentRuntime, url: string): Promise<SongMemory | null>;
-/**
- * Record a play
- */
-declare function recordSongPlay(runtime: IAgentRuntime, song: {
-    url: string;
-    title: string;
-    artist?: string;
-    album?: string;
-    duration?: number;
-}, context: {
-    roomId?: UUID;
-    playDuration: number;
-    listenerCount?: number;
-    requestedBy?: {
-        entityId: UUID;
-        name: string;
-    };
-    wasSkipped?: boolean;
-}): Promise<void>;
-/**
- * Record a request
- */
-declare function recordSongRequest(runtime: IAgentRuntime, song: {
-    url: string;
-    title: string;
-    artist?: string;
-    album?: string;
-    duration?: number;
-}, requester: {
-    entityId: UUID;
-    name: string;
-}): Promise<void>;
-/**
- * Record a dedication
- */
-declare function recordSongDedication(runtime: IAgentRuntime, url: string, dedication: {
-    from: string;
-    to: string;
-    message?: string;
-}): Promise<void>;
-/**
- * Get top songs by play count
- */
-declare function getTopSongs(_runtime: IAgentRuntime, _limit?: number): Promise<SongMemory[]>;
-/**
- * Get most requested songs
- */
-declare function getMostRequestedSongs(_runtime: IAgentRuntime, _limit?: number): Promise<SongMemory[]>;
-
-/**
- * Audio Broadcast Contracts
- *
- * WHY THIS EXISTS:
- * These contracts define how audio flows from music-player to consumers (Discord, Web, etc.)
- * without creating dependencies between plugins. This allows:
- *
- * 1. Plugin Independence: music-player doesn't know about Discord, Discord doesn't know
- *    about music-player internals. They communicate through contracts.
- *
- * 2. Multiple Consumers: Multiple outputs (Discord + 5 web listeners) can all receive
- *    the same broadcast independently without affecting each other.
- *
- * 3. Resilience: If Discord disconnects, the broadcast continues. Web listeners are
- *    unaffected. Discord can reconnect and resume from live position.
- *
- * 4. No Radio Dependency: music-player + discord work together without needing the
- *    radio plugin. Radio can add orchestration features, but isn't required.
- */
-/**
- * Subscription to an audio broadcast stream
- *
- * WHY: Each consumer needs independent control over their subscription.
- * One consumer unsubscribing shouldn't affect others.
- */
-interface AudioSubscription {
-    /** Unique identifier for this subscription */
-    readonly consumerId: string;
-    /** The audio stream (PCM or Opus frames) */
-    readonly stream: Readable;
-    /** Unsubscribe from the broadcast */
-    unsubscribe(): void;
-}
-/**
- * Audio broadcast state
- */
-type BroadcastState = "live" | "silence" | "stopped";
-/**
- * Track metadata for broadcast events
- */
-interface BroadcastTrackMetadata {
-    title: string;
-    url: string;
-    duration?: number;
-    requestedBy?: string;
-}
-/**
- * Audio broadcast interface - represents a continuous audio stream
- * that multiple consumers can subscribe to independently.
- *
- * WHY NON-BLOCKING:
- * A slow web listener with a bad connection should NOT cause Discord audio to stutter.
- * Each consumer is isolated - if they can't keep up, we drop their frames, not the source.
- *
- * WHY RESILIENT:
- * Radio stations don't stop broadcasting when everyone changes the channel. Similarly,
- * the broadcast continues even with zero subscribers, so reconnecting is seamless.
- *
- * WHY LIVE:
- * When Discord reconnects after a hiccup, it should hear what's playing NOW, not
- * buffered audio from 10 seconds ago. This is radio-style, not recording-style.
- *
- * Implementations must ensure:
- * - Non-blocking: slow consumers don't affect the broadcast or other consumers
- * - Resilient: broadcast continues even if all consumers disconnect
- * - Live: new subscribers get current audio, not buffered past audio
- */
-interface IAudioBroadcast extends EventEmitter {
-    /** Guild/server this broadcast is for */
-    readonly guildId: string;
-    /** Current broadcast state */
-    readonly state: BroadcastState;
-    /**
-     * Subscribe to this broadcast stream
-     * @param consumerId Unique identifier for the consumer
-     * @returns Subscription object with stream and unsubscribe method
-     */
-    subscribe(consumerId: string): AudioSubscription;
-    /**
-     * Get current subscriber count
-     */
-    getSubscriberCount(): number;
-    /**
-     * Check if a consumer is currently subscribed
-     */
-    isSubscribed(consumerId: string): boolean;
-    on(event: "stateChange", listener: (state: BroadcastState) => void): this;
-    on(event: "metadata", listener: (metadata: BroadcastTrackMetadata) => void): this;
-    on(event: "subscriberAdded", listener: (consumerId: string) => void): this;
-    on(event: "subscriberRemoved", listener: (consumerId: string) => void): this;
-    emit(event: "stateChange", state: BroadcastState): boolean;
-    emit(event: "metadata", metadata: BroadcastTrackMetadata): boolean;
-    emit(event: "subscriberAdded", consumerId: string): boolean;
-    emit(event: "subscriberRemoved", consumerId: string): boolean;
-}
-
-/**
- * Broadcast - Implements IAudioBroadcast contract
- *
- * WHY THIS FACADE:
- * Consumers (Discord, Web) shouldn't care about internal complexity (StreamCore,
- * StreamMultiplexer, silence generation, backpressure policies). They just want:
- * - subscribe() → get audio stream
- * - unsubscribe() → stop receiving audio
- * - events → know what's playing
- *
- * This class is the ONLY public interface. Everything else (core components) is internal.
- *
- * ARCHITECTURE LAYERS:
- * ```
- * Consumer Layer: Discord, Web, etc. → call subscribe()
- *       ↓
- * Facade Layer: Broadcast (this class) → implements IAudioBroadcast
- *       ↓
- * Generation Layer: StreamCore → produces audio (tracks or silence)
- *       ↓
- * Distribution Layer: StreamMultiplexer → fans out to N consumers
- * ```
- *
- * WHY WIRE THEM IN CONSTRUCTOR:
- * StreamCore → StreamMultiplexer wiring happens once. The output stream is long-lived
- * (never closes). Tracks come and go, but the pipeline stays connected.
- *
- * This is the public interface that consumers (Discord, Web, etc.) interact with.
- * Internally uses StreamCore for audio generation and StreamMultiplexer for fan-out.
- */
-declare class Broadcast extends EventEmitter implements IAudioBroadcast {
-    readonly guildId: string;
-    private streamCore;
-    private multiplexer;
-    private _state;
-    constructor(guildId: string);
-    /**
-     * Get current broadcast state
-     */
-    get state(): BroadcastState;
-    /**
-     * Subscribe to this broadcast
-     * @param consumerId Unique identifier for the consumer
-     * @returns AudioSubscription with stream and unsubscribe method
-     */
-    subscribe(consumerId: string): AudioSubscription;
-    /**
-     * Get current subscriber count
-     */
-    getSubscriberCount(): number;
-    /**
-     * Check if a consumer is subscribed
-     */
-    isSubscribed(consumerId: string): boolean;
-    /**
-     * Push a track stream into the broadcast (internal API for MusicQueue)
-     * @param stream Audio stream
-     * @param metadata Track metadata
-     */
-    pushTrack(stream: Readable, metadata: BroadcastTrackMetadata): Promise<void>;
-    /**
-     * Start silence generation (internal API)
-     */
-    startSilence(): void;
-    /**
-     * Stop the broadcast (internal API)
-     */
-    stop(): void;
-    /**
-     * Destroy the broadcast and clean up resources
-     */
-    destroy(): void;
-    /**
-     * Get statistics about the broadcast
-     */
-    getStats(): {
-        state: BroadcastState;
-        subscriberCount: number;
-        consumerStats: Map<string, {
-            droppedFrames: number;
-            totalFrames: number;
-        }>;
-    };
-    /**
-     * Map StreamCore state to BroadcastState
-     */
-    private mapCoreStateToBroadcastState;
-}
-
-interface AudioCacheKey {
-    artist?: string;
-    album?: string;
-    song: string;
-    quality: "low" | "medium" | "high" | "highest";
-    url: string;
-}
-/**
- * Audio cache service that downloads, converts, and caches audio files
- *
- * ## Overview
- * This service manages a file-based cache of audio files downloaded from YouTube.
- * Audio is downloaded using yt-dlp and converted to OGG Opus format, which is:
- * - Native to Discord voice (no transcoding needed)
- * - Efficiently compressed (smaller cache size)
- * - High quality (VBR encoding)
- * - Web-compatible (supported by modern browsers)
- *
- * ## Caching Strategy
- * Files are cached based on artist/album/song/quality and stored in the configured
- * cache directory. Each cached file includes metadata (duration, bitrate, etc.)
- * obtained via ffprobe.
- *
- * ## Stream Handling (CRITICAL)
- * ⚠️ This service creates clean, unmodified file streams. DO NOT add event listeners
- * or call resume() on these streams - adding listeners (especially 'readable' and 'data')
- * puts streams into paused mode and prevents Discord.js from controlling stream flow.
- *
- * Let the consumer (Discord.js) handle all stream control, probing, and consumption.
- *
- * @example
- * ```typescript
- * const cache = new AudioCacheService('/path/to/cache');
- * const key = { song: 'Track Name', quality: 'high', url: 'https://...' };
- * const stream = await cache.getAudioStream(key, 'https://youtube.com/...');
- * // Pass stream directly to Discord.js - don't touch it!
- * voiceManager.playAudio(stream, { guildId, channel });
- * ```
- */
-declare class AudioCacheService {
-    private cacheDir;
-    private readonly CACHE_TTL;
-    private cacheIndex;
-    constructor(cacheDir?: string);
-    /**
-     * Generate cache key from track metadata
-     */
-    private generateCacheKey;
-    /**
-     * Simple hash function for URLs
-     */
-    private hashString;
-    /**
-     * Extract YouTube video ID from various URL formats
-     * WHY: YouTube URLs can come in many forms but point to the same video:
-     * - https://www.youtube.com/watch?v=ABC123
-     * - https://youtube.com/watch?v=ABC123
-     * - https://youtu.be/ABC123
-     * - https://www.youtube.com/watch?v=ABC123&list=PLxyz&index=1
-     *
-     * We need to normalize these to get consistent cache keys
-     */
-    private extractYouTubeVideoId;
-    /**
-     * Normalize URL for consistent caching
-     * WHY: Same video can have different URL formats - we want them to hit the same cache entry
-     */
-    private normalizeUrlForCache;
-    /**
-     * Get cache file path for a key
-     */
-    private getCacheFilePath;
-    /**
-     * Check if audio is cached (checks all supported formats)
-     */
-    isCached(key: AudioCacheKey): boolean;
-    /**
-     * Find cached audio by URL (searches all cached files)
-     * This is useful when you only have the URL and don't know the exact cache key
-     */
-    findCachedAudioByUrl(url: string, quality?: "low" | "medium" | "high" | "highest"): Promise<Readable | null>;
-    /**
-     * Get cached audio file as a readable stream
-     *
-     * Returns a clean file stream with NO event listeners attached (except error handling).
-     * The stream is in paused mode by default - the consumer must control flow.
-     *
-     * ⚠️ WARNING: Do not add event listeners or call resume() on the returned stream.
-     * Adding listeners puts the stream in paused mode and prevents proper playback.
-     * Let Discord.js handle all stream control.
-     *
-     * @param key - Cache key identifying the audio file
-     * @returns Clean readable stream, or null if not cached/invalid
-     */
-    getCachedAudio(key: AudioCacheKey): Promise<Readable | null>;
-    /**
-     * Download and cache audio from YouTube URL
-     *
-     * Uses yt-dlp to download audio and convert to the configured format.
-     * yt-dlp automatically invokes ffmpeg for format conversion.
-     *
-     * ## Process
-     * 1. Check if already cached (skip if so)
-     * 2. Download audio using yt-dlp with quality settings
-     * 3. Convert to configured format (default: Opus, configurable via AUDIO_CACHE_FORMAT)
-     * 4. Probe metadata with ffprobe (duration, bitrate, etc.)
-     * 5. Update cache index
-     *
-     * ## Supported Formats
-     * - opus: Discord-optimized, lossy but high quality (default)
-     * - flac: Lossless format, prevents additional quality loss from lossy-to-lossy conversions (larger files)
-     *   Even though YouTube source is lossy, FLAC preserves the best quality available and prevents
-     *   further degradation from multiple lossy conversions (e.g., Opus→Opus or Opus→MP3)
-     * - wav: Uncompressed lossless (very large files)
-     * - mp3: Lossy, widely compatible
-     * - m4a: Lossy, Apple format
-     *
-     * Set AUDIO_CACHE_FORMAT environment variable to choose format (e.g., export AUDIO_CACHE_FORMAT=flac)
-     *
-     * Note: Using FLAC prevents quality loss from lossy-to-lossy transcoding, preserving the best
-     * quality available from the YouTube source even if the source itself is lossy.
-     *
-     * ## Quality Mapping
-     * - low: worst available audio
-     * - medium: up to 128kbps
-     * - high: up to 192kbps
-     * - highest: best available audio
-     *
-     * Note: FLAC is lossless, so quality settings don't apply (preserves source quality)
-     *
-     * @param key - Cache key for the audio
-     * @param youtubeUrl - YouTube URL to download from
-     * @returns Path to cached file
-     * @throws Error if yt-dlp/ffmpeg not installed, download fails, or file invalid
-     */
-    downloadAndCache(key: AudioCacheKey, youtubeUrl: string): Promise<string>;
-    /**
-     * Get or download audio (returns file path)
-     */
-    getOrDownload(key: AudioCacheKey, youtubeUrl: string): Promise<string>;
-    /**
-     * Resolve the on-disk file path for a cached track by URL (any quality/format).
-     * Returns null when the file has not been cached yet or is expired.
-     */
-    findCachedFilePathByUrl(url: string): string | null;
-    /**
-     * Get cached audio as stream, or download and return stream
-     */
-    getAudioStream(key: AudioCacheKey, youtubeUrl: string): Promise<Readable>;
-    /**
-     * Probe audio file using ffprobe to get metadata
-     */
-    private probeAudioFile;
-    /**
-     * Load cache index from filesystem
-     */
-    private loadCacheIndex;
-    /**
-     * Clean up expired cache entries
-     */
-    private cleanExpiredCache;
-    /**
-     * Get cache statistics
-     */
-    getCacheStats(): {
-        totalFiles: number;
-        totalSize: number;
-        oldestEntry: number | null;
-        newestEntry: number | null;
-    };
-    /**
-     * Clear all cache
-     */
-    clearCache(): void;
-    /**
-     * Get audio metadata for a cached file (returns undefined if not cached)
-     */
-    getAudioMetadata(key: AudioCacheKey): Promise<{
-        bitrate?: number;
-        format?: string;
-        sampleRate?: number;
-        channels?: number;
-        size?: number;
-        duration?: number;
-    } | undefined>;
-}
-
-interface VoicePlaybackHandle {
-    finished?: Promise<void>;
-}
-/** Minimal voice pipeline from plugin-discord (avoids hard dependency here). */
-interface VoiceManagerLike {
-    stopAudio(guildId: string, channel: number): Promise<void>;
-    pauseAudio(guildId: string, channel: number): Promise<void>;
-    resumeAudio(guildId: string, channel: number): Promise<void>;
-    isPlaying(guildId: string, channel: number): Promise<boolean>;
-    on(event: "audio:finished", handler: (data: {
-        guildId: string;
-        channel: number;
-    }) => void): void;
-    off(event: "audio:finished", handler: (data: {
-        guildId: string;
-        channel: number;
-    }) => void): void;
-    playAudio(stream: Readable, options: {
-        guildId: string;
-        channel: number;
-        volume?: number;
-        metadata?: Record<string, unknown>;
-    }): Promise<VoicePlaybackHandle>;
-}
-/**
- * Represents a track in the music queue
- */
-interface QueuedTrack {
-    id: string;
-    url: string;
-    title: string;
-    duration?: number;
-    requestedBy?: string;
-    dedicatedTo?: string;
-    dedicationMessage?: string;
-    addedAt: number;
-    stream?: Readable;
-    audioMetadata?: {
-        bitrate?: number;
-        format?: string;
-        sampleRate?: number;
-        channels?: number;
-        size?: number;
-    };
-}
-/**
- * Options for cross-fading between tracks
- */
-interface CrossFadeOptions {
-    enabled: boolean;
-    duration: number;
-}
-/**
- * Music queue manager with cross-fading support
- */
-declare class MusicQueue extends EventEmitter {
-    private queue;
-    private currentTrack;
-    private currentPlaybackHandle;
-    private isPlaying;
-    private isPaused;
-    private guildId;
-    private voiceManager;
-    private crossFadeOptions;
-    private nextTrackPreBuffered;
-    private readonly MUSIC_CHANNEL;
-    private continuousStream;
-    private nextTrackStream;
-    private preBufferTimeout;
-    private trackPlayedCallback;
-    private audioCache;
-    private runtime;
-    private broadcast;
-    constructor(guildId: string, voiceManager: VoiceManagerLike | null, runtime?: IAgentRuntime, audioCache?: AudioCacheService);
-    /**
-     * Set the broadcast for this queue (new architecture)
-     * @param broadcast Broadcast instance to push audio to
-     */
-    setBroadcast(broadcast: Broadcast): void;
-    /**
-     * Register callback for when a track finishes playing
-     */
-    onTrackPlayed(callback: (track: QueuedTrack, duration: number) => Promise<void>): void;
-    /**
-     * Set cross-fade options
-     */
-    setCrossFadeOptions(options: Partial<CrossFadeOptions>): void;
-    /**
-     * Add a track to the queue
-     */
-    addTrack(track: Omit<QueuedTrack, "id" | "addedAt">): Promise<QueuedTrack>;
-    /**
-     * Remove a track from the queue
-     */
-    removeTrack(trackId: string): boolean;
-    /**
-     * Skip the current track.
-     * Works for both legacy voiceManager and broadcast architectures.
-     */
-    skip(): Promise<boolean>;
-    /**
-     * Pause playback.
-     * For Discord voice: delegates to voiceManager.pauseAudio.
-     * For broadcast (web): stops the broadcast StreamCore so HTTP clients
-     * stop receiving new audio frames (they stay connected but hear silence).
-     */
-    pause(): Promise<void>;
-    /**
-     * Resume playback.
-     * For Discord voice: delegates to voiceManager.resumeAudio.
-     * For broadcast (web): re-pushes the current track metadata so clients
-     * know playback resumed. The actual audio stream is still wired; calling
-     * broadcast.startSilence() unblocks the pipeline and the next pushTrack
-     * will pick it back up.
-     */
-    resume(): Promise<void>;
-    /**
-     * Stop playback and clear queue.
-     * Stops both legacy voiceManager and broadcast paths so all consumers
-     * (Discord voice + HTTP stream clients) stop receiving audio.
-     */
-    stop(): Promise<void>;
-    /**
-     * Clear the queue
-     */
-    clear(): void;
-    /**
-     * Shuffle the queue
-     */
-    shuffle(): void;
-    /**
-     * Get the queue
-     */
-    getQueue(): QueuedTrack[];
-    /**
-     * Get the current track
-     */
-    getCurrentTrack(): QueuedTrack | null;
-    /**
-     * Get whether playback is active
-     */
-    getIsPlaying(): boolean;
-    /**
-     * Get whether playback is paused
-     */
-    getIsPaused(): boolean;
-    /**
-     * Get the continuous stream
-     */
-    getContinuousStream(): PassThrough | null;
-    /**
-     * Get audio stream for a track (cached or download)
-     * Tries cache first (title-based, then URL-based), then downloads if not cached.
-     * @param track - Track to get stream for
-     * @param shouldCache - Whether to cache downloaded streams (default: true)
-     * @returns Audio stream or null if failed
-     */
-    private getAudioStreamForTrack;
-    /**
-     * Clean up pre-buffered stream
-     */
-    private cleanupPreBufferedStream;
-    /**
-     * Pre-buffer the next track for cross-fading
-     */
-    private preBufferNextTrack;
-    /**
-     * Play the next track in the queue
-     */
-    private playNext;
-}
-
-/**
- * Compatibility fallback for `/music-player/status`.
- *
- * The UI polls this route even when plugin-music-player is not enabled. When the
- * plugin route is absent, returning a stable JSON payload is better than a noisy
- * 404 loop in desktop logs.
- */
-declare function tryHandleMusicPlayerStatusFallback(options: {
-    pathname: string;
-    method: string;
-    runtime: AgentRuntime | null | undefined;
-    res: ServerResponse;
-}): boolean;
-
-/** Minimal VoiceTarget shape — avoids hard dep on @elizaos/plugin-discord. */
-interface VoiceTarget {
-    id: string;
-    type: string;
-    guildId?: string;
-    channelId?: string;
-    play?: (stream: Readable, opts?: Record<string, unknown>) => Promise<unknown>;
-    playAudio?: (stream: Readable, opts?: Record<string, unknown>) => Promise<unknown>;
-    feed?: (stream: Readable) => Promise<unknown>;
-    stop?: () => Promise<unknown>;
-    stopAudio?: () => Promise<unknown>;
-    [key: string]: unknown;
-}
-/**
- * Audio routing mode
- */
-type AudioRoutingMode = "simulcast" | "independent";
-/**
- * Configuration for audio routing
- */
-interface AudioRouteConfig {
-    sourceId: string;
-    targetIds: string[];
-    mode?: AudioRoutingMode;
-}
-/**
- * AudioRouter manages routing of audio streams to multiple voice targets
- * Supports both simulcast (same stream to all) and independent (separate streams) modes
- */
-declare class AudioRouter {
-    private routes;
-    private defaultMode;
-    private targetRegistry;
-    constructor(defaultMode?: AudioRoutingMode);
-    /**
-     * Register voice targets for routing
-     */
-    registerTargets(targets: VoiceTarget[]): void;
-    /**
-     * Unregister voice targets
-     */
-    unregisterTarget(targetId: string): void;
-    /**
-     * Get registered target by ID
-     */
-    getTarget(targetId: string): VoiceTarget | undefined;
-    /**
-     * Route an audio stream to multiple targets
-     * @param sourceId Unique identifier for the audio source
-     * @param stream The audio stream to route
-     * @param targetIds Array of target IDs to route to
-     * @param mode Routing mode (defaults to configured default)
-     */
-    route(sourceId: string, stream: Readable, targetIds: string[], mode?: AudioRoutingMode, onCleanup?: () => void): Promise<void>;
-    /**
-     * Simulcast mode: Clone single stream to all targets
-     * Uses PassThrough streams to multiplex
-     */
-    private routeSimulcast;
-    /**
-     * Independent mode: Separate streams per target
-     * Note: This requires the source to provide multiple independent streams
-     * For now, this will use the same stream but track separately
-     */
-    private routeIndependent;
-    /**
-     * Stop routing for a source
-     */
-    unroute(sourceId: string): Promise<void>;
-    /**
-     * Stop all active routes
-     */
-    unrouteAll(): Promise<void>;
-    /**
-     * Get active routes
-     */
-    getActiveRoutes(): Array<{
-        sourceId: string;
-        targetIds: string[];
-        mode: AudioRoutingMode;
-    }>;
-    /**
-     * Set default routing mode
-     */
-    setDefaultMode(mode: AudioRoutingMode): void;
-    /**
-     * Get default routing mode
-     */
-    getDefaultMode(): AudioRoutingMode;
-    /**
-     * Get all registered routing target IDs
-     */
-    getRegisteredTargetIds(): string[];
-    /**
-     * Check if a source is currently routed
-     */
-    isRouted(sourceId: string): boolean;
-    /**
-     * Get route info for a source
-     */
-    getRoute(sourceId: string): {
-        sourceId: string;
-        targetIds: string[];
-        mode: AudioRoutingMode;
-    } | undefined;
-    /**
-     * Add target to existing route
-     */
-    addTargetToRoute(sourceId: string, targetId: string): Promise<void>;
-    /**
-     * Remove target from existing route
-     */
-    removeTargetFromRoute(sourceId: string, targetId: string): Promise<void>;
-    private startTargetPlayback;
-    private stopTargetPlayback;
-}
-
-/**
- * Configuration for a mix session
- */
-interface MixConfig {
-    name: string;
-    zones: Record<string, string[]>;
-    routing?: {
-        mode: AudioRoutingMode;
-        mappings: Record<string, string[]>;
-    };
-    autoCleanup?: boolean;
-    cleanupDelay?: number;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Active mix session state
- */
-interface MixSession {
-    id: string;
-    config: MixConfig;
-    startedAt: number;
-    cleanupTimeout?: NodeJS.Timeout;
-}
-/**
- * MixSessionManager handles runtime mixing configurations
- * Manages temporary bot assignments, routing, and auto-cleanup
- */
-declare class MixSessionManager {
-    private sessions;
-    private runtime;
-    constructor(runtime: IAgentRuntime);
-    /**
-     * Start a new mix session
-     * @param config Mix configuration
-     * @returns Created session
-     */
-    start(config: MixConfig): Promise<MixSession>;
-    /**
-     * End a mix session
-     * @param sessionId Session ID to end
-     */
-    end(sessionId: string): Promise<void>;
-    /**
-     * Update an existing session
-     * @param sessionId Session ID to update
-     * @param config Partial configuration to update
-     */
-    update(sessionId: string, config: Partial<MixConfig>): Promise<MixSession>;
-    /**
-     * Get a session by ID
-     */
-    get(sessionId: string): MixSession | undefined;
-    /**
-     * Get all active sessions
-     */
-    list(): MixSession[];
-    /**
-     * Find sessions by name
-     */
-    findByName(name: string): MixSession[];
-    /**
-     * End all sessions
-     */
-    endAll(): Promise<void>;
-    /**
-     * Check if a session exists
-     */
-    exists(sessionId: string): boolean;
-    /**
-     * Get active session count
-     */
-    count(): number;
-    /**
-     * Extend session cleanup timer
-     * @param sessionId Session ID
-     * @param additionalTime Additional time in milliseconds
-     */
-    extendSession(sessionId: string, additionalTime: number): void;
-    /**
-     * Cancel auto-cleanup for a session
-     */
-    cancelAutoCleanup(sessionId: string): void;
-    /**
-     * Save session to agent memory
-     * @private
-     */
-    private saveToMemory;
-    /**
-     * Remove session from agent memory
-     * @private
-     */
-    private removeFromMemory;
-    /**
-     * Load sessions from agent memory on startup
-     */
-    loadFromMemory(): Promise<void>;
-    /**
-     * Get session duration in milliseconds
-     */
-    getSessionDuration(sessionId: string): number;
-    /**
-     * Get session info summary
-     */
-    getSessionInfo(sessionId: string): {
-        id: string;
-        name: string;
-        duration: number;
-        zoneCount: number;
-        hasAutoCleanup: boolean;
-    } | undefined;
-}
-
-/**
- * A named group of voice targets
- */
-interface Zone {
-    name: string;
-    targetIds: string[];
-    createdAt: number;
-    metadata?: Record<string, unknown>;
-}
-/**
- * ZoneManager manages logical groupings of voice targets
- * Zones allow routing audio to named collections of targets
- */
-declare class ZoneManager {
-    private zones;
-    /**
-     * Create a new zone
-     * @param name Zone name
-     * @param targetIds Array of target IDs in this zone
-     * @param metadata Optional metadata for the zone
-     */
-    create(name: string, targetIds: string[], metadata?: Record<string, unknown>): Zone;
-    /**
-     * Delete a zone
-     */
-    delete(name: string): boolean;
-    /**
-     * Get a zone by name
-     */
-    get(name: string): Zone | undefined;
-    /**
-     * Get all zones
-     */
-    list(): Zone[];
-    /**
-     * Check if a zone exists
-     */
-    exists(name: string): boolean;
-    /**
-     * Add target to a zone
-     */
-    addTarget(zoneName: string, targetId: string): void;
-    /**
-     * Remove target from a zone
-     */
-    removeTarget(zoneName: string, targetId: string): void;
-    /**
-     * Get all target IDs in a zone
-     */
-    getTargets(zoneName: string): string[];
-    /**
-     * Update zone metadata
-     */
-    updateMetadata(zoneName: string, metadata: Record<string, unknown>): void;
-    /**
-     * Find all zones containing a specific target
-     */
-    findZonesWithTarget(targetId: string): Zone[];
-    /**
-     * Clear all zones
-     */
-    clear(): void;
-    /**
-     * Get zone count
-     */
-    count(): number;
-    /**
-     * Merge multiple zones into a new zone
-     */
-    merge(newZoneName: string, zoneNames: string[]): Zone;
-    /**
-     * Clone a zone with a new name
-     */
-    clone(sourceName: string, newName: string): Zone;
-    /**
-     * Get targets that are in multiple zones (intersection)
-     */
-    getIntersection(zoneNames: string[]): string[];
-    /**
-     * Get all unique targets across multiple zones (union)
-     */
-    getUnion(zoneNames: string[]): string[];
-}
-
-interface RoutingTarget {
-    id: string;
-    type: string;
-    guildId?: string;
-    channelId?: string;
-    play?: (stream: NodeJS.ReadableStream, opts?: Record<string, unknown>) => Promise<unknown>;
-    playAudio?: (stream: NodeJS.ReadableStream, opts?: Record<string, unknown>) => Promise<unknown>;
-    feed?: (stream: NodeJS.ReadableStream) => Promise<unknown>;
-    stop?: () => Promise<unknown>;
-    stopAudio?: () => Promise<unknown>;
-    [key: string]: unknown;
-}
-/**
- * Music service that manages music queues and playback
- * Pure playback engine - analytics/preferences are optional via music-library plugin
- */
-declare class MusicService extends Service {
-    static serviceType: string;
-    capabilityDescription: string;
-    private queues;
-    private broadcasts;
-    private voiceManager;
-    private audioCache;
-    private readonly audioRouter;
-    private readonly zoneManager;
-    constructor(runtime?: IAgentRuntime);
-    static start(runtime: IAgentRuntime): Promise<MusicService>;
-    stop(): Promise<void>;
-    /**
-     * Initialize the service with voice manager
-     */
-    setVoiceManager(voiceManager: VoiceManagerLike): void;
-    getAudioRouter(): AudioRouter;
-    getZoneManager(): ZoneManager;
-    setRoutingMode(mode: AudioRoutingMode): void;
-    getRoutingMode(): AudioRoutingMode;
-    registerRoutingTargets(targets: RoutingTarget[]): void;
-    unregisterRoutingTarget(targetId: string): void;
-    listRoutingTargets(): string[];
-    startBroadcastRoute(sourceId: string, targetIds: string[], mode?: AudioRoutingMode): Promise<{
-        sourceId: string;
-        targetIds: string[];
-        mode: AudioRoutingMode;
-    }>;
-    stopBroadcastRoute(sourceId: string): Promise<void>;
-    getRoutingStatus(): {
-        mode: AudioRoutingMode;
-        activeRoutes: Array<{
-            sourceId: string;
-            targetIds: string[];
-            mode: AudioRoutingMode;
-        }>;
-        registeredTargets: string[];
-        zoneCount: number;
-    };
-    /**
-     * Get or create a queue for a guild
-     */
-    getQueue(guildId: string): MusicQueue;
-    /**
-     * Get all queues (for external monitoring)
-     */
-    getQueues(): Map<string, MusicQueue>;
-    /**
-     * Get audio cache service
-     */
-    getAudioCache(): AudioCacheService;
-    /**
-     * Add a track to the queue
-     */
-    addTrack(guildId: string, track: Omit<QueuedTrack, "id" | "addedAt">): Promise<QueuedTrack>;
-    /**
-     * Skip current track
-     */
-    skip(guildId: string, skipperEntityId?: UUID): Promise<boolean>;
-    /**
-     * Pause playback
-     */
-    pause(guildId: string): Promise<void>;
-    /**
-     * Resume playback
-     */
-    resume(guildId: string): Promise<void>;
-    /**
-     * Stop playback for a specific guild
-     */
-    stopPlayback(guildId: string): Promise<void>;
-    /**
-     * Clear queue
-     */
-    clear(guildId: string): void;
-    /**
-     * Get queue
-     */
-    getQueueList(guildId: string): QueuedTrack[];
-    /**
-     * Get current track
-     */
-    getCurrentTrack(guildId: string): QueuedTrack | null;
-    /**
-     * Get or create a broadcast for a guild
-     * Broadcasts provide a clean interface for multiple consumers (Discord, Web, etc.)
-     * to subscribe to the audio stream independently.
-     * @param guildId Guild/server ID
-     * @returns IAudioBroadcast instance
-     */
-    getBroadcast(guildId: string): IAudioBroadcast;
-    /**
-     * Remove a track from queue
-     */
-    removeTrack(guildId: string, trackId: string): boolean;
-    /**
-     * Shuffle queue
-     */
-    shuffle(guildId: string): void;
-    /**
-     * Get whether queue is currently playing
-     */
-    getIsPlaying(guildId: string): boolean;
-    /**
-     * Get whether playback is paused
-     */
-    getIsPaused(guildId: string): boolean;
-    /**
-     * Handle track played event (optional analytics integration)
-     */
-    private handleTrackPlayed;
-    /**
-     * Helper to get roomId from guildId via Discord service
-     */
-    private getRoomIdFromGuild;
-    /**
-     * Update Discord listening activity to show currently playing track
-     */
-    private updateDiscordListeningActivity;
-    /**
-     * Clear Discord activity when music stops
-     */
-    private clearDiscordActivity;
-    /**
-     * Auto-subscribe Discord to broadcast (enables new architecture without requiring radio plugin)
-     *
-     * WHY AUTO-WIRING:
-     * Design goal: music-player + discord should work together WITHOUT needing radio plugin.
-     * Radio can add advanced features, but shouldn't be required for basic playback.
-     *
-     * THE CHALLENGE:
-     * - MusicQueue pushes audio to broadcast
-     * - Discord needs to subscribe to broadcast
-     * - But music-player shouldn't import discord plugin (circular dependency)
-     *
-     * THE SOLUTION:
-     * When a track starts, MusicService (which has access to runtime) checks:
-     * 1. Is discord service available? (optional dependency)
-     * 2. Is Discord connected to this guild?
-     * 3. If yes, auto-subscribe Discord to the broadcast
-     * 4. If not yet connected, attach listener to subscribe when it connects
-     *
-     * This happens transparently - user just plays music, and it works.
-     *
-     * WHY HANDLE RECONNECTS HERE:
-     * Discord will emit status changes (connected/disconnected). MusicService listens
-     * and auto-resubscribes on reconnect. This keeps the reconnection logic in one place.
-     *
-     * GRACEFUL DEGRADATION:
-     * If discord service doesn't exist, or doesn't support IAudioSink, this silently
-     * does nothing. Old architecture keeps working.
-     */
-    private autoSubscribeDiscord;
-}
-
-interface DetectedMusicEntity {
-    type: "artist" | "album" | "song";
-    name: string;
-    confidence: number;
-    context?: string;
-}
-/**
- * Service for detecting music entity names (artists, albums, songs) from text
- * Uses LLM for intelligent extraction with caching
- */
-declare class MusicEntityDetectionHelper {
-    capabilityDescription: string;
-    private cache;
-    private readonly CACHE_TTL;
-    private readonly runtime?;
-    constructor(runtime?: IAgentRuntime);
-    stop(): Promise<void>;
-    /**
-     * Detect music entities from text using LLM
-     */
-    detectEntities(text: string): Promise<DetectedMusicEntity[]>;
-    /**
-     * Clear cache
-     */
-    clearCache(): void;
-    /**
-     * Clear expired cache entries
-     */
-    clearExpiredCache(): void;
-}
-
-/**
- * Audio features data structure for music tracks
- * Based on Spotify's audio features API
- */
-interface AudioFeatures {
-    trackId?: string;
-    danceability: number;
-    energy: number;
-    valence: number;
-    acousticness: number;
-    instrumentalness: number;
-    liveness: number;
-    speechiness: number;
-    key: number;
-    mode: number;
-    tempo: number;
-    timeSignature: number;
-    loudness: number;
-    duration: number;
-    source?: "spotify" | "computed" | "manual";
-}
-/**
- * Simplified audio features for recommendations
- */
-interface AudioFeatureSeed {
-    targetDanceability?: number;
-    targetEnergy?: number;
-    targetValence?: number;
-    targetTempo?: number;
-    targetLoudness?: number;
-    targetAcousticness?: number;
-    targetInstrumentalness?: number;
-    targetPopularity?: number;
-}
-/**
- * Track recommendation request
- */
-interface RecommendationRequest {
-    seedArtists?: string[];
-    seedTracks?: string[];
-    seedGenres?: string[];
-    audioFeatures?: AudioFeatureSeed;
-    limit?: number;
-}
-/**
- * Track recommendation result
- */
-interface TrackRecommendation {
-    trackName: string;
-    artistName: string;
-    albumName?: string;
-    url?: string;
-    previewUrl?: string;
-    audioFeatures?: AudioFeatures;
-    popularity?: number;
-}
-
-/**
- * Music information types
- */
-interface TrackInfo {
-    title: string;
-    artist: string;
-    album?: string;
-    duration?: number;
-    genre?: string[];
-    year?: number;
-    url?: string;
-    thumbnail?: string;
-    description?: string;
-    tags?: string[];
-    lyrics?: string;
-    lyricsUrl?: string;
-}
-interface ArtistInfo {
-    name: string;
-    genres?: string[];
-    bio?: string;
-    image?: string;
-    imageThumb?: string;
-    imageLogo?: string;
-    imageFanart?: string;
-    imageBanner?: string;
-    similarArtists?: string[];
-    albums?: string[];
-    topTracks?: string[];
-}
-interface AlbumInfo {
-    title: string;
-    artist: string;
-    year?: number;
-    genre?: string[];
-    tracks?: string[];
-    coverArt?: string;
-    coverArtThumb?: string;
-    coverArtCD?: string;
-    description?: string;
-}
-interface MusicInfoResult {
-    track?: TrackInfo;
-    artist?: ArtistInfo;
-    album?: AlbumInfo;
-    source: "youtube" | "spotify" | "lastfm" | "musicbrainz" | "wikipedia" | "genius" | "theaudiodb";
-}
-
-/**
- * Service status tracking for music info services
- */
-declare enum ServiceStatus {
-    ACTIVE = "active",
-    DEGRADED = "degraded",// Available but experiencing issues
-    UNAVAILABLE = "unavailable",
-    NOT_CONFIGURED = "not_configured"
-}
-interface ServiceHealth {
-    status: ServiceStatus;
-    lastChecked: number;
-    lastError?: string;
-    responseTime?: number;
-}
-interface MusicInfoServiceStatus {
-    musicBrainz: ServiceHealth;
-    lastFm: ServiceHealth;
-    genius: ServiceHealth;
-    theAudioDb: ServiceHealth;
-    wikipedia: ServiceHealth;
-}
-
-/**
- * Service for Wikipedia API access
- * Free, no authentication required
- * Rate limit: 2 requests per second (shared across all agents per instance)
- */
-declare class WikipediaClient {
-    capabilityDescription: string;
-    private readonly baseUrl;
-    private readonly searchUrl;
-    private readonly rateLimiter;
-    stop(): Promise<void>;
-    /**
-     * Search for a Wikipedia page and get summary
-     */
-    private getPageSummary;
-    /**
-     * Search Wikipedia for pages matching a query
-     */
-    private searchPages;
-    /**
-     * Get track information from Wikipedia
-     */
-    getTrackInfo(trackName: string, artistName?: string): Promise<TrackInfo | null>;
-    /**
-     * Get artist information from Wikipedia
-     */
-    getArtistInfo(artistName: string): Promise<ArtistInfo | null>;
-    /**
-     * Get album information from Wikipedia
-     */
-    getAlbumInfo(albumTitle: string, artistName?: string): Promise<AlbumInfo | null>;
-    /**
-     * Clean Wikipedia extract text (remove HTML, truncate)
-     */
-    private cleanExtract;
-    /**
-     * Try to extract artist name from Wikipedia extract
-     */
-    private extractArtistFromExtract;
-    /**
-     * Extract related artists, influences, and similar acts from Wikipedia extract
-     * Looks for patterns like "influenced by", "similar to", "associated acts", etc.
-     * This data helps drive intelligent music selection and discovery
-     */
-    private extractRelatedArtists;
-}
-
-/**
- * Service for fetching music information from authoritative sources.
- * Track metadata comes from YouTube for direct URLs and MusicBrainz for
- * text queries; artist and album metadata comes from MusicBrainz only.
- */
-declare class MusicInfoHelper {
-    capabilityDescription: string;
-    private cache;
-    private readonly CACHE_TTL;
-    private musicBrainzClient;
-    private lastFmClient;
-    private geniusClient;
-    private theAudioDbClient;
-    private readonly wikipediaClient;
-    private serviceStatus;
-    constructor(runtime?: IAgentRuntime, wikipediaClient?: WikipediaClient | null);
-    stop(): Promise<void>;
-    /**
-     * Get service status for all integrated APIs
-     */
-    getServiceStatus(): MusicInfoServiceStatus;
-    /**
-     * Validate API keys for all configured services
-     * Updates service status based on validation results
-     */
-    private validateApiKeys;
-    /**
-     * Extract track information from a YouTube URL or MusicBrainz lookup.
-     */
-    getTrackInfo(urlOrTitle: string): Promise<MusicInfoResult | null>;
-    /**
-     * Parse title string to extract artist and track name
-     */
-    private parseTitle;
-    /**
-     * Get artist information from MusicBrainz.
-     */
-    getArtistInfo(artistName: string): Promise<ArtistInfo | null>;
-    /**
-     * Get album information from MusicBrainz.
-     */
-    getAlbumInfo(albumTitle: string, artistName?: string): Promise<AlbumInfo | null>;
-    /**
-     * Check if a string is a YouTube URL
-     */
-    private isYouTubeUrl;
-    /**
-     * Extract information from YouTube URL using play-dl
-     */
-    private getInfoFromYouTube;
-    /**
-     * Clear cache
-     */
-    clearCache(): void;
-    /**
-     * Clear expired cache entries
-     */
-    clearExpiredCache(): void;
-    /**
-     * Pre-warm cache for a track (non-blocking)
-     * This is called by plugin-dj to prepare caches before tracks are played
-     * @param urlOrTitle - YouTube URL or track title
-     */
-    prewarmTrackInfo(urlOrTitle: string): Promise<void>;
-    /**
-     * Pre-warm cache for multiple tracks (non-blocking)
-     * @param tracks - Array of YouTube URLs or track titles
-     */
-    prewarmTracks(tracks: string[]): Promise<void>;
-}
-
-/**
- * Client for Spotify Web API
- * Provides access to audio features and track recommendations
- */
-declare class SpotifyClient {
-    private clientId;
-    private clientSecret;
-    private token;
-    private baseUrl;
-    private authUrl;
-    private lastRequestTime;
-    private minRequestInterval;
-    constructor(clientId?: string, clientSecret?: string);
-    /**
-     * Check if API credentials are configured
-     */
-    isConfigured(): boolean;
-    /**
-     * Get or refresh access token
-     */
-    private getAccessToken;
-    /**
-     * Rate limiting helper
-     */
-    private rateLimit;
-    /**
-     * Search for a track on Spotify
-     */
-    searchTrack(query: string): Promise<string | null>;
-    /**
-     * Get audio features for a track
-     */
-    getAudioFeatures(trackId: string): Promise<AudioFeatures | null>;
-    /**
-     * Get audio features for a track by search query
-     */
-    getAudioFeaturesByQuery(query: string): Promise<AudioFeatures | null>;
-    /**
-     * Get track recommendations
-     */
-    getRecommendations(request: RecommendationRequest): Promise<TrackRecommendation[]>;
-    /**
-     * Validate API credentials
-     */
-    validateCredentials(): Promise<boolean>;
-}
-
-interface WikipediaExtractionContext {
-    purpose: "dj_intro" | "music_selection" | "general_info" | "related_artists";
-    currentArtist?: string;
-    currentTrack?: string;
-    currentAlbum?: string;
-}
-interface ExtractedMusicInfo {
-    artist?: Partial<ArtistInfo>;
-    track?: Partial<TrackInfo>;
-    album?: Partial<AlbumInfo>;
-    relatedArtists?: string[];
-    influences?: string[];
-    genres?: string[];
-    interestingFacts?: string[];
-    selectionSuggestions?: string[];
-}
-/**
- * Service that uses LLMs to dynamically extract relevant information from Wikipedia
- * Based on context (e.g., DJ intro, music selection), extracts different information
- */
-declare class WikipediaExtractionHelper {
-    capabilityDescription: string;
-    private cache;
-    private readonly CACHE_TTL;
-    private readonly runtime?;
-    private readonly wikipediaClient;
-    constructor(runtime?: IAgentRuntime, wikipediaClient?: WikipediaClient | null);
-    private getWikipediaService;
-    stop(): Promise<void>;
-    /**
-     * Extract music information from Wikipedia using LLM based on context
-     */
-    extractFromWikipedia(entityName: string, entityType: "artist" | "album" | "song", context: WikipediaExtractionContext): Promise<ExtractedMusicInfo | null>;
-    /**
-     * Build extraction prompt based on context
-     */
-    private buildExtractionPrompt;
-    /**
-     * Parse LLM extraction response
-     */
-    private parseExtractionResponse;
-    /**
-     * Extract list items from text using pattern
-     */
-    private extractList;
-    /**
-     * Clear cache
-     */
-    clearCache(): void;
-    /**
-     * Clear expired cache entries
-     */
-    clearExpiredCache(): void;
-}
-
-interface YouTubeSearchResult {
-    url: string;
-    title: string;
-    duration?: number;
-    channel?: string;
-    views?: number;
-}
-/**
- * Service for searching YouTube videos
- * Centralizes YouTube search logic for reuse across multiple actions
- */
-declare class YouTubeSearchHelper {
-    capabilityDescription: string;
-    private cache;
-    private readonly CACHE_TTL;
-    stop(): Promise<void>;
-    /**
-     * Clear all cached searches
-     */
-    clearCache(): void;
-    /**
-     * Search YouTube for videos
-     * @param query - Search query string
-     * @param options - Search options
-     * @returns Array of search results
-     */
-    search(query: string, options?: {
-        limit?: number;
-        includeShorts?: boolean;
-    }): Promise<YouTubeSearchResult[]>;
-    /**
-     * Search and return the top result
-     * @param query - Search query
-     * @returns Top search result or null
-     */
-    searchOne(query: string): Promise<YouTubeSearchResult | null>;
-    /**
-     * Validate if a URL is a valid YouTube video
-     */
-    validateUrl(url: string): Promise<boolean>;
-    /**
-     * Get video info from URL
-     */
-    getVideoInfo(url: string): Promise<YouTubeSearchResult | null>;
-}
-
-interface AggregatedRoomPreferences {
-    favoriteTracks: Array<{
-        url: string;
-        title: string;
-        requestedBy: UUID[];
-        playCount: number;
-    }>;
-    dislikedTracks: string[];
-}
-declare class MusicLibraryService extends Service {
-    static serviceType: string;
-    capabilityDescription: string;
-    readonly spotifyClient: SpotifyClient;
-    readonly repetitionControl: RepetitionControl;
-    private readonly youtubeSearch;
-    private readonly wikipedia;
-    private readonly musicInfo;
-    private readonly entityDetection;
-    private readonly wikipediaExtraction;
-    constructor(runtime?: IAgentRuntime);
-    static start(runtime: IAgentRuntime): Promise<MusicLibraryService>;
-    stop(): Promise<void>;
-    private ensureRuntime;
-    addSong(songData: Parameters<typeof addSongToLibrary>[1]): Promise<LibrarySong>;
-    getSong(url: string): Promise<LibrarySong | null>;
-    getRecentSongs(limit?: number): Promise<LibrarySong[]>;
-    getLastPlayedSong(): Promise<LibrarySong | null>;
-    getMostPlayedSongs(limit?: number): Promise<LibrarySong[]>;
-    searchLibrary(query: string, limit?: number): Promise<LibrarySong[]>;
-    getLibraryStats(): Promise<{
-        totalSongs: number;
-        totalPlays: number;
-        mostPlayed?: LibrarySong;
-    }>;
-    savePlaylist(entityId: UUID, playlist: Parameters<typeof savePlaylist>[2]): Promise<Playlist>;
-    loadPlaylists(entityId: UUID): Promise<Playlist[]>;
-    deletePlaylist(entityId: UUID, playlistId: string): Promise<boolean>;
-    getUserPreferences(entityId: UUID): Promise<UserMusicPreferences | null>;
-    getRoomPreferences(roomId: UUID): Promise<Map<UUID, UserMusicPreferences>>;
-    getAggregatedRoomPreferences(roomId: UUID): Promise<AggregatedRoomPreferences>;
-    trackTrackRequest(entityId: UUID, track: {
-        url: string;
-        title: string;
-    }, roomId?: UUID, worldId?: UUID): Promise<void>;
-    trackSkip(entityId: UUID, trackUrl: string, roomId?: UUID, worldId?: UUID): Promise<void>;
-    trackFavorite(entityId: UUID, track: {
-        url: string;
-        title: string;
-    }, roomId?: UUID, worldId?: UUID): Promise<void>;
-    trackTrackPlayed(roomId: UUID, track: {
-        url: string;
-        title: string;
-    }, duration: number, requestedBy?: {
-        entityId: UUID;
-        name: string;
-    }): Promise<void>;
-    getAnalytics(roomId: UUID): Promise<DJAnalytics | null>;
-    getSongMemory(url: string): Promise<SongMemory | null>;
-    recordSongPlay(song: Parameters<typeof recordSongPlay>[1], context: Parameters<typeof recordSongPlay>[2]): Promise<void>;
-    recordSongRequest(song: Parameters<typeof recordSongRequest>[1], requester: Parameters<typeof recordSongRequest>[2]): Promise<void>;
-    recordSongDedication(url: string, dedication: Parameters<typeof recordSongDedication>[2]): Promise<void>;
-    trackDJTip(roomId: UUID, tip: Omit<DJTip, "roomId">): Promise<void>;
-    getDJTipStats(): Promise<DJTipStats>;
-    search(query: string, options?: {
-        limit?: number;
-        includeShorts?: boolean;
-    }): Promise<YouTubeSearchResult[]>;
-    searchYouTube(query: string, options?: {
-        limit?: number;
-        includeShorts?: boolean;
-    }): Promise<YouTubeSearchResult[]>;
-    searchOneYouTube(query: string): Promise<YouTubeSearchResult | null>;
-    validateYouTubeUrl(url: string): Promise<boolean>;
-    getYouTubeVideoInfo(url: string): Promise<YouTubeSearchResult | null>;
-    getServiceStatus(): MusicInfoServiceStatus;
-    getTrackInfo(urlOrTitle: string): Promise<MusicInfoResult | null>;
-    getArtistInfo(artistName: string): Promise<ArtistInfo | null>;
-    getAlbumInfo(albumTitle: string, artistName?: string): Promise<AlbumInfo | null>;
-    prewarmTrackInfo(urlOrTitle: string): Promise<void>;
-    prewarmTracks(tracks: string[]): Promise<void>;
-    detectEntities(text: string): Promise<DetectedMusicEntity[]>;
-    getWikipediaTrackInfo(trackName: string, artistName?: string): Promise<TrackInfo | null>;
-    getWikipediaArtistInfo(artistName: string): Promise<ArtistInfo | null>;
-    getWikipediaAlbumInfo(albumTitle: string, artistName?: string): Promise<AlbumInfo | null>;
-    extractFromWikipedia(entityName: string, entityType: "artist" | "album" | "song", context: WikipediaExtractionContext): Promise<ExtractedMusicInfo | null>;
-}
-
-interface StoredTrack {
-    url: string;
-    title: string;
-    artist?: string;
-    album?: string;
-    filePath: string;
-    format: string;
-    size: number;
-    duration?: number;
-    bitrate?: number;
-    storedAt: number;
-}
-/**
- * Music Storage Service
- * Stores high-quality original music files for archival and library purposes
- *
- * Unlike the Discord-optimized cache in music-player, this stores:
- * - Original quality files (no transcoding)
- * - Permanent storage (not temporary cache)
- * - Organized by artist/album/track
- * - Indexed for library browsing
- */
-declare class MusicStorageService {
-    private storageDir;
-    private highQuality;
-    private index;
-    private readonly INDEX_FILE;
-    constructor(storageDir?: string, highQuality?: boolean);
-    /**
-     * Check if a track is stored
-     */
-    isStored(url: string): boolean;
-    /**
-     * Get stored track info
-     */
-    getStoredTrack(url: string): StoredTrack | null;
-    /**
-     * Get all stored tracks
-     */
-    getAllTracks(): StoredTrack[];
-    /**
-     * Store a track from YouTube URL
-     */
-    storeTrack(url: string, metadata: {
-        title: string;
-        artist?: string;
-        album?: string;
-    }): Promise<StoredTrack>;
-    /**
-     * Get a readable stream for a stored track
-     */
-    getStream(url: string): Readable | null;
-    /**
-     * Delete a stored track
-     */
-    deleteTrack(url: string): boolean;
-    /**
-     * Get total storage size in bytes
-     */
-    getTotalSize(): number;
-    /**
-     * Get storage statistics
-     */
-    getStats(): {
-        totalTracks: number;
-        totalSize: number;
-        totalDuration: number;
-        byArtist: Map<string, number>;
-    };
-    /**
-     * Load index from disk
-     */
-    private loadIndex;
-    /**
-     * Save index to disk
-     */
-    private saveIndex;
-}
-
-interface FetchProgress {
-    stage: "checking_library" | "trying_ytdlp" | "searching_torrents" | "downloading_torrents" | "indexing" | "ready" | "failed";
-    message: string;
-    details?: unknown;
-}
-interface FetchResult {
-    success: boolean;
-    source: "library" | "ytdlp" | "torrent";
-    url?: string;
-    files?: string[];
-    error?: string;
-}
-interface SmartFetchOptions {
-    query: string;
-    requestedBy?: UUID;
-    onProgress?: (progress: FetchProgress) => void;
-    preferredQuality?: "flac" | "mp3_320" | "any";
-    parallelDownloads?: number;
-}
-/**
- * Smart music fetch service that tries multiple sources automatically
- * 1. Check music library
- * 2. Try yt-dlp (YouTube, SoundCloud, etc.)
- * 3. Search and download torrents (2-3 in parallel)
- * 4. Notify when ready
- */
-declare class SmartMusicFetchService extends Service {
-    static serviceType: string;
-    capabilityDescription: string;
-    static start(runtime: IAgentRuntime): Promise<SmartMusicFetchService>;
-    stop(): Promise<void>;
-    /**
-     * Smart fetch music from any available source
-     */
-    fetchMusic(options: SmartFetchOptions): Promise<FetchResult>;
-    /**
-     * Check if music exists in library
-     */
-    private checkMusicLibrary;
-    /**
-     * Try to find and get URL from YouTube/SoundCloud via search
-     */
-    private tryYtdlp;
-    /**
-     * Search for music torrents with quality scoring
-     */
-    private searchMusicTorrents;
-    /**
-     * Calculate quality score for a torrent
-     * Considers: quality match, seeders, and file format
-     */
-    private calculateQualityScore;
-    /**
-     * Check if torrent is likely music
-     */
-    private isMusicTorrent;
-    /**
-     * Download multiple torrents in parallel, return first to complete
-     */
-    private downloadTorrentsParallel;
-    /**
-     * Wait for torrent to complete
-     */
-    private waitForTorrentCompletion;
-}
-
-declare const musicPlugin: Plugin;
-
-export { type AlbumInfo, type ArtistInfo, type AudioFeatureSeed, type AudioFeatures, type AudioRouteConfig, AudioRouter, type AudioRoutingMode, type AudioSubscription, Broadcast, type BroadcastState, type BroadcastTrackMetadata, type CrossFadeOptions, DEFAULT_DJ_INTRO_OPTIONS, DEFAULT_GUILD_SETTINGS, type DJAnalytics, type DJGuildSettings, type DJIntroOptions, type DJTip, type DJTipStats, type DetectedMusicEntity, type ExtractedMusicInfo, type FetchProgress, type FetchResult, type IAudioBroadcast, type LibrarySong, type MixConfig, type MixSession, MixSessionManager, MusicEntityDetectionHelper, MusicEntityDetectionHelper as MusicEntityDetectionService, MusicInfoHelper, type MusicInfoResult, MusicInfoHelper as MusicInfoService, type MusicInfoServiceStatus, MusicLibraryService, MusicService, MusicStorageService, type Playlist, type PlaylistTrack, type QueuedTrack, type RecommendationRequest, type ServiceHealth, ServiceStatus, type SmartFetchOptions, SmartMusicFetchService, type SongMemory, SpotifyClient, type StoredTrack, type TrackInfo, type TrackRecommendation, type UserMusicPreferences, WikipediaClient, type WikipediaExtractionContext, WikipediaExtractionHelper, WikipediaExtractionHelper as WikipediaExtractionService, WikipediaClient as WikipediaService, YouTubeSearchHelper, type YouTubeSearchResult, YouTubeSearchHelper as YouTubeSearchService, type Zone, ZoneManager, addSongToLibrary, buildIntroPrompt, musicPlugin as default, deletePlaylist, getAllConfiguredGuilds, getAnalytics, getDJGuildSettings, getDJIntroOptions, getDJTipStats, getLastPlayedSong, getLibraryStats, getMostPlayedSongs, getMostRequestedSongs, getRecentSongs, getRecentTips, getRoomPreferences, getSong, getSongMemory, getTopSongs, getTopTippers, getUserPreferences, loadPlaylists, musicAction, recordSongDedication, recordSongPlay, recordSongRequest, repetitionControl, resetDJGuildSettings, resetDJIntroOptions, savePlaylist, searchLibrary, setAutonomyLevel, setDJGuildSettings, setDJIntroOptions, toggleDJ, trackDJTip, trackFavorite, trackListenerSnapshot, trackSession, trackSkip, trackTrackPlayed, trackTrackRequest, tryHandleMusicPlayerStatusFallback, updateUserPreferences };