beatsaber-playlist-tool/docs/PlaylistBuilder.md

# 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.

---