How it Works

General

Playlist Archiver works by utilizing the YouTube Data API to retrieve metadata from playlists. It parses playlist URLs to extract IDs and fetches data, which is then serialized and saved locally in structured JSON files. JSON files are deserialized when needed. The program uses the Spotify API to export playlists by creating new Spotify playlists and matching YouTube songs to Spotify tracks.
Backend of the application is generally represented by classes listed bellow. Code responsible for GUI and CLI will not be described here.

1. Caller Class
2. Playlist Manager Class
3. Parser Class

Caller Class

The Caller class is designed for interacting with the YouTube Data API and Spotify API to retrieve and manage playlists. Its methods are focused on fetching data, and exporting data to Spotify.

Public Methods

get_playlist_response(address: str) -> tuple

Fetches metadata and all videos in a YouTube playlist from its URL. Input: Playlist URL (address) Output: Metadata and video data in a tuple.

make_channel_request(channel_id: str) -> dict

Description: Retrieves all playlists from a specified YouTube channel. Input: Channel ID (channel_id) Output: A dictionary containing playlists' metadata.

make_playlist_request(playlist_id: str) -> tuple

Description: Gets detailed information about a playlist by its ID. Input: Playlist ID (playlist_id) Output: Tuple with playlist metadata and video data.

create_spotify_playlist(playlist_name: str, playlist_description: str, songs: list)

Description: Creates a Spotify playlist, adds songs, and organizes them. Input: Playlist Name (playlist_name), Playlist Description (playlist_description), List of songs (songs)

Playlist Manager Class

This class provides functionality for managing YouTube playlists by handling playlist records. The class also enables users to save, load, and update playlists while maintaining their structure.

Public Methods

create_multiple_new_playlist_records(channel_address, includes) -> None

This method creates and stores multiple playlist records by retrieving playlists from a given channel address. The includes parameter determines which metadata fields should be included in the records.

create_new_playlist_record(address, includes) -> None

Generates a new playlist record based on the provided playlist address. The includes parameter specifies the fields to be included in the record.

get_playlist_name(sanitized: bool = False, playlist_index: int = 0) -> str

Returns the name of a playlist. If sanitized is True, the name will be stripped of invalid file system characters. The playlist_index specifies which playlist to retrieve.

get_playlist_basic_info(playlist_index: int = 0) -> str

Provides a brief summary of the specified playlist, such as its title, description, and item count.

load_playlist_record(filepath: str) -> None

Loads a playlist record from a specified file path and integrates it into the program’s playlist management system.

compare_playlist_record_with_online(playlist_index: int = 0, by_index: bool = True, by_ids: bool = True) -> None

Compares the local playlist record with the online version. The by_index parameter checks positions, while by_ids verifies video IDs.

update_playlist_record(playlist_index: int = 0, remove_missing: bool = False, add_new: bool = True) -> None

Synchronizes the local playlist record with the corresponding online playlist. Missing items can be removed, and new items can be added based on the parameters.

save_playlist_record(filepath: str, playlist_index: int = 0, remove_from_list: bool = False, safe_to_save: bool = True) -> None

Saves the specified playlist record to a file. The remove_from_list parameter determines if the playlist is removed from the current session after saving.

save_multiple_playlist_records(filepath: str, safe_to_save: bool = True, get_unique_names: bool = True) -> None

Saves multiple playlist records to files. If get_unique_names is True, each file will have a unique name to prevent overwriting.

export_to_spotify(playlist_index: int = 0, safe_to_save: bool = True) -> int

Exports the specified playlist to Spotify. Returns the number of songs successfully added to the Spotify playlist.

reset()

Resets the state of the PlaylistManager by clearing all loaded playlists and resetting the internal state to free.

Parser Class

The PlaylistResponseParser class provides methods for parsing and transforming YouTube playlist and video metadata into structured format. It allows program to extract information from API responses.

Public Methods

parse_single_video(video_data: dict, included_params: dict) -> dict

Parses metadata for a single video from the provided video data. This includes fields like video ID, title, position, based on the included_params dictionary.

parse_response_body(items_data: dict, included_params: dict) -> list

Processes a collection of video data (contained in items_data) and returns a list of parsed videos. Each video's metadata is parsed based on the parameters specified in included_params.

parse_response_header(playlistInfo: dict, included_params: dict, included_video_params: dict) -> dict

Extracts and structures metadata from a playlist's header, such as its ID, title, description, and item count. This method also includes details about which playlist and video parameters are active, based on included_params and included_video_params.

join_header_and_body(header: dict, body: list) -> dict

Combines the parsed playlist header and body into a single dictionary. The resulting structure contains a header key for playlist metadata and a body key for the list of parsed videos.

deserialize_playlist_includes(headerInfo: dict) -> tuple

Converts the serialized included_playlist_params and included_video_params from a playlist's header back into their boolean forms. This method ensures that parameters can be used programmatically in subsequent operations.