pomice/FEATURES.md

Pomice Advanced Features Guide

🎉 Overview

Pomice now comes with built-in advanced features to help you build powerful music bots. These features are integrated directly into the Player and Queue classes, providing a "batteries-included" experience.

Key Enhancements

• Integrated Queue & History: Every Player now has its own queue and history automatically.
• Auto-History: Tracks are automatically added to history when they finish playing.
• Advanced Analytics: Detailed statistics available directly via player.get_stats() or queue.get_stats().
• Integrated Utilities: Filtering, sorting, and playlist management.

---

📚 Table of Contents

1. Integrated Features
2. Track History
3. Queue Statistics
4. Playlist Manager
5. Track Utilities
6. Complete Examples

---

🚀 Integrated Features

Since these features are now part of the core classes, usage is extremely simple:

# Every player now has a queue and history by default
player = ctx.voice_client

# Access the queue
player.queue.put(track)

# Play the next track from the queue
await player.do_next()

# Access the history (automatically updated)
last_song = player.history.current

# Get real-time statistics
stats = player.get_stats()
print(f"Queue Duration: {stats.format_duration(stats.total_duration)}")

---

🕐 Track History

The player.history object automatically tracks every song that finishes playing.

Features

• Configurable maximum history size (default: 100)
• Navigation: get_previous(), get_next()
• Search: history.search("query")
• Filter: get_by_requester(user_id)
• Unique tracks: get_unique_tracks()

Usage

# Show last 10 songs
recent = player.history.get_last(10)

# Search history
results = player.history.search("Imagine Dragons")

# Play previous track
prev = player.history.get_previous()
if prev:
    await player.play(prev)

---

📊 Queue Statistics

Access advanced analytics via player.get_stats() or player.queue.get_stats().

Features

• Total/Average duration
• Longest/Shortest tracks
• Requester analytics (who added what)
• Author distribution
• Duration breakdown (short/medium/long)

Usage

stats = player.get_stats()
summary = stats.get_summary()

print(f"Total Tracks: {summary['total_tracks']}")
print(f"Total Duration: {summary['total_duration_formatted']}")

# Who added the most songs?
top = stats.get_top_requesters(3)
for user, count in top:
    print(f"{user.display_name}: {count} tracks")

---

💾 Playlist Manager

Export and import playlists to/from JSON and M3U formats.

Usage

import pomice

# Export current queue to file
pomice.PlaylistManager.export_queue(
    player.queue,
    filepath='playlists/party.json',
    name='Party Mix'
)

# Import a playlist
data = pomice.PlaylistManager.import_playlist('playlists/rock.json')
uris = pomice.PlaylistManager.get_track_uris('playlists/rock.json')

for uri in uris:
    results = await player.get_tracks(query=uri)
    if results:
        player.queue.put(results[0])

---

🔧 Track Utilities

Advanced filtering and sorting.

Filtering

import pomice

tracks = list(player.queue)

# Get tracks under 5 minutes
short = pomice.TrackFilter.by_duration(tracks, max_duration=300000)

# Get tracks by a specific artist
artist_songs = pomice.TrackFilter.by_author(tracks, "Artist Name")

Sorting

# Sort queue by title
sorted_tracks = pomice.SearchHelper.sort_by_title(list(player.queue))

# Clear and refill with sorted tracks
player.queue.clear()
player.queue.extend(sorted_tracks)

---

🎯 Complete Examples

Integrated Music Cog

import pomice
from discord.ext import commands

class Music(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
    
    @commands.command()
    async def play(self, ctx, *, search: str):
        if not ctx.voice_client:
            await ctx.author.voice.channel.connect(cls=pomice.Player)
        
        player = ctx.voice_client
        results = await player.get_tracks(query=search, ctx=ctx)
        
        if not results:
            return await ctx.send("No results.")
            
        track = results[0]
        player.queue.put(track)
        await ctx.send(f"Added **{track.title}** to queue.")
        
        if not player.is_playing:
            await player.do_next()

    @commands.command()
    async def history(self, ctx):
        """Show recently played songs."""
        player = ctx.voice_client
        recent = player.history.get_last(5)
        
        msg = "\n".join(f"{i}. {t.title}" for i, t in enumerate(recent, 1))
        await ctx.send(f"**Recently Played:**\n{msg}")

    @commands.command()
    async def stats(self, ctx):
        """Show queue analytics."""
        stats = ctx.voice_client.get_stats()
        summary = stats.get_summary()
        
        await ctx.send(
            f"**Queue Stats**\n"
            f"Tracks: {summary['total_tracks']}\n"
            f"Duration: {summary['total_duration_formatted']}"
        )

---

📖 Quick Reference

Feature	Integrated Access
Queue	player.queue
History	player.history
Statistics	player.get_stats()
Next Track	await player.do_next()

---

Happy coding! 🎵