vantiv.io 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantiv.io",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Enterprise WebSocket infrastructure for Highrise featuring spatial intelligence systems, memory-optimized architecture, and production-grade reliability for scalable application development",
   "keywords": [
     "highrise",

package/src/classes/Actions/Music.js

@@ -23,38 +23,38 @@ class MusicClass extends EventEmitter {
 
         this.initializeStreamer();
         this.setupEventHandlers();
-        
+
         if (this.config.autoStartServer) {
             this.startWebServer();
         }
-        
+
     }
 
     initializeStreamer() {
         try {
             this.streamer = new IcecastStreamer(this.config.icecast);
-            this.queue = new IcecastQueue(this.streamer, { ...this.config.queue, ...this.config.icecast});
-            
+            this.queue = new IcecastQueue(this.streamer, { ...this.config.queue, ...this.config.icecast });
+
             this.streamer.on('playbackStart', (track) => {
                 this.emit('playbackStart', track);
             });
-            
+
             this.streamer.on('playbackEnd', (track) => {
                 this.emit('playbackEnd', track);
             });
-            
+
             this.streamer.on('progress', (data) => {
                 this.emit('progress', data);
             });
-            
+
             this.streamer.on('error', (error) => {
                 this.emit('error', error);
             });
-            
+
             this.streamer.on('streamStopped', () => {
                 this.emit('streamStopped');
             });
-            
+
         } catch (error) {
             console.error('Failed to initialize Icecast streamer:', error);
             throw error;
@@ -79,10 +79,19 @@ class MusicClass extends EventEmitter {
 
             let trackInfo;
             let source = 'direct';
-            
+
             if (this.isValidUrl(query)) {
                 if (query.includes('youtube.com') || query.includes('youtu.be')) {
-                    trackInfo = await YouTubeExtractor.getStreamUrl(query);
+                    try {
+                        trackInfo = await YouTubeExtractor.getStreamUrl(query);
+                    } catch (error) {
+                        return {
+                            success: false,
+                            error: error.message.includes('yt-dlp')
+                                ? 'Missing dependency: yt-dlp'
+                                : `YouTube error: ${error.message}`
+                        };
+                    }
                     source = 'youtube';
                 } else {
                     trackInfo = {
@@ -115,7 +124,7 @@ class MusicClass extends EventEmitter {
             });
 
             const result = await this.queue.add(track);
-            
+
             return {
                 success: true,
                 track: {
@@ -128,7 +137,7 @@ class MusicClass extends EventEmitter {
                 position: result.position,
                 isNowPlaying: result.isNowPlaying || false
             };
-            
+
         } catch (error) {
             console.error('Error playing track:', error);
             return {
@@ -141,7 +150,7 @@ class MusicClass extends EventEmitter {
     async skip() {
         try {
             const result = await this.queue.skip();
-            
+
             let upcoming = null;
             if (this.queue.queue.length > 0) {
                 const nextTrack = this.queue.queue[0];
@@ -151,7 +160,7 @@ class MusicClass extends EventEmitter {
                     formattedDuration: nextTrack.getFormattedDuration()
                 };
             }
-            
+
             return {
                 success: result,
                 upcoming: upcoming
@@ -197,7 +206,7 @@ class MusicClass extends EventEmitter {
         const currentIndex = modes.indexOf(this.queue.loopMode);
         const nextIndex = (currentIndex + 1) % modes.length;
         this.queue.loopMode = modes[nextIndex];
-        
+
         return {
             success: true,
             newMode: this.queue.loopMode
@@ -223,6 +232,18 @@ class MusicClass extends EventEmitter {
         };
     }
 
+    removeFromQueue(index) {
+        return this.queue?.remove(index) || null;
+    }
+
+    moveInQueue(from, to) {
+        return this.queue?.move(from, to) || false;
+    }
+
+    clearQueue() {
+        return this.queue?.clear() || [];
+    }
+
     isValidUrl(string) {
         try {
             new URL(string);
@@ -234,31 +255,24 @@ class MusicClass extends EventEmitter {
 
     formatDuration(seconds) {
         if (!seconds) return '0:00';
-        
+
         const hours = Math.floor(seconds / 3600);
         const minutes = Math.floor((seconds % 3600) / 60);
         const secondsRemaining = Math.floor(seconds % 60);
-        
+
         if (hours > 0) {
             return `${hours}:${minutes.toString().padStart(2, '0')}:${secondsRemaining.toString().padStart(2, '0')}`;
         }
         return `${minutes}:${secondsRemaining.toString().padStart(2, '0')}`;
     }
 
-    startWebServer() {
-        try {
-            this.webServer = new IcecastServer({
-                port: this.config.serverPort,
-                publicStreamUrl: this.streamer.publicStreamUrl,
-                logger: this.bot.utils.logger
-            });
-            
-            this.webServer.start();
-            return true;
-        } catch (error) {
-            console.error('Failed to start web server:', error);
-            return false;
-        }
+    getHealth() {
+        return {
+            streamer: this.streamer?.getHealth(),
+            queue: this.queue?.getStatus(),
+            webServer: !!this.webServer,
+            uptime: process.uptime()
+        };
     }
 
     destroy() {
@@ -266,7 +280,7 @@ class MusicClass extends EventEmitter {
             if (this.streamer) {
                 this.streamer.stop();
             }
-            
+
             return true;
         } catch (error) {
             console.error('Error destroying music class:', error);

package/src/classes/Actions/lib/AudioStreaming.js

@@ -148,7 +148,7 @@ class IcecastStreamer extends EventEmitter {
         if (!this.config.fallbackUrl || this.isFallbackActive || this.isStreaming) {
             return false;
         }
-        
+
         if (this.ffmpegProcess) {
             this.ffmpegProcess.kill('SIGKILL');
             this.ffmpegProcess = null;
@@ -156,10 +156,10 @@ class IcecastStreamer extends EventEmitter {
 
         const args = this.getFallbackFFmpegArgs();
         this.fallbackProcess = spawn('ffmpeg', args);
-        
+
         this.isFallbackActive = true;
         this.isStreaming = false;
-        
+
         this.currentTrack = new Track({
             url: this.config.fallbackUrl,
             title: 'Fallback Music',
@@ -173,11 +173,11 @@ class IcecastStreamer extends EventEmitter {
 
         this.fallbackProcess.stderr.on('data', (data) => {
             const message = data.toString();
-            
+
             if (message.includes('Stream mapping') || message.includes('Output')) {
                 this.emit('fallbackStart', this.currentTrack);
             }
-            
+
             if (message.includes('Error') || message.includes('Failed')) {
                 console.error('Fallback FFmpeg error:', message.trim());
             }
@@ -187,7 +187,7 @@ class IcecastStreamer extends EventEmitter {
             this.isFallbackActive = false;
             this.currentTrack = null;
             this.fallbackProcess = null;
-            
+
             this.emit('fallbackEnd', { code });
         });
 
@@ -219,7 +219,7 @@ class IcecastStreamer extends EventEmitter {
             this.isStreaming = false;
             this.emit('streamStopped');
         }
-        
+
         this.stopFallback();
     }
 
@@ -233,6 +233,18 @@ class IcecastStreamer extends EventEmitter {
         };
     }
 
+    getHealth() {
+        return {
+            status: this.isStreaming ? 'playing' :
+                this.isFallbackActive ? 'fallback' : 'idle',
+            latencyMs: this.currentTrack?.startedAt ?
+                Date.now() - this.currentTrack.startedAt : 0,
+            lastError: this.lastError,
+            uptime: this.currentTrack?.startedAt ?
+                (Date.now() - this.currentTrack.startedAt) / 1000 : 0,
+        };
+    }
+
     getNowPlaying() {
         if (!this.currentTrack) return null;
 
@@ -300,12 +312,12 @@ class IcecastQueue {
         this.history = [];
         this.maxHistory = config.maxHistory || 50;
         this.skipRequested = false;
-        
+
         this.fallbackEnabled = config.fallbackEnabled || false;
         this.fallbackUrl = config.fallbackUrl || '';
 
         this.setupEventListeners();
-        
+
         this.checkAndStartFallback();
     }
 
@@ -332,27 +344,27 @@ class IcecastQueue {
         this.streamer.on('playbackStart', (track) => {
             this.currentTrack = track;
         });
-        
+
         this.streamer.on('fallbackStart', (track) => {
             this.currentTrack = track;
         });
-        
+
         this.streamer.on('fallbackEnd', () => {
             this.currentTrack = null;
             this.checkAndStartFallback();
         });
     }
-    
+
     checkAndStartFallback() {
-        if (this.queue.length === 0 && 
+        if (this.queue.length === 0 &&
             !this.streamer.isStreaming &&
             !this.streamer.isFallbackActive &&
-            this.fallbackEnabled && 
+            this.fallbackEnabled &&
             this.fallbackUrl) {
-            
+
             setTimeout(() => {
-                if (this.queue.length === 0 && 
-                    !this.streamer.isStreaming && 
+                if (this.queue.length === 0 &&
+                    !this.streamer.isStreaming &&
                     !this.streamer.isFallbackActive) {
                     this.streamer.startFallback();
                 }
@@ -453,18 +465,35 @@ class IcecastQueue {
         return this.queue.splice(position - 1, 1)[0];
     }
 
+    move(fromIndex, toIndex) {
+        if (fromIndex < 0 || fromIndex >= this.queue.length ||
+            toIndex < 0 || toIndex >= this.queue.length) {
+            return false;
+        }
+
+        const track = this.queue.splice(fromIndex, 1)[0];
+        this.queue.splice(toIndex, 0, track);
+        return true;
+    }
+
+    clearExceptCurrent() {
+        const cleared = this.queue.splice(0);
+        this.checkAndStartFallback();
+        return cleared;
+    }
+
     clear() {
         const cleared = [...this.queue];
         this.queue = [];
-        
+
         this.checkAndStartFallback();
-        
+
         return cleared;
     }
 
     addToHistory(track, success = true) {
         if (track.isFallback) return;
-        
+
         const historyEntry = {
             ...track,
             playedAt: Date.now(),
@@ -499,14 +528,14 @@ class IcecastQueue {
     async delay(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
-    
+
     startFallback() {
         if (this.fallbackEnabled && this.fallbackUrl) {
             return this.streamer.startFallback();
         }
         return false;
     }
-    
+
     stopFallback() {
         return this.streamer.stopFallback();
     }
@@ -525,12 +554,27 @@ class YouTubeExtractor {
                 '--no-playlist',
                 '--no-check-certificates',
                 '--quiet'
-            ]);
+            ], {
+                timeout: 15000
+            });
 
             let data = '';
             ytdlp.stdout.on('data', (chunk) => data += chunk.toString());
             ytdlp.stderr.on('data', () => { });
 
+            ytdlp.on('error', (err) => {
+                if (err.code === 'ENOENT') {
+                    reject(new Error('yt-dlp not found. Install with: pip install yt-dlp'));
+                } else {
+                    reject(err);
+                }
+            });
+
+            ytdlp.on('timeout', () => {
+                ytdlp.kill('SIGKILL');
+                reject(new Error('YouTube fetch timed out (15s)'));
+            });
+
             ytdlp.on('close', (code) => {
                 if (code !== 0) {
                     resolve(null);

package/src/classes/Managers/Networking/ConnectionManager.js

@@ -34,11 +34,6 @@ class ConnectionManager extends EventEmitter {
     }
 
     _establishConnection() {
-        if (this.reconnecting || this.connected) {
-            this.logger.debug('ConnectionManager', 'Connection attempt already in progress — skipping');
-            return;
-        }
-
         if (!this.connectionAuth) {
             throw new Error('No connection authentication available');
         }
@@ -59,7 +54,8 @@ class ConnectionManager extends EventEmitter {
                 [WebSocketConstants.HEADERS.API_TOKEN]: token,
                 [WebSocketConstants.HEADERS.ROOM_ID]: roomId
             },
-            handshakeTimeout: WebSocketConstants.DEFAULT_HANDSHAKE_TIMEOUT
+            handshakeTimeout: WebSocketConstants.DEFAULT_HANDSHAKE_TIMEOUT,
+            autoPong: true
         });
 
         this._setupWebSocketHandlers();
@@ -105,7 +101,7 @@ class ConnectionManager extends EventEmitter {
         this.reconnecting = false;
         this._clearReconnectTimeout();
 
-        this.emit('connected');
+        this.emit('Connected');
         this.logger.info('ConnectionManager', 'WebSocket connection established');
     }
 
@@ -115,7 +111,7 @@ class ConnectionManager extends EventEmitter {
         this.reconnecting = false;
 
         const reasonStr = reason?.toString('utf8') || `Binary reason (length: ${reason?.length || 0})`;
-        this.emit('disconnected', { code, reason: reasonStr });
+        this.emit('Disconnected', { code, reason: reasonStr });
 
         this.logger.warn('ConnectionManager', 'Connection closed', {
             code,
@@ -188,7 +184,7 @@ class ConnectionManager extends EventEmitter {
         }
 
         this.connected = false;
-        this.emit('disconnected', { code, reason, manual: true });
+        this.emit('Disconnected', { code, reason, IsManual: true });
     }
 
     send(data) {

package/typings/index.d.ts

@@ -14,7 +14,7 @@ type EventType =
     | 'TipReactionEvent'
     | 'RoomModeratedEvent'
     | 'ChannelEvent'
-    
+
 type Goldbars = 1 | 5 | 10 | 50 | 100 | 500 | 1000 | 5000 | 10000
 type ItemCategory =
     | "bag"
@@ -368,6 +368,12 @@ interface CooldownManagerStats {
     memoryUsage: CooldownMemoryUsage;
 }
 
+interface DisconnectedData {
+    code: number | null,
+    reason: string,
+    IsManual: boolean
+}
+
 interface EventMap {
     UserLeft: [user: User]
     Ready: [session: ReadyEvent]
@@ -380,6 +386,11 @@ interface EventMap {
     Direct: [user: User, message: string, conversation: Conversation]
     Moderation: [moderator: User, target: User, action: ModerationAction]
     Movement: [user: User, position: Position | null, anchor: AnchorPosition | null]
+
+    // Connections
+    error: [data: any]
+    Connected: []
+    Disconnected: [data: DisconnectedData]
 }
 
 
@@ -983,6 +994,468 @@ interface ChannelStats {
     listeners: number;
 }
 
+/**
+ * Icecast stream configuration
+ */
+interface IcecastConfig {
+    /** Icecast server hostname or IP address */
+    server?: string;
+    /** Icecast server port */
+    port?: number;
+    /** Mount point for the stream */
+    mount?: string;
+    /** Source password for Icecast authentication */
+    sourcePassword?: string;
+    /** Fallback URL to play when queue is empty */
+    fallbackUrl?: string;
+    /** Whether fallback is enabled */
+    fallbackEnabled?: boolean;
+    /** Audio format (mp3, aac, etc.) */
+    audioFormat?: string;
+    /** Audio bitrate (e.g., '192k') */
+    audioBitrate?: string;
+    /** Audio sample rate in Hz */
+    audioSampleRate?: number;
+    /** Number of audio channels (1 for mono, 2 for stereo) */
+    audioChannels?: number;
+    /** Content type for Icecast stream */
+    contentType?: string;
+}
+
+/**
+ * Queue configuration
+ */
+interface QueueConfig {
+    /** Maximum number of tracks to keep in history */
+    maxHistory?: number;
+}
+
+/**
+ * Music configuration for Highrise bot
+ */
+interface MusicConfig {
+    /** Whether the music module is enabled */
+    enabled?: boolean;
+    /** Icecast server configuration */
+    icecast?: IcecastConfig;
+    /** Queue management configuration */
+    queue?: QueueConfig;
+    /** Automatically start web server for stream monitoring */
+    autoStartServer?: boolean;
+    /** Port for the web server */
+    serverPort?: number;
+    /** Maximum queue size */
+    maxQueueSize?: number;
+    /** Default volume level (0-100) */
+    defaultVolume?: number;
+    /** Allowed audio source formats */
+    allowedFormats?: string[];
+}
+
+/**
+ * Music playback status and information
+ */
+interface MusicNowPlaying {
+    /** Current track information */
+    track: Track;
+    /** Current playback position in seconds */
+    position: number;
+    /** Total track duration in seconds */
+    duration: number;
+    /** Playback progress percentage (0-100) */
+    progress: number;
+    /** Time remaining in seconds */
+    remaining: number;
+    /** Formatted position string (e.g., '1:30') */
+    formattedPosition: string;
+    /** Formatted duration string (e.g., '3:45') */
+    formattedDuration: string;
+    /** Formatted remaining time string (e.g., '2:15') */
+    formattedRemaining: string;
+}
+
+/**
+ * Queue information
+ */
+interface QueueInfo {
+    /** Current queue of tracks */
+    queue: Track[];
+    /** Upcoming tracks (first 10 in queue) */
+    upcoming: Track[];
+    /** Current loop mode */
+    loopMode: 'off' | 'track' | 'queue';
+    /** Number of tracks in queue */
+    length: number;
+}
+
+/**
+ * Play result from music operations
+ */
+interface PlayResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Track information (if successful) */
+    track?: {
+        title: string;
+        duration: number;
+        formattedDuration: string;
+        requester: string;
+        thumbnail?: string | null;
+    };
+    /** Position in queue (if added to queue) */
+    position?: number;
+    /** Whether track is now playing immediately */
+    isNowPlaying?: boolean;
+    /** Error message (if failed) */
+    error?: string;
+}
+
+/**
+ * Skip result from music operations
+ */
+interface SkipResult {
+    /** Whether skip was successful */
+    success: boolean;
+    /** Upcoming track information */
+    upcoming?: {
+        title: string;
+        duration: number;
+        formattedDuration: string;
+    };
+    /** Error message (if failed) */
+    error?: string;
+}
+
+/**
+ * Loop toggle result
+ */
+interface LoopResult {
+    /** Whether operation was successful */
+    success: boolean;
+    /** New loop mode */
+    newMode: string;
+}
+
+/**
+ * Shuffle result
+ */
+interface ShuffleResult {
+    /** Whether shuffle was successful */
+    success: boolean;
+    /** Updated queue information */
+    queue?: QueueInfo;
+    /** Error message (if failed) */
+    error?: string;
+}
+
+/**
+ * Music event types
+ */
+interface MusicEventMap {
+    'playbackStart': [track: Track];
+    'playbackEnd': [track: Track];
+    'progress': [data: { position: number, duration: number, progress: number }];
+    'error': [error: Error];
+    'streamStopped': [];
+    'Ready': [];
+    'ready': [];
+}
+
+/**
+ * Logger configuration - controls how bot messages appear in console
+ */
+interface LoggerOptions {
+    /** Show time in logs? (true = [2023-10-05T14:30:00.68a7dd5eecae68acca580f41Z] [INFO]) */
+    showTimestamp?: boolean;
+    /** Show method name? (true = [connect]: Connected) */
+    showMethodName?: boolean;
+    /** Use colors? (true = green success, red errors) */
+    colors?: boolean;
+}
+
+/**
+ * Bot connection settings - controls how bot handles disconnections
+ */
+interface HighriseOptions {
+    /** How logs look in console */
+    LoggerOptions?: LoggerOptions;
+    /** Wait time between reconnect tries (milliseconds) */
+    reconnectDelay?: number;
+    /** Auto-reconnect if disconnected? */
+    autoReconnect?: boolean;
+    /** Custom roles to create on startup */
+    customRoles?: string[];
+    /** Music module configuration */
+    music?: MusicConfig;
+}
+
+/**
+ * Configuration options for request senders
+ */
+interface SenderConfig {
+    /**
+     * Default timeout for requests waiting in milliseconds (default: 10000ms)
+     */
+    defaultTimeout?: number;
+
+    /**
+     * Maximum number of retry attempts for failed requests (default: 2)
+     */
+    maxRetries?: number;
+
+    /**
+     * Delay between retry attempts in milliseconds (default: 100)
+     */
+    retryDelay?: number;
+}
+
+interface PlayMetadata {
+    title?: string;
+    duration?: number;
+    requester?: string;
+    requesterId?: string;
+    thumbnail?: string | null;
+    source?: string;
+}
+
+interface MusicHealthInfo {
+    streamer: {
+        status: 'idle' | 'playing' | 'fallback' | 'error';
+        latencyMs: number;
+        uptimeSeconds: number;
+        lastError?: string;
+    };
+    queue: {
+        length: number;
+        isProcessing: boolean;
+    };
+    webServer: boolean;
+    systemUptime: number;
+}
+
+/**
+ * Track information
+ */
+class Track {
+    id: number;
+    url: string;
+    title: string;
+    duration: number;
+    requester: string;
+    requesterId: string;
+    addedAt: number;
+    thumbnail?: string | null;
+    source: string;
+    isFallback?: boolean;
+    position?: number;
+    startedAt?: number;
+
+    /**
+     * Formats track duration (in seconds) as a readable time string.
+     * 
+     * @returns
+     * - `"Unknown"` if duration is `0`, `null`, or `invalid`
+     * - `"M:SS"` for tracks under 1 hour (e.g., `"0:05"`, `"3:45"`)
+     * - `"H:MM:SS"` for tracks 1+ hours (e.g., `"1:05:30"`)
+     * 
+     * Note: Minutes are not padded in M:SS mode (`0:05`, not `00:05`),
+     * but minutes/seconds are padded in H:MM:SS mode.
+     */
+    getFormattedDuration(): string;
+}
+
+declare class MusicClass {
+    /**
+     * Creates a new MusicClass instance
+     * @param bot - Highrise bot instance
+     * @param config - Music configuration
+     */
+    constructor(bot: Highrise, config: MusicConfig);
+
+    /**
+     * Play a track from URL or search query
+     * @param query - YouTube URL, direct URL, or search query
+     * @param metadata - Track metadata (requester, title, etc.)
+     * @returns Promise resolving to play result or error when thrown
+     * @example
+     * ```typescript
+     * // Play YouTube video by URL
+     * const result = await bot.music.play(
+     *   'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+     *   { requester: 'User123', requesterId: 'user_123' }
+     * );
+     * 
+     * // Search and play YouTube video
+     * const result = await bot.music.play(
+     *   'never gonna give you up',
+     *   { requester: 'User123', requesterId: 'user_123' }
+     * );
+     * ```
+     */
+    play(query: string, metadata?: PlayMetadata): Promise<PlayResult>;
+
+    /**
+     * Skip the currently playing track
+     * @returns Promise resolving to skip result
+     * @example
+     * ```typescript
+     * const result = await bot.music.skip();
+     * if (result.success && result.upcoming) {
+     *   await bot.message.send(`Now playing: ${result.upcoming.title}`);
+     * }
+     * ```
+     */
+    skip(): Promise<SkipResult>;
+
+    /**
+     * Get information about currently playing track
+     * @returns Now playing information or null if nothing is playing
+     * @example
+     * ```typescript
+     * const np = bot.music.getNowPlaying();
+     * if (np) {
+     *   await bot.message.send(
+     *     `Now playing: ${np.track.title}\n` +
+     *     `Progress: ${np.formattedPosition} / ${np.formattedDuration}`
+     *   );
+     * }
+     * ```
+     */
+    getNowPlaying(): MusicNowPlaying | null;
+
+    /**
+     * Get current queue information
+     * @returns Queue information
+     * @example
+     * ```typescript
+     * const queue = bot.music.getQueue();
+     * await bot.message.send(
+     *   `Queue: ${queue.length} tracks\n` +
+     *   `Loop mode: ${queue.loopMode}`
+     * );
+     * ```
+     */
+    getQueue(): QueueInfo;
+
+    /**
+     * Toggle loop mode between off, track, and queue
+     * @returns Loop result with new mode
+     * @example
+     * ```typescript
+     * const result = bot.music.toggleLoop();
+     * await bot.message.send(`Loop mode: ${result.newMode}`);
+     * ```
+     */
+    toggleLoop(): LoopResult;
+
+    /**
+     * Shuffle the current queue
+     * @returns Shuffle result
+     * @example
+     * ```typescript
+     * const result = bot.music.shuffle();
+     * if (result.success) {
+     *   await bot.message.send('Queue shuffled!');
+     * }
+     * ```
+     */
+    shuffle(): ShuffleResult;
+
+    /**
+     * Remove a track from queue by position (1-based index)
+     * @param position - Position in queue (1 = next track)
+     * @returns Removed track or null if position invalid
+     * @example
+     * ```typescript
+     * const removed = bot.music.removeFromQueue(1);
+     * if (removed) {
+     *   await bot.message.send(`Removed: ${removed.title}`);
+     * }
+     * ```
+     */
+    removeFromQueue(position: number): Track | null;
+
+    /**
+     * Move a track from one position to another in the queue
+     * @tutorial 1 being the top
+     * @param fromPosition - Current position (1-based index)
+     * @param toPosition - Target position (1-based index)
+     * @returns true if move succeeded, false if invalid positions
+     * @example
+     * ```typescript
+     * const success = bot.music.moveInQueue(3, 1);
+     * if (success) {
+     *   await bot.message.send('Moved track to top of queue!');
+     * }
+     * ```
+     */
+    moveInQueue(fromPosition: number, toPosition: number): boolean;
+
+    /**
+     * Clear the entire queue (keeps currently playing track)
+     * @returns Number of tracks removed
+     * @example
+     * ```typescript
+     * const count = bot.music.clearQueue();
+     * await bot.message.send(`Cleared ${count} tracks from queue`);
+     * ```
+     */
+    clearQueue(): number;
+
+    /**
+     * Get system health status
+     * @returns Health information including stream status, latency, and errors
+     * @example
+     * ```typescript
+     * const health = bot.music.getHealth();
+     * if (health.streamer.status === 'error') {
+     *   await bot.message.send(`⚠️ Music system error: ${health.streamer.lastError}`);
+     * }
+     * ```
+     */
+    getHealth(): MusicHealthInfo;
+
+    /**
+     * Check if string is a valid URL
+     * @param string - String to check
+     * @returns Whether string is a valid URL
+     */
+    isValidUrl(string: string): boolean;
+
+    /**
+     * Format duration in seconds to human-readable string
+     * @param seconds - Duration in seconds
+     * @returns Formatted duration string in `M:SS` format (e.g. `"0:00"`, `"1:05"`, `"12:30"`)
+     */
+    formatDuration(seconds: number): string;
+
+    /**
+     * Clean up and destroy music instance
+     * @returns Whether cleanup was successful
+     */
+    destroy(): boolean;
+
+    /**
+     * Register event listener for music events
+     * @param event - Event name
+     * @param listener - Event handler function
+     */
+    on<K extends keyof MusicEventMap>(
+        event: K,
+        listener: (...args: MusicEventMap[K]) => void
+    ): void;
+
+    /**
+     * Remove event listener
+     * @param event - Event name
+     * @param listener - Event handler function to remove
+     */
+    off<K extends keyof MusicEventMap>(
+        event: K,
+        listener: (...args: MusicEventMap[K]) => void
+    ): void;
+}
+
 declare class RoleManager {
     /**
      * Create a new custom role
@@ -1716,10 +2189,6 @@ declare class CooldownManager {
     static formatTime(ms: number): string;
 }
 
-/**
- * Hidden channel system for bot-to-bot communication
- * Messages are broadcast to all bots in the same room
- */
 declare class Channel {
     /**
      * Send a message to the hidden channel
@@ -2613,7 +3082,6 @@ declare class WebApi {
     }
 }
 
-
 declare class MovementCache {
     /**
      * Get user data by either userId or username
@@ -2974,7 +3442,6 @@ declare class WhisperClass {
     send(user_id: string, message: string): Promise<boolean>;
 }
 
-
 declare class DirectClass {
 
     /**
@@ -3345,7 +3812,7 @@ declare class Logger {
     debug(method: string, message: string, data?: any): void;
 }
 
-interface BotUtils {
+declare class BotUtils {
     /**
      * Logger instance for structured, color-coded logging throughout the application
      * Provides different log levels (SUCCESS, ERROR, WARN, INFO, DEBUG) with timestamps and method tracking
@@ -3612,52 +4079,6 @@ declare class RoomClass {
     }
 }
 
-/**
- * Logger configuration - controls how bot messages appear in console
- */
-interface LoggerOptions {
-    /** Show time in logs? (true = [2023-10-05T14:30:00.68a7dd5eecae68acca580f41Z] [INFO]) */
-    showTimestamp?: boolean;
-    /** Show method name? (true = [connect]: Connected) */
-    showMethodName?: boolean;
-    /** Use colors? (true = green success, red errors) */
-    colors?: boolean;
-}
-
-/**
- * Bot connection settings - controls how bot handles disconnections
- */
-interface HighriseOptions {
-    /** How logs look in console */
-    LoggerOptions?: LoggerOptions;
-    /** Wait time between reconnect tries (milliseconds) */
-    reconnectDelay: number;
-    /** Auto-reconnect if disconnected? */
-    autoReconnect: boolean;
-    /** Custom roles to create on startup */
-    customRoles?: string[];
-}
-
-/**
- * Configuration options for request senders
- */
-interface SenderConfig {
-    /**
-     * Default timeout for requests waiting in milliseconds (default: 10000ms)
-     */
-    defaultTimeout?: number;
-
-    /**
-     * Maximum number of retry attempts for failed requests (default: 2)
-     */
-    maxRetries?: number;
-
-    /**
-     * Delay between retry attempts in milliseconds (default: 100)
-     */
-    retryDelay?: number;
-}
-
 declare class Highrise {
     /**
      * Creates a new Highrise bot instance
@@ -3713,6 +4134,9 @@ declare class Highrise {
      */
     public channel: Channel;
 
+    /** Music streaming and management */
+    public music: MusicClass | null;
+
     /**
      * Cache management system for efficient data storage and retrieval
      * Provides optimized memory usage and fast lookups for frequently accessed data