Queue Management

class GuildPlayerState:
    """Encapsulates all playback-related state for a single guild."""
    def __init__(self, guild_id: int, bot_instance: commands.Bot):
        self.guild_id: int = guild_id
        self.bot: commands.Bot = bot_instance
        self.queue: list[str] = []  # List of file paths for songs
        self.song_titles: list[str] = []  # List of song titles corresponding to the queue
        self.current_song_path: str | None = None  # File path of currently playing song
        self.current_song_title: str | None = None  # Title of currently playing song
        self.inactive_timer: asyncio.TimerHandle | None = None  # Timer for inactivity disconnect
        self.voice_client: discord.VoiceClient | None = None  # Voice client for this guild
        self.last_ctx: commands.Context | None = None  # Last command context

guild_states: dict[int, GuildPlayerState] = {}

if file_path_to_play and title_to_play:
    logger.info(f"Adding to queue: '{title_to_play}' from {file_path_to_play}")
    guild_state.queue.append(file_path_to_play)
    guild_state.song_titles.append(title_to_play)
    await ctx.send(f"Added to queue: '{title_to_play}'")
    
    if not guild_state.current_song_path and guild_state.voice_client.is_connected():
        play_next_song(guild_state)

User: !play song1
Bot: Downloading audio...
     Added to queue: 'Song 1'
     Now playing: 'Song 1'
     [queue is now empty, current_song = Song 1]

User: !play song2
Bot: Added to queue: 'Song 2'
     [queue = [Song 2], current_song = Song 1]

User: !play song3
Bot: Added to queue: 'Song 3'
     [queue = [Song 2, Song 3], current_song = Song 1]

[Song 1 finishes]
Bot: Now playing: 'Song 2'
     [queue = [Song 3], current_song = Song 2]

[Song 2 finishes]
Bot: Now playing: 'Song 3'
     [queue is empty, current_song = Song 3]

[Song 3 finishes]
     [queue is empty, current_song = None]
     [inactivity timer starts]

def play_next_song(guild_state: GuildPlayerState):
    """Plays the next song in the queue."""
    voice_client = guild_state.voice_client
    ctx = guild_state.last_ctx
    
    if guild_state.queue:  # If there are songs in the queue
        file_path = guild_state.queue.pop(0)  # Get first song (FIFO)
        song_title = guild_state.song_titles.pop(0)
        
        guild_state.current_song_path = file_path
        guild_state.current_song_title = song_title
        
        # Play the audio
        audio_source = discord.FFmpegPCMAudio(file_path)
        voice_client.play(
            audio_source,
            after=lambda e: song_finished(file_path, guild_state, error=e)
        )
        
        asyncio.run_coroutine_threadsafe(
            ctx.send(f"Now playing: '{song_title}'"),
            guild_state.bot.loop
        )

file_path = guild_state.queue.pop(0)  # Remove from front
song_title = guild_state.song_titles.pop(0)

def song_finished(file_path: str, guild_state: GuildPlayerState, error=None):
    """Callback when a song finishes playing."""
    cleanup(file_path)  # Log retention (files not deleted)
    guild_state.current_song_path = None
    guild_state.current_song_title = None
    
    if voice_client and voice_client.is_connected():
        play_next_song(guild_state)  # Play next song automatically

@bot.command(name='skip', help='Skips the currently playing song.')
async def skip(ctx: commands.Context):
    guild_state = get_or_create_guild_state(ctx)
    voice_client = guild_state.voice_client
    
    if voice_client and voice_client.is_playing():
        voice_client.stop()  # Stopping triggers song_finished callback
        await ctx.send('Song skipped.')

[Current song: Song 1, Queue: Song 2, Song 3]

User: !skip
Bot: Song skipped.
     Now playing: 'Song 2'
     
[Current song: Song 2, Queue: Song 3]

User: !skip
Bot: Song skipped.
     Now playing: 'Song 3'
     
[Current song: Song 3, Queue: empty]

User: !skip
Bot: Song skipped.
     [No more songs, playback stops]

# Clear queue and reset playback state
guild_state.queue.clear()
guild_state.song_titles.clear()
guild_state.current_song_path = None
guild_state.current_song_title = None

else:  # If the queue is empty
    logger.info(f"Queue is empty for guild '{ctx.guild.name}'. No more songs to play.")
    guild_state.current_song_path = None
    guild_state.current_song_title = None
    # Inactivity timer continues - will disconnect after 5 minutes

def check_inactive(guild_state: GuildPlayerState):
    """Callback for the inactivity timer."""
    if guild_state.current_song_path or (voice_client and voice_client.is_playing()):
        return  # Still active
    
    # Bot is inactive - disconnect
    asyncio.run_coroutine_threadsafe(voice_client.disconnect(), guild_state.bot.loop)
    asyncio.run_coroutine_threadsafe(
        ctx.send('Disconnected due to inactivity. The song queue has been cleared.'),
        guild_state.bot.loop
    )
    
    guild_state.queue.clear()
    guild_state.song_titles.clear()

if guild_state.inactive_timer:
    guild_state.inactive_timer.cancel()

guild_state.inactive_timer = guild_state.bot.loop.call_later(
    inactive_time,  # 300 seconds
    check_inactive,
    guild_state
)

User: !play song A
Bot: Added to queue: 'Song A'
     Now playing: 'Song A'

User: !play song B
Bot: Added to queue: 'Song B'

User: !play song C
Bot: Added to queue: 'Song C'

[Queue state: current=Song A, queue=[Song B, Song C]]

# User rapidly adds 5 songs:
!play never gonna give you up
!play lofi hip hop
!play beethoven 9th
!play pink floyd
!play led zeppelin

# Bot processes in order:
Bot: Added to queue: 'Never Gonna Give You Up'
     Now playing: 'Never Gonna Give You Up'
     Added to queue: 'Lofi Hip Hop'
     Added to queue: 'Symphony No. 9'
     Added to queue: 'Pink Floyd - Comfortably Numb'
     Added to queue: 'Led Zeppelin - Stairway to Heaven'

# Playback proceeds sequentially without user intervention

[Queue: Song A (playing), Song B, Song C, Song D]

User: !skip
[Queue: Song B (playing), Song C, Song D]

User: !skip
[Queue: Song C (playing), Song D]

User: !play Song E
[Queue: Song C (playing), Song D, Song E]

[Song C finishes naturally]
[Queue: Song D (playing), Song E]

!play song A
!play song B  
!play song A  # Allowed - will play again

def get_or_create_guild_state(ctx: commands.Context) -> GuildPlayerState:
    guild_id = ctx.guild.id
    if guild_id not in guild_states:
        guild_states[guild_id] = GuildPlayerState(guild_id=guild_id, bot_instance=bot)
    
    guild_states[guild_id].last_ctx = ctx  # Update context
    return guild_states[guild_id]