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

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.

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

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.

---