MusicRound is a Flask-based web application for building engaging music rounds for pub quizzes. Leveraging the Spotify API, it allows you to generate rounds based on the least-used genres, decades, or completely random criteria, making your quizzes dynamic and entertaining.

Features

Spotify Integration: Import songs and playlists directly from Spotify using their API.
Dynamic Round Creation:
- Randomly generated songs.
- Based on least-used genres or decades.
- Unique and diverse song selections.
Preview and Export:
- Include Spotify preview links in rounds.
- Export rounds as printable PDFs and playable MP3s.
Last.fm Integration: Automatically enrich tracks with genre metadata.
Email Delivery: Email generated quiz rounds to the designated recipient.

Getting Started

Prerequisites

Python: Version 3.6 or higher.
Spotify Developer Account: Create a Spotify Developer App to retrieve your client ID and secret.
Last.fm API Key: Sign up at Last.fm to obtain an API key.

Installation

Clone the repository:

git clone https://github.com/christianlouis/musicround.git
cd musicround

Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

Set up environment variables in a .env file:

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:5000/callback
LASTFM_API_KEY=your_lastfm_api_key

Initialize the SQLite database:

python
>>> from app import db
>>> db.create_all()
>>> exit()

Start the application:
```
python app.py
```
Open your browser and navigate to http://localhost:5000.

APIs Used

Spotify API:
- Used to import songs, playlists, and retrieve song metadata.
- API Documentation
Last.fm API:
- Enriches tracks with genre information.
- API Documentation

Provided APIs

MusicRound also provides APIs to fetch data from the application. For example:

GET /rounds: Fetch all rounds created.
POST /rounds: Create a new round using specified criteria.
GET /songs: Retrieve all songs in the database.

For detailed API usage, refer to the in-app documentation or inspect the routes in app.py.

Changelog

Version 1.0

Initial release.
Features:
- Spotify and Last.fm integration.
- Random, genre-based, and decade-based round generation.
- PDF and MP3 export functionality.
- Email delivery of rounds.

Project Structure

musicround/
├── app.py               # Main application logic
├── config.py            # Configuration settings
├── templates/           # HTML templates for rendering views
├── static/              # Static files (CSS, JS)
├── requirements.txt     # Python dependencies
├── instance/            # SQLite database folder
├── mp3/                 # Audio files for MP3 generation
├── pdf_reports/         # Generated PDF reports
├── README.md            # Project documentation
└── rounds/              # MP3 cache for quiz rounds

License

This project is licensed under the MIT License. See LICENSE for details.

Contributing

We welcome contributions! To contribute:

Fork the repository.

Create a feature branch:

git checkout -b feature/your-feature-name

Commit your changes:

git commit -m "Add your feature description"

Push the branch:

git push origin feature/your-feature-name

Open a pull request.

Contact

Developer: Christian Krakau-Louis
Email: christian@kaufdeinquiz.com
GitHub: christianlouis