diff --git a/ADVANCED_FEATURES.md b/FEATURES.md similarity index 50% rename from ADVANCED_FEATURES.md rename to FEATURES.md index e816bc0..9da1ce3 100644 --- a/ADVANCED_FEATURES.md +++ b/FEATURES.md @@ -1,13 +1,28 @@ -# Pomice Advanced Features +# Pomice Advanced Features Guide -This document describes the new advanced features added to Pomice to enhance your music bot capabilities. +## 🎉 Overview + +This guide covers the advanced features added to Pomice to enhance your music bot capabilities. These features include track history, queue statistics, playlist management, and advanced track utilities. + +### What's New + +- **Track History**: Keep track of previously played songs with navigation and search +- **Queue Statistics**: Detailed analytics about queue contents (duration, requesters, etc.) +- **Playlist Manager**: Export/import playlists to JSON and M3U formats +- **Track Utilities**: Advanced filtering, searching, and sorting capabilities + +All features are **fully backward compatible** and **optional** - use what you need! + +--- ## 📚 Table of Contents -1. [Track History](#track-history) -2. [Queue Statistics](#queue-statistics) -3. [Playlist Manager](#playlist-manager) -4. [Track Utilities](#track-utilities) +1. [Track History](#-track-history) +2. [Queue Statistics](#-queue-statistics) +3. [Playlist Manager](#-playlist-manager) +4. [Track Utilities](#-track-utilities) +5. [Complete Examples](#-complete-examples) +6. [Quick Reference](#-quick-reference) --- @@ -22,7 +37,7 @@ Keep track of previously played songs with navigation and search capabilities. - Filter by requester - Get unique tracks (remove duplicates) -### Usage +### Basic Usage ```python import pomice @@ -57,6 +72,12 @@ history.clear() - `is_empty` - Check if history is empty - `current` - Get current track in navigation +### Use Cases +- "What was that song that just played?" +- "Show me the last 10 songs" +- "Play the previous track" +- "Show all songs requested by User X" + --- ## 📊 Queue Statistics @@ -72,7 +93,7 @@ Get detailed analytics about your queue contents. - Stream detection - Playlist distribution -### Usage +### Basic Usage ```python import pomice @@ -137,6 +158,12 @@ summary = stats.get_summary() } ``` +### Use Cases +- "How long is the queue?" +- "Who added the most songs?" +- "What's the longest track?" +- "Show me queue statistics" + --- ## 💾 Playlist Manager @@ -151,9 +178,7 @@ Export and import playlists to/from JSON and M3U formats. - Remove duplicates - Playlist metadata -### Usage - -#### Export Queue +### Export Queue ```python import pomice @@ -167,7 +192,7 @@ pomice.PlaylistManager.export_queue( ) ``` -#### Import Playlist +### Import Playlist ```python # Import playlist data data = pomice.PlaylistManager.import_playlist('playlists/my_playlist.json') @@ -182,7 +207,7 @@ for uri in uris: await player.queue.put(results[0]) ``` -#### Export Track List +### Export Track List ```python # Export a list of tracks (not from queue) tracks = [track1, track2, track3] @@ -194,7 +219,7 @@ pomice.PlaylistManager.export_track_list( ) ``` -#### Merge Playlists +### Merge Playlists ```python # Merge multiple playlists into one pomice.PlaylistManager.merge_playlists( @@ -205,7 +230,7 @@ pomice.PlaylistManager.merge_playlists( ) ``` -#### Export to M3U +### Export to M3U ```python # Export to M3U format (compatible with many players) tracks = list(player.queue) @@ -216,7 +241,7 @@ pomice.PlaylistManager.export_to_m3u( ) ``` -#### Get Playlist Info +### Get Playlist Info ```python # Get metadata without loading all tracks info = pomice.PlaylistManager.get_playlist_info('playlists/my_playlist.json') @@ -248,6 +273,12 @@ info = pomice.PlaylistManager.get_playlist_info('playlists/my_playlist.json') } ``` +### Use Cases +- "Save this queue for later" +- "Load my favorite playlist" +- "Merge all my playlists" +- "Export to M3U for my media player" + --- ## 🔧 Track Utilities @@ -351,13 +382,18 @@ grouped = pomice.SearchHelper.group_by_playlist(tracks) random_tracks = pomice.SearchHelper.get_random_tracks(tracks, count=5) ``` +### Use Cases +- "Show me all songs by Artist X" +- "Find tracks between 3-5 minutes" +- "Sort queue by duration" +- "Remove duplicate songs" +- "Play 5 random tracks" + --- -## 🎯 Complete Example +## 🎯 Complete Examples -See `examples/advanced_features.py` for a complete bot example using all these features. - -### Quick Example +### Example 1: Basic Music Bot with History ```python import pomice @@ -367,44 +403,182 @@ class Music(commands.Cog): def __init__(self, bot): self.bot = bot self.history = pomice.TrackHistory(max_size=100) - + + @commands.Cog.listener() + async def on_pomice_track_end(self, player, track, _): + # Add to history when track ends + self.history.add(track) + @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']}" + async def history(self, ctx, limit: int = 10): + """Show recently played tracks.""" + recent = self.history.get_last(limit) + + tracks_list = '\n'.join( + f"{i}. {track.title} by {track.author}" + for i, track in enumerate(recent, 1) ) + + await ctx.send(f"**Recently Played:**\n{tracks_list}") +``` - @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" +### Example 2: Queue Statistics Command + +```python +@commands.command() +async def stats(self, ctx): + """Show queue statistics.""" + player = ctx.voice_client + stats = pomice.QueueStats(player.queue) + summary = stats.get_summary() + + embed = discord.Embed(title='📊 Queue Statistics', color=discord.Color.green()) + + embed.add_field(name='Total Tracks', value=summary['total_tracks'], inline=True) + embed.add_field(name='Total Duration', value=summary['total_duration_formatted'], inline=True) + embed.add_field(name='Average Duration', value=summary['average_duration_formatted'], inline=True) + + if summary['longest_track']: + embed.add_field( + name='Longest Track', + value=f"{summary['longest_track'].title} ({stats.format_duration(summary['longest_track'].length)})", + inline=False ) - 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 + + # Top requesters + top_requesters = stats.get_top_requesters(3) + if top_requesters: + requesters_text = '\n'.join( + f'{i}. {req.display_name}: {count} tracks' + for i, (req, count) in enumerate(top_requesters, 1) ) + embed.add_field(name='Top Requesters', value=requesters_text, inline=False) + + await ctx.send(embed=embed) +``` - await ctx.send(f'Found {len(long_tracks)} long tracks!') +### Example 3: Export/Import Playlists + +```python +@commands.command() +async def export(self, ctx, filename: str = 'playlist.json'): + """Export current queue to a file.""" + player = ctx.voice_client + + pomice.PlaylistManager.export_queue( + player.queue, + f'playlists/{filename}', + name=f"{ctx.guild.name}'s Playlist", + description=f'Exported from {ctx.guild.name}' + ) + await ctx.send(f'✅ Queue exported to `playlists/{filename}`') + +@commands.command() +async def import_playlist(self, ctx, filename: str): + """Import a playlist from a file.""" + player = ctx.voice_client + + data = pomice.PlaylistManager.import_playlist(f'playlists/{filename}') + uris = [track['uri'] for track in data['tracks'] if track.get('uri')] + + added = 0 + for uri in uris: + results = await player.get_tracks(query=uri, ctx=ctx) + if results: + await player.queue.put(results[0]) + added += 1 + + await ctx.send(f'✅ Imported {added} tracks from `{data["name"]}`') +``` + +### Example 4: Filter and Sort Queue + +```python +@commands.command() +async def filter_short(self, ctx): + """Show tracks shorter than 3 minutes.""" + player = ctx.voice_client + tracks = list(player.queue) + + short_tracks = pomice.TrackFilter.by_duration( + tracks, + max_duration=180000 # 3 minutes in ms + ) + + await ctx.send(f'Found {len(short_tracks)} tracks under 3 minutes!') + +@commands.command() +async def sort_queue(self, ctx, sort_by: str = 'duration'): + """Sort the queue by duration, title, or author.""" + player = ctx.voice_client + queue_tracks = list(player.queue) + + if sort_by == 'duration': + sorted_tracks = pomice.SearchHelper.sort_by_duration(queue_tracks) + elif sort_by == 'title': + sorted_tracks = pomice.SearchHelper.sort_by_title(queue_tracks) + elif sort_by == 'author': + sorted_tracks = pomice.SearchHelper.sort_by_author(queue_tracks) + else: + return await ctx.send('Valid options: duration, title, author') + + # Clear and refill queue + player.queue._queue.clear() + for track in sorted_tracks: + await player.queue.put(track) + + await ctx.send(f'✅ Queue sorted by {sort_by}') +``` + +--- + +## 📖 Quick Reference + +### Track History +```python +history = pomice.TrackHistory(max_size=100) +history.add(track) +recent = history.get_last(10) +results = history.search("query") +previous = history.get_previous() +unique = history.get_unique_tracks() +``` + +### Queue Statistics +```python +stats = pomice.QueueStats(queue) +total = stats.total_duration +formatted = stats.format_duration(total) +top_users = stats.get_top_requesters(5) +summary = stats.get_summary() +``` + +### Playlist Manager +```python +# Export +pomice.PlaylistManager.export_queue(queue, 'playlist.json') + +# Import +data = pomice.PlaylistManager.import_playlist('playlist.json') + +# Merge +pomice.PlaylistManager.merge_playlists(['p1.json', 'p2.json'], 'merged.json') + +# M3U +pomice.PlaylistManager.export_to_m3u(tracks, 'playlist.m3u') +``` + +### Track Utilities +```python +# Filter +short = pomice.TrackFilter.by_duration(tracks, max_duration=180000) +artist = pomice.TrackFilter.by_author(tracks, "Artist Name") + +# Search & Sort +results = pomice.SearchHelper.search_tracks(tracks, "query") +sorted_tracks = pomice.SearchHelper.sort_by_duration(tracks) +unique = pomice.SearchHelper.remove_duplicates(tracks) +random = pomice.SearchHelper.get_random_tracks(tracks, 5) ``` --- @@ -412,14 +586,37 @@ class Music(commands.Cog): ## 📝 Notes - All duration values are in **milliseconds** -- History is per-guild (you should maintain separate histories for each guild) +- History should be maintained per-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! +## 🚀 Getting Started + +1. **Import the features you need**: + ```python + import pomice + ``` + +2. **Use them in your commands**: + ```python + history = pomice.TrackHistory() + stats = pomice.QueueStats(player.queue) + ``` + +3. **Check the examples** in `examples/advanced_features.py` for a complete bot + +4. **Experiment** and customize to fit your needs! + +--- + +## 🎓 Additional Resources + +- **Full Example Bot**: See `examples/advanced_features.py` +- **Main Documentation**: See the main Pomice README +- **Discord Support**: Join the Pomice Discord server --- diff --git a/NEW_FEATURES_SUMMARY.md b/NEW_FEATURES_SUMMARY.md deleted file mode 100644 index 423f4b9..0000000 --- a/NEW_FEATURES_SUMMARY.md +++ /dev/null @@ -1,301 +0,0 @@ -# Pomice Enhancement Summary - -## 🎉 New Features Added - -This update adds **4 major feature modules** to enhance Pomice's capabilities for building advanced music bots. - ---- - -## 📦 New Modules - -### 1. **Track History** (`pomice/history.py`) -- **Purpose**: Keep track of previously played songs -- **Key Features**: - - Configurable history size (default: 100 tracks) - - Navigation (previous/next track) - - Search through history by title/author - - Filter by requester - - Get unique tracks (removes duplicates) - - Get last N played tracks -- **Use Cases**: - - "What was that song that just played?" - - "Show me the last 10 songs" - - "Play the previous track" - - "Show all songs requested by User X" - -### 2. **Queue Statistics** (`pomice/queue_stats.py`) -- **Purpose**: Detailed analytics about queue contents -- **Key Features**: - - Total and average duration calculations - - Find longest/shortest tracks - - Requester statistics (who added what) - - Author distribution (most common artists) - - Duration breakdown (short/medium/long/very long) - - Stream detection - - Playlist distribution - - Comprehensive summary with formatted output -- **Use Cases**: - - "How long is the queue?" - - "Who added the most songs?" - - "What's the longest track?" - - "Show me queue statistics" - -### 3. **Playlist Manager** (`pomice/playlist_manager.py`) -- **Purpose**: Export and import playlists -- **Key Features**: - - Export queue to JSON format - - Import playlists from JSON - - Export to M3U format (universal compatibility) - - Merge multiple playlists - - Remove duplicates when merging - - Get playlist metadata without loading all tracks - - Export track lists (not just queues) -- **Use Cases**: - - "Save this queue for later" - - "Load my favorite playlist" - - "Merge all my playlists" - - "Export to M3U for my media player" - -### 4. **Track Utilities** (`pomice/track_utils.py`) -- **Purpose**: Advanced filtering, searching, and sorting -- **Key Features**: - - **TrackFilter**: - - Filter by duration range - - Filter by author (exact or contains) - - Filter by title - - Filter by requester - - Filter by playlist - - Streams only / non-streams only - - Custom filter with lambda functions - - **SearchHelper**: - - Search tracks by query - - Sort by duration/title/author - - Remove duplicates (by URI or title+author) - - Group by author or playlist - - Get random tracks -- **Use Cases**: - - "Show me all songs by Artist X" - - "Find tracks between 3-5 minutes" - - "Sort queue by duration" - - "Remove duplicate songs" - - "Play 5 random tracks" - ---- - -## 📁 Files Added - -``` -pomice/ -├── history.py # Track history system -├── queue_stats.py # Queue statistics -├── playlist_manager.py # Playlist export/import -├── track_utils.py # Filtering and search utilities -└── __init__.py # Updated to export new modules - -examples/ -└── advanced_features.py # Complete example bot - -ADVANCED_FEATURES.md # Comprehensive documentation -NEW_FEATURES_SUMMARY.md # This file -``` - ---- - -## 🚀 Quick Start - -### Installation -The new features are automatically available when you import pomice: - -```python -import pomice - -# All new features are now available -history = pomice.TrackHistory() -stats = pomice.QueueStats(queue) -pomice.PlaylistManager.export_queue(...) -filtered = pomice.TrackFilter.by_author(tracks, "Artist") -``` - -### Basic Usage 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.Cog.listener() - async def on_pomice_track_end(self, player, track, _): - # Add to history when track ends - self.history.add(track) - - @commands.command() - async def stats(self, ctx): - """Show queue statistics.""" - stats = pomice.QueueStats(ctx.voice_client.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']}\n" - f"👥 Unique Requesters: {summary['unique_requesters']}" - ) - - @commands.command() - async def history(self, ctx, limit: int = 10): - """Show recently played tracks.""" - recent = self.history.get_last(limit) - - tracks_list = '\n'.join( - f"{i}. {track.title} by {track.author}" - for i, track in enumerate(recent, 1) - ) - - await ctx.send(f"**Recently Played:**\n{tracks_list}") - - @commands.command() - async def export(self, ctx): - """Export current queue.""" - pomice.PlaylistManager.export_queue( - ctx.voice_client.queue, - f'playlists/{ctx.guild.id}.json', - name=f"{ctx.guild.name}'s Queue" - ) - await ctx.send('✅ Queue exported!') -``` - ---- - -## 📊 Statistics - -- **Total Lines of Code**: ~1,200+ lines -- **New Classes**: 6 (TrackHistory, QueueStats, PlaylistManager, TrackFilter, SearchHelper) -- **New Methods**: 50+ -- **Documentation**: Complete with examples - ---- - -## 🎯 Benefits - -1. **Enhanced User Experience** - - Users can see what played recently - - Detailed queue information - - Save and load playlists - -2. **Better Bot Management** - - Track who's adding what - - Analyze queue patterns - - Filter and organize tracks efficiently - -3. **Persistence** - - Save queues for later - - Share playlists between servers - - Export to universal formats (M3U) - -4. **Flexibility** - - Custom filtering with lambdas - - Multiple sort options - - Comprehensive search capabilities - ---- - -## 🔧 Compatibility - -- ✅ **Fully compatible** with existing Pomice code -- ✅ **No breaking changes** to existing functionality -- ✅ **Optional features** - use what you need -- ✅ **Type hints** included for better IDE support -- ✅ **Documented** with docstrings and examples - ---- - -## 📚 Documentation - -- **Full Documentation**: See `ADVANCED_FEATURES.md` -- **Example Bot**: See `examples/advanced_features.py` -- **Inline Docs**: All functions have comprehensive docstrings - ---- - -## 🐛 Testing - -All modules have been: -- ✅ Syntax checked with `py_compile` -- ✅ Type hints verified -- ✅ Tested for import compatibility -- ✅ Documented with examples - ---- - -## 🎓 Learning Resources - -1. Read `ADVANCED_FEATURES.md` for detailed usage -2. Check `examples/advanced_features.py` for a complete bot -3. Explore the docstrings in each module -4. Experiment with the features in your own bot - ---- - -## 🚀 Next Steps - -1. **Try the features** in your bot -2. **Read the documentation** in `ADVANCED_FEATURES.md` -3. **Run the example** in `examples/advanced_features.py` -4. **Customize** to fit your needs - ---- - -## 💡 Feature Highlights - -### Track History -```python -history = pomice.TrackHistory(max_size=100) -history.add(track) -recent = history.get_last(10) -results = history.search("Imagine Dragons") -``` - -### Queue Statistics -```python -stats = pomice.QueueStats(queue) -print(f"Total: {stats.format_duration(stats.total_duration)}") -top_requesters = stats.get_top_requesters(5) -``` - -### Playlist Manager -```python -# Export -pomice.PlaylistManager.export_queue(queue, 'playlist.json') - -# Import -data = pomice.PlaylistManager.import_playlist('playlist.json') - -# Merge -pomice.PlaylistManager.merge_playlists( - ['p1.json', 'p2.json'], - 'merged.json', - remove_duplicates=True -) -``` - -### Track Utilities -```python -# Filter -short = pomice.TrackFilter.by_duration(tracks, max_duration=180000) -artist = pomice.TrackFilter.by_author(tracks, "Imagine Dragons") - -# Sort -sorted_tracks = pomice.SearchHelper.sort_by_duration(tracks) - -# Search -results = pomice.SearchHelper.search_tracks(tracks, "thunder") -``` - ---- - -**Enjoy the new features! 🎵**