Consolidate documentation into single FEATURES.md file
- Merged ADVANCED_FEATURES.md and NEW_FEATURES_SUMMARY.md into FEATURES.md - Provides comprehensive guide for all advanced features - Easier to maintain and navigate - Includes all examples and quick reference sections
This commit is contained in:
wizardoesmagic
parent
e5dd3aec86
commit
14044a3256
|
|
@ -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
|
## 📚 Table of Contents
|
||||||
|
|
||||||
1. [Track History](#track-history)
|
1. [Track History](#-track-history)
|
||||||
2. [Queue Statistics](#queue-statistics)
|
2. [Queue Statistics](#-queue-statistics)
|
||||||
3. [Playlist Manager](#playlist-manager)
|
3. [Playlist Manager](#-playlist-manager)
|
||||||
4. [Track Utilities](#track-utilities)
|
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
|
- Filter by requester
|
||||||
- Get unique tracks (remove duplicates)
|
- Get unique tracks (remove duplicates)
|
||||||
|
|
||||||
### Usage
|
### Basic Usage
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import pomice
|
import pomice
|
||||||
|
|
@ -57,6 +72,12 @@ history.clear()
|
||||||
- `is_empty` - Check if history is empty
|
- `is_empty` - Check if history is empty
|
||||||
- `current` - Get current track in navigation
|
- `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
|
## 📊 Queue Statistics
|
||||||
|
|
@ -72,7 +93,7 @@ Get detailed analytics about your queue contents.
|
||||||
- Stream detection
|
- Stream detection
|
||||||
- Playlist distribution
|
- Playlist distribution
|
||||||
|
|
||||||
### Usage
|
### Basic Usage
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import pomice
|
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
|
## 💾 Playlist Manager
|
||||||
|
|
@ -151,9 +178,7 @@ Export and import playlists to/from JSON and M3U formats.
|
||||||
- Remove duplicates
|
- Remove duplicates
|
||||||
- Playlist metadata
|
- Playlist metadata
|
||||||
|
|
||||||
### Usage
|
### Export Queue
|
||||||
|
|
||||||
#### Export Queue
|
|
||||||
```python
|
```python
|
||||||
import pomice
|
import pomice
|
||||||
|
|
||||||
|
|
@ -167,7 +192,7 @@ pomice.PlaylistManager.export_queue(
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Import Playlist
|
### Import Playlist
|
||||||
```python
|
```python
|
||||||
# Import playlist data
|
# Import playlist data
|
||||||
data = pomice.PlaylistManager.import_playlist('playlists/my_playlist.json')
|
data = pomice.PlaylistManager.import_playlist('playlists/my_playlist.json')
|
||||||
|
|
@ -182,7 +207,7 @@ for uri in uris:
|
||||||
await player.queue.put(results[0])
|
await player.queue.put(results[0])
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Export Track List
|
### Export Track List
|
||||||
```python
|
```python
|
||||||
# Export a list of tracks (not from queue)
|
# Export a list of tracks (not from queue)
|
||||||
tracks = [track1, track2, track3]
|
tracks = [track1, track2, track3]
|
||||||
|
|
@ -194,7 +219,7 @@ pomice.PlaylistManager.export_track_list(
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Merge Playlists
|
### Merge Playlists
|
||||||
```python
|
```python
|
||||||
# Merge multiple playlists into one
|
# Merge multiple playlists into one
|
||||||
pomice.PlaylistManager.merge_playlists(
|
pomice.PlaylistManager.merge_playlists(
|
||||||
|
|
@ -205,7 +230,7 @@ pomice.PlaylistManager.merge_playlists(
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Export to M3U
|
### Export to M3U
|
||||||
```python
|
```python
|
||||||
# Export to M3U format (compatible with many players)
|
# Export to M3U format (compatible with many players)
|
||||||
tracks = list(player.queue)
|
tracks = list(player.queue)
|
||||||
|
|
@ -216,7 +241,7 @@ pomice.PlaylistManager.export_to_m3u(
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Get Playlist Info
|
### Get Playlist Info
|
||||||
```python
|
```python
|
||||||
# Get metadata without loading all tracks
|
# Get metadata without loading all tracks
|
||||||
info = pomice.PlaylistManager.get_playlist_info('playlists/my_playlist.json')
|
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
|
## 🔧 Track Utilities
|
||||||
|
|
@ -351,13 +382,18 @@ grouped = pomice.SearchHelper.group_by_playlist(tracks)
|
||||||
random_tracks = pomice.SearchHelper.get_random_tracks(tracks, count=5)
|
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.
|
### Example 1: Basic Music Bot with History
|
||||||
|
|
||||||
### Quick Example
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import pomice
|
import pomice
|
||||||
|
|
@ -368,43 +404,181 @@ class Music(commands.Cog):
|
||||||
self.bot = bot
|
self.bot = bot
|
||||||
self.history = pomice.TrackHistory(max_size=100)
|
self.history = pomice.TrackHistory(max_size=100)
|
||||||
|
|
||||||
@commands.command()
|
@commands.Cog.listener()
|
||||||
async def stats(self, ctx):
|
async def on_pomice_track_end(self, player, track, _):
|
||||||
"""Show queue statistics."""
|
# Add to history when track ends
|
||||||
player = ctx.voice_client
|
self.history.add(track)
|
||||||
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()
|
@commands.command()
|
||||||
async def export(self, ctx):
|
async def history(self, ctx, limit: int = 10):
|
||||||
"""Export queue to file."""
|
"""Show recently played tracks."""
|
||||||
player = ctx.voice_client
|
recent = self.history.get_last(limit)
|
||||||
pomice.PlaylistManager.export_queue(
|
|
||||||
player.queue,
|
|
||||||
'my_playlist.json',
|
|
||||||
name=f"{ctx.guild.name}'s Queue"
|
|
||||||
)
|
|
||||||
await ctx.send('✅ Queue exported!')
|
|
||||||
|
|
||||||
@commands.command()
|
tracks_list = '\n'.join(
|
||||||
async def filter_long(self, ctx):
|
f"{i}. {track.title} by {track.author}"
|
||||||
"""Show tracks longer than 5 minutes."""
|
for i, track in enumerate(recent, 1)
|
||||||
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!')
|
await ctx.send(f"**Recently Played:**\n{tracks_list}")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
|
)
|
||||||
|
|
||||||
|
# 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)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
## 📝 Notes
|
||||||
|
|
||||||
- All duration values are in **milliseconds**
|
- 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
|
- Exported playlists are in JSON format by default
|
||||||
- M3U export is compatible with most media players
|
- M3U export is compatible with most media players
|
||||||
- All utilities work with standard Pomice Track objects
|
- 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
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -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! 🎵**
|
|
||||||
Loading…
Reference in New Issue