Song Library API

A FastAPI-based REST API for managing songs and their lyrics with automatic enrichment from external music APIs.

Features

• CRUD Operations: Create, read, update, and delete songs
• Search Functionality: Search songs by title, artist, release date range, external link, or lyrics keywords
• Automatic Enrichment: Automatically fetch release dates and lyrics from external APIs (Genius)
• Verse-by-Verse Access: Page through lyrics instead of loading all at once
• Flexible Architecture: Easy to switch between different music API providers

Installation

1. Clone the repository and activate virtual environment

2. Install dependencies

pip install -r requirements.txt

3. Set up environment variables:

Getting a Genius API Token

Go to https://genius.com/api-clients Click "Generate Access Token" Copy the token and add it to your .env file

Create .env and add your Genius API token

DATABASE_URL=sqlite:///./song_library.db
MUSIC_API_TOKEN=your_genius_api_token_here
MUSIC_API_BASE_URL=https://api.genius.com

Configuration

The API is configured through environment variables:

• DATABASE_URL: SQLite database URL (default: sqlite:///./song_library.db)
• MUSIC_API_TOKEN: Genius API access token (optional)
• MUSIC_API_BASE_URL: Base URL for the music API (default: https://api.genius.com)

4. Run the application:

uvicorn app.main:app --reload

API Documentation

Once running, visit:

• Interactive API docs: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc

API Endpoints

Songs

• POST /songs/ - Create a new song (auto-enriched)
• GET /songs/ - List all songs
• GET /songs/{song_id} - Get a specific song
• PUT /songs/{song_id} - Update a song
• DELETE /songs/{song_id} - Delete a song
• GET /songs/search - Search songs with filters
• GET /songs/{song_id}/verses - Get paginated verses
• POST /songs/{song_id}/enrich - Manually trigger enrichment
• POST /songs/{song_id}/verses - Manually add verses

Search Parameters

• title: Search by song title (partial match)
• artist: Search by artist name (partial match)
• release_date_from: Filter by minimum release date
• release_date_to: Filter by maximum release date
• external_link: Search by external link
• lyrics_keyword: Search for keywords in lyrics

Database Schema

Songs Table

• id: Primary key
• title: Song title
• artist: Artist name
• release_date: Release date (nullable)
• external_link: Link to external source (nullable)
• created_at: Creation timestamp
• updated_at: Update timestamp

Verses Table

• id: Primary key
• song_id: Foreign key to songs
• verse_number: Order of verse
• content: Verse text
• verse_type: Type (verse, chorus, bridge, etc.)

Working Without Genius API

The API works without a Genius token, but without automatic enrichment:

1. Create songs - Will create basic entries without release date or lyrics
2. Manually add data:
   • Use PUT /songs/{id} to add release date and external link
   • Use POST /songs/{id}/verses to add lyrics manually
3. All search and pagination features still work

Architecture

The project follows a clean architecture pattern:

• Routers: Handle HTTP requests and responses
• CRUD: Database operations
• Services: External API integration and web scraping
• Models: SQLAlchemy ORM models
• Schemas: Pydantic models for validation
• Database: Database connection and session management

No Lyrics Scraped

• Some songs may not have lyrics on Genius
• The scraper may need adjustments for certain page formats
• Check console logs for scraping errors