RYM List to Spotify Playlist Importer

This project consists of two Python scripts designed to scrape public lists from RateYourMusic (RYM) and import the found music into a new, private Spotify playlist.

1. rym-to-txt.py: Scrapes a given RYM list URL, extracting albums, EPs, compilations, singles, and attempts to find linked songs (YouTube/Bandcamp) in the item descriptions. This song extraction is basic and may not always succeed without more advanced processing (like LLM analysis, which is not implemented here). It cleans the extracted data and saves it to a structured text file. It requires user interaction with a Chromium window to handle Cloudflare checks.

2. txt-to-spotify.py: Reads the text file generated by the scraper, searches Spotify for each entry, creates a private Spotify playlist, and adds the found tracks. By default, it adds the most popular track for album-like entries or the specific track if found for song entries. It features API response caching and a formatted console output.

Features

• Scrapes RateYourMusic lists, handling pagination.
• Uses nodriver (Chromium) for scraping, requiring user interaction for Cloudflare checks.
• Identifies different release types (Album, EP, Compilation, Single).
• Basic extraction of linked songs (YouTube, Bandcamp) from item descriptions.
• Generates a structured .txt file suitable for the importer script.
• Authenticates with Spotify using OAuth 2.0.
• Creates a new private Spotify playlist named after the RYM list.
• Searches Spotify for albums and songs using various strategies (exact, fuzzy matching).
• Adds tracks to the Spotify playlist (configurable number of tracks per album via command-line, default is 1).
• Implements caching for Spotify API responses (spotify_cache.db) using sqlite.
• Provides formatted, colored console output showing progress and status.

Requirements

• Python 3.13+
• uv (for running scripts/managing dependencies)
• Python packages (managed by uv run):
  • requests
  • beautifulsoup4
  • nodriver
  • spotipy
• Spotify Developer App credentials.
• A .env file in the project root for Spotify credentials.

Setup

1. Clone the repository:

   git clone <your-repository-url>
   cd <your-repository-directory>

2. Install uv: Follow instructions on the uv GitHub repository.
3. Install Dependencies: Dependencies are handled automatically by uv run based on script headers.
4. Create Spotify Developer App:
   • Go to the Spotify Developer Dashboard.
   • Create an application.
   • Note the Client ID and Client Secret.
   • Add a Redirect URI (e.g., http://127.0.0.1:8888/callback) in the app settings.
5. Create .env file: Create .env in the project root:

   SPOTIPY_CLIENT_ID='YOUR_SPOTIFY_CLIENT_ID'
   SPOTIPY_CLIENT_SECRET='YOUR_SPOTIFY_CLIENT_SECRET'
   SPOTIPY_REDIRECT_URI='YOUR_REGISTERED_REDIRECT_URI'

Usage

Step 1: Scrape the RYM List

• Run rym-to-txt.py with the RYM list URL:

  # Example:
  uv run ./rym-to-txt.py https://rateyourmusic.com/list/M4rcus/dream-folk/

• A .txt file (e.g., Dream Folk - M4rcus.txt) will be created.

Step 2: Import to Spotify

• Run txt-to-spotify.py with the path to the .txt file:

  # Example:
  uv run ./txt-to-spotify.py "Dream Folk - M4rcus.txt"

Command-line Options for txt-to-spotify.py:

• music_file: (Required, positional) Path to the input .txt file.
• --clear-cache: (Optional flag) Deletes spotify_cache.db before running.

  uv run ./txt-to-spotify.py --clear-cache "Your List Name - YourUsername.txt"

• --tracks-per-release <number>: (Optional) Number of tracks to add per album/EP/single entry. Defaults to 1.

  # Add top 3 tracks per album entry:
  uv run ./txt-to-spotify.py --tracks-per-release 3 "Your List Name - YourUsername.txt"

Configuration

• Spotify Credentials: Managed via the .env file.
• Tracks per Entry: Primarily configured using the --tracks-per-release command-line option (see Usage). The default value (if the option is not provided) is set by the DEFAULT_TRACKS_PER_RELEASE constant within the txt-to-spotify.py script.

Input File Format (.txt)

The rym-to-txt.py script generates, and txt-to-spotify.py consumes, a text file with the following line formats:

title: "List Title - Username"
url: "https://rateyourmusic.com/list/..."
# Comments or blank lines are ignored

# Album-like entries:
album: "Album Name" - "Artist Name"
ep: "EP Name" - "Artist Name"
compilation: "Compilation Name" - "Artist Name"
single: "Single Name" - "Artist Name"

# Song entries (derived from YouTube/Bandcamp links):
# Note: This extraction is basic and may require manual correction
song: "Extracted Song Title" - "Original Album/Release Title" - "Artist Name"