157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# PlaylistBuilder Class - Quick Reference
|
|
|
|
## Overview
|
|
|
|
The **PlaylistBuilder** class is a Python utility designed to create customized playlists efficiently. It manages cover images, tracks usage history to prevent duplication, and structures playlist data in a standardized JSON format. Ideal for applications requiring organized and visually appealing playlists, `PlaylistBuilder` simplifies the playlist creation process.
|
|
|
|
## Key Data Structures
|
|
|
|
### Difficulty
|
|
Represents the difficulty level of a song.
|
|
|
|
- **Attributes:**
|
|
- `name` (str): Difficulty name (e.g., "normal", "hard").
|
|
- `characteristic` (str): Mode or characteristic (e.g., "Standard").
|
|
|
|
### Song
|
|
Encapsulates song details within a playlist.
|
|
|
|
- **Attributes:**
|
|
- `hash` (str): Unique identifier for the song.
|
|
- `difficulties` (List[Difficulty]): Available difficulty levels.
|
|
- `key` (Optional[str]): Optional key identifier.
|
|
- `levelId` (Optional[str]): Optional custom level ID.
|
|
- `songName` (Optional[str]): Optional name of the song.
|
|
|
|
### CustomData
|
|
Holds additional metadata for the playlist.
|
|
|
|
- **Attributes:**
|
|
- `syncURL` (Optional[str])
|
|
- `owner` (Optional[str])
|
|
- `id` (Optional[str])
|
|
- `hash` (Optional[str])
|
|
- `shared` (Optional[bool])
|
|
|
|
### Playlist
|
|
Represents the complete playlist structure.
|
|
|
|
- **Attributes:**
|
|
- `playlistTitle` (str): Title of the playlist.
|
|
- `songs` (List[Song]): List of songs included.
|
|
- `playlistAuthor` (Optional[str]): Author of the playlist.
|
|
- `image` (Optional[str]): Base64-encoded cover image.
|
|
- `coverImage` (Optional[str]): File path to the cover image.
|
|
- `description` (Optional[str]): Description of the playlist.
|
|
- `allowDuplicates` (Optional[bool]): Flag to allow duplicate songs.
|
|
- `customData` (Optional[CustomData]): Additional metadata.
|
|
|
|
## PlaylistBuilder Class
|
|
|
|
### Initialization
|
|
|
|
```python
|
|
def __init__(self, covers_dir="./covers", history_file="./playlist_history.json", output_dir=None):
|
|
```
|
|
|
|
- **Parameters:**
|
|
- `covers_dir` (str): Directory containing cover images.
|
|
- `history_file` (str): Path to the JSON file tracking used covers.
|
|
- `output_dir` (Optional[str]): Directory to save generated playlists. Defaults to current working directory.
|
|
|
|
- **Behavior:**
|
|
- Ensures the covers directory exists.
|
|
- Loads or initializes the history of used covers.
|
|
|
|
### Methods
|
|
|
|
#### `create_playlist`
|
|
|
|
Generates a playlist based on provided song data.
|
|
|
|
```python
|
|
def create_playlist(self, playlist_data: List[Dict], playlist_title: str = "playlist", playlist_author: str = "SaberList Tool") -> str:
|
|
```
|
|
|
|
- **Parameters:**
|
|
- `playlist_data` (List[Dict]): List of song dictionaries.
|
|
- `playlist_title` (str): Title of the playlist.
|
|
- `playlist_author` (str): Author of the playlist.
|
|
|
|
- **Returns:**
|
|
- `str`: File path to the created playlist.
|
|
|
|
- **Behavior:**
|
|
- Converts song dictionaries to `Song` instances.
|
|
- Selects a random unused cover image.
|
|
- Encodes the cover image to Base64.
|
|
- Constructs a `Playlist` instance.
|
|
- Saves the playlist as a `.bplist` JSON file.
|
|
- Updates the history of used covers.
|
|
|
|
## Usage Example
|
|
|
|
```python
|
|
from src.saberlist.PlaylistBuilder import PlaylistBuilder
|
|
|
|
# Initialize PlaylistBuilder
|
|
builder = PlaylistBuilder(
|
|
covers_dir="./covers",
|
|
history_file="./playlist_history.json",
|
|
output_dir="./playlists"
|
|
)
|
|
|
|
# Define song data
|
|
sample_song = {
|
|
"hash": "7c9e0a7c523395c7ef9d79006b9d42dc6ab8b44a",
|
|
"key": "2a44e",
|
|
"levelId": "custom_level_7c9e0a7c523395c7ef9d79006b9d42dc6ab8b44a",
|
|
"songName": "Gleodream",
|
|
"difficulties": [
|
|
{
|
|
"name": "normal",
|
|
"characteristic": "Standard"
|
|
}
|
|
]
|
|
}
|
|
|
|
# Create the playlist
|
|
playlist_path = builder.create_playlist(
|
|
playlist_data=[sample_song],
|
|
playlist_title="Chill Vibes",
|
|
playlist_author="Alice Smith"
|
|
)
|
|
|
|
print(f"Playlist created at: {playlist_path}")
|
|
```
|
|
|
|
## Handling Cover Images
|
|
|
|
- **Adding Covers:** Place `.jpg` images in the `covers_dir`. The `PlaylistBuilder` selects an unused cover for each playlist.
|
|
- **Preventing Duplicates:** The `history_file` tracks used covers to avoid repetition until all covers are utilized.
|
|
- **Resetting History:** Delete or modify `playlist_history.json` to reset cover usage history.
|
|
|
|
## File Structures
|
|
|
|
### Playlist File (`.bplist`)
|
|
|
|
- **Format:** JSON
|
|
- **Contents:**
|
|
- Playlist metadata (title, author, description).
|
|
- List of songs with details.
|
|
- Base64-encoded cover image.
|
|
- Path to the cover image file.
|
|
|
|
### History File (`playlist_history.json`)
|
|
|
|
- **Format:** JSON
|
|
- **Contents:**
|
|
- `used_covers`: Array of filenames that have been used as covers.
|
|
|
|
## Additional Information
|
|
|
|
- **Logging:** The class logs important actions, such as creating directories and handling missing covers.
|
|
- **Extensibility:** Easily extendable to support more image formats or additional metadata fields.
|
|
- **Dependencies:** Utilizes Python's standard libraries (`os`, `json`, `random`, etc.) and `dataclasses` for structured data.
|
|
|
|
--- |