Quizzical Beats

📚 Documentation • Features • Getting Started • Deployment • License

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

---

Features

• Multi-Service Music Integration:

  • Spotify Integration: Import songs and playlists directly from Spotify using their API.
  • Deezer Integration: Alternative source for songs and playlists.
  • Last.fm Integration: Automatically enrich tracks with genre metadata.

• Dynamic Round Creation:

  • Randomly generated rounds.
  • Based on least-used genres or decades.
  • Tag-based rounds for custom categorization.
  • Unique and diverse song selections.

• Powerful Export Options:

  • Export rounds as printable PDFs with questions and answers.
  • Create playable MP3s with song snippets.
  • Generate ZIP packages with all round contents.
  • Dropbox Integration for cloud storage of rounds.

• User Management:

  • Multiple authentication methods (local, Spotify, Google, Authentik).
  • User-specific settings and preferences.
  • Role-based access control.

• System Administration:

  • Comprehensive backup and restore functionality.
  • System health monitoring dashboard.
  • User and content management tools.

---

Getting Started

Prerequisites

• Python: Version 3.9 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.
• Dropbox Developer Account (optional): Create a Dropbox App for export functionality.
• Deezer Developer Account (optional): Create a Deezer App for additional music sources.

Installation

Docker Installation (Recommended)

1. Clone the repository:

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

2. Configure environment variables in a .env file (copy from .env.example):

   SPOTIFY_CLIENT_ID=your_spotify_client_id
   SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
   SPOTIFY_REDIRECT_URI=http://localhost:5000/auth/spotify/callback
   LASTFM_API_KEY=your_lastfm_api_key
   # Add other configuration options as needed
   

3. Start the Docker containers:

   docker-compose up -d
   

4. Access the application at http://localhost:5000.

Manual Installation

1. Clone the repository:

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

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables in a .env file (copy from .env.example).

5. Initialize the database:

   python run_migration.py
   

6. Start the application:

   python run.py
   

7. Access the application at http://localhost:5000.

---

Deployment

For production deployment, we recommend using Docker with proper security configurations. See our Installation Guide in the documentation for detailed deployment instructions.

Security Considerations

• Always use HTTPS in production
• Set up proper authentication methods
• Use strong, unique secrets and passwords
• Configure backups regularly

---

Documentation

Comprehensive documentation is available at quizzicalbeats.readthedocs.io, including:

• User Guide
• Admin Guide
• Developer Guide
• API Reference
• FAQ

Additional Documentation

• SECURITY.md - Security policy, best practices, and vulnerability reporting
• ROADMAP.md - Project roadmap, milestones, and future plans
• AGENTS.md - Guidelines for AI coding agents and developers
• CONTRIBUTING.md - Contribution guidelines
• TODO.md - Detailed task list and completed milestones

---

Project Structure

The project follows a modular Flask application structure:

musicround/              # Main application package
├── __init__.py          # Application factory
├── config.py            # Configuration management
├── models.py            # Database models
├── version.py           # Version information
├── helpers/             # Utility modules
├── mp3/                 # Audio file storage
├── routes/              # Route blueprints
├── static/              # Static assets
└── templates/           # HTML templates

---

License

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

---

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.

---

Contact

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

---

Where trivia meets the rhythm.