# Pomice Advanced Features This document describes the new advanced features added to Pomice to enhance your music bot capabilities. ## 📚 Table of Contents 1. [Track History](#track-history) 2. [Queue Statistics](#queue-statistics) 3. [Playlist Manager](#playlist-manager) 4. [Track Utilities](#track-utilities) --- ## 🕐 Track History Keep track of previously played songs with navigation and search capabilities. ### Features - Configurable maximum history size - Navigation (previous/next) - Search through history - Filter by requester - Get unique tracks (remove duplicates) ### Usage ```python import pomice # Create a history tracker history = pomice.TrackHistory(max_size=100) # Add tracks as they play history.add(track) # Get last 10 played tracks recent = history.get_last(10) # Search history results = history.search("Imagine Dragons") # Get tracks by specific user user_tracks = history.get_by_requester(user_id=123456789) # Navigate through history previous_track = history.get_previous() next_track = history.get_next() # Get all unique tracks (removes duplicates) unique = history.get_unique_tracks() # Clear history history.clear() ``` ### Properties - `is_empty` - Check if history is empty - `current` - Get current track in navigation --- ## 📊 Queue Statistics Get detailed analytics about your queue contents. ### Features - Total and average duration - Longest/shortest tracks - Requester statistics - Author distribution - Duration breakdown - Stream detection - Playlist distribution ### Usage ```python import pomice # Create stats for a queue stats = pomice.QueueStats(player.queue) # Get total duration total_ms = stats.total_duration formatted = stats.format_duration(total_ms) # "1:23:45" # Get average duration avg_ms = stats.average_duration # Find longest and shortest tracks longest = stats.longest_track shortest = stats.shortest_track # Get requester statistics requester_stats = stats.get_requester_stats() # Returns: {user_id: {'count': 5, 'total_duration': 900000, 'tracks': [...]}} # Get top requesters top_requesters = stats.get_top_requesters(limit=5) # Returns: [(requester, count), ...] # Get author distribution authors = stats.get_author_distribution() # Returns: {'Artist Name': track_count, ...} # Get top authors top_authors = stats.get_top_authors(limit=10) # Returns: [('Artist Name', count), ...] # Get duration breakdown breakdown = stats.get_duration_breakdown() # Returns: {'short': 10, 'medium': 25, 'long': 5, 'very_long': 2} # Get stream count streams = stats.get_stream_count() # Get comprehensive summary summary = stats.get_summary() ``` ### Summary Dictionary ```python { 'total_tracks': 42, 'total_duration': 7200000, # milliseconds 'total_duration_formatted': '2:00:00', 'average_duration': 171428.57, 'average_duration_formatted': '2:51', 'longest_track': Track(...), 'shortest_track': Track(...), 'stream_count': 3, 'unique_authors': 15, 'unique_requesters': 5, 'duration_breakdown': {...}, 'loop_mode': LoopMode.QUEUE, 'is_looping': True } ``` --- ## 💾 Playlist Manager Export and import playlists to/from JSON and M3U formats. ### Features - Export queue to JSON - Import playlists from JSON - Export to M3U format - Merge multiple playlists - Remove duplicates - Playlist metadata ### Usage #### Export Queue ```python import pomice # Export current queue pomice.PlaylistManager.export_queue( player.queue, filepath='playlists/my_playlist.json', name='My Awesome Playlist', description='Best songs ever', include_metadata=True # Include requester info ) ``` #### Import Playlist ```python # Import playlist data data = pomice.PlaylistManager.import_playlist('playlists/my_playlist.json') # Get just the URIs uris = pomice.PlaylistManager.get_track_uris('playlists/my_playlist.json') # Load tracks into queue for uri in uris: results = await player.get_tracks(query=uri) if results: await player.queue.put(results[0]) ``` #### Export Track List ```python # Export a list of tracks (not from queue) tracks = [track1, track2, track3] pomice.PlaylistManager.export_track_list( tracks, filepath='playlists/favorites.json', name='Favorites', description='My favorite tracks' ) ``` #### Merge Playlists ```python # Merge multiple playlists into one pomice.PlaylistManager.merge_playlists( filepaths=['playlist1.json', 'playlist2.json', 'playlist3.json'], output_path='merged_playlist.json', name='Mega Playlist', remove_duplicates=True # Remove duplicate tracks ) ``` #### Export to M3U ```python # Export to M3U format (compatible with many players) tracks = list(player.queue) pomice.PlaylistManager.export_to_m3u( tracks, filepath='playlists/my_playlist.m3u', name='My Playlist' ) ``` #### Get Playlist Info ```python # Get metadata without loading all tracks info = pomice.PlaylistManager.get_playlist_info('playlists/my_playlist.json') # Returns: {'name': '...', 'track_count': 42, 'total_duration': 7200000, ...} ``` ### JSON Format ```json { "name": "My Playlist", "description": "Best songs", "created_at": "2024-01-15T12:30:00", "track_count": 10, "total_duration": 1800000, "version": "1.0", "tracks": [ { "title": "Song Title", "author": "Artist Name", "uri": "https://...", "identifier": "abc123", "length": 180000, "thumbnail": "https://...", "isrc": "USRC12345678", "requester_id": 123456789, "requester_name": "User#1234" } ] } ``` --- ## 🔧 Track Utilities Advanced filtering, searching, and sorting utilities for tracks. ### TrackFilter Filter tracks by various criteria. ```python import pomice tracks = list(player.queue) # Filter by duration (milliseconds) short_tracks = pomice.TrackFilter.by_duration( tracks, min_duration=60000, # 1 minute max_duration=300000 # 5 minutes ) # Filter by author artist_tracks = pomice.TrackFilter.by_author( tracks, author='Imagine Dragons', exact=False # Case-insensitive contains ) # Filter by title title_tracks = pomice.TrackFilter.by_title( tracks, title='Thunder', exact=True # Exact match ) # Filter by requester user_tracks = pomice.TrackFilter.by_requester(tracks, requester_id=123456789) # Filter by playlist playlist_tracks = pomice.TrackFilter.by_playlist(tracks, playlist_name='Rock Hits') # Get only streams streams = pomice.TrackFilter.streams_only(tracks) # Get only non-streams non_streams = pomice.TrackFilter.non_streams_only(tracks) # Custom filter with lambda long_tracks = pomice.TrackFilter.custom( tracks, predicate=lambda t: t.length > 600000 # > 10 minutes ) ``` ### SearchHelper Search, sort, and organize tracks. ```python import pomice tracks = list(player.queue) # Search tracks results = pomice.SearchHelper.search_tracks( tracks, query='imagine', search_title=True, search_author=True, case_sensitive=False ) # Sort by duration sorted_tracks = pomice.SearchHelper.sort_by_duration( tracks, reverse=True # Longest first ) # Sort by title (alphabetically) sorted_tracks = pomice.SearchHelper.sort_by_title(tracks) # Sort by author sorted_tracks = pomice.SearchHelper.sort_by_author(tracks) # Remove duplicates unique_tracks = pomice.SearchHelper.remove_duplicates( tracks, by_uri=True, # Remove by URI by_title_author=False # Or by title+author combo ) # Group by author grouped = pomice.SearchHelper.group_by_author(tracks) # Returns: {'Artist Name': [track1, track2, ...], ...} # Group by playlist grouped = pomice.SearchHelper.group_by_playlist(tracks) # Get random tracks random_tracks = pomice.SearchHelper.get_random_tracks(tracks, count=5) ``` --- ## 🎯 Complete Example See `examples/advanced_features.py` for a complete bot example using all these features. ### Quick Example ```python import pomice from discord.ext import commands class Music(commands.Cog): def __init__(self, bot): self.bot = bot self.history = pomice.TrackHistory(max_size=100) @commands.command() async def stats(self, ctx): """Show queue statistics.""" player = ctx.voice_client stats = pomice.QueueStats(player.queue) summary = stats.get_summary() await ctx.send( f"**Queue Stats**\n" f"Tracks: {summary['total_tracks']}\n" f"Duration: {summary['total_duration_formatted']}\n" f"Streams: {summary['stream_count']}" ) @commands.command() async def export(self, ctx): """Export queue to file.""" player = ctx.voice_client pomice.PlaylistManager.export_queue( player.queue, 'my_playlist.json', name=f"{ctx.guild.name}'s Queue" ) await ctx.send('✅ Queue exported!') @commands.command() async def filter_long(self, ctx): """Show tracks longer than 5 minutes.""" player = ctx.voice_client tracks = list(player.queue) long_tracks = pomice.TrackFilter.by_duration( tracks, min_duration=300000 # 5 minutes ) await ctx.send(f'Found {len(long_tracks)} long tracks!') ``` --- ## 📝 Notes - All duration values are in **milliseconds** - History is per-guild (you should maintain separate histories for each guild) - Exported playlists are in JSON format by default - M3U export is compatible with most media players - All utilities work with standard Pomice Track objects ## 🤝 Contributing Feel free to suggest more features or improvements! --- **Happy coding! 🎵**