Update README.md to reflect project renaming and enhance documentation; add multi-service music integration details and installation instructions; improve feature descriptions and security considerations.

2025-05-13 21:56:58 +02:00
parent 9d3065beab
commit d2772b88fe
5 changed files with 353 additions and 79 deletions
@@ -1,21 +1,49 @@
-# MusicRound
+# Quizzical Beats

-**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.
+<p align="center">
+  <img src="docs/static/img/logo.png" alt="Quizzical Beats Logo" width="350">
+</p>
+
+<p align="center">
+  <a href="https://quizzicalbeats.readthedocs.io/"><strong>📚 Documentation</strong></a> •
+  <a href="#features">Features</a> •
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#deployment">Deployment</a> •
+  <a href="#license">License</a>
+</p>
+
+**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

- **Spotify Integration**: Import songs and playlists directly from Spotify using their API.
+- **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 songs.
+  - Randomly generated rounds.
  - Based on least-used genres or decades.
+  - Tag-based rounds for custom categorization.
  - 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.
+
+- **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.

 ---

@@ -23,22 +51,50 @@

 ### Prerequisites

- **Python**: Version 3.6 or higher.
+- **Python**: Version 3.9 or higher.
 - **Spotify Developer Account**: [Create a Spotify Developer App](https://developer.spotify.com/dashboard/applications) to retrieve your client ID and secret.
 - **Last.fm API Key**: Sign up at [Last.fm](https://www.last.fm/api) to obtain an API key.
+- **Dropbox Developer Account** (optional): [Create a Dropbox App](https://www.dropbox.com/developers/apps) for export functionality.
+- **Deezer Developer Account** (optional): [Create a Deezer App](https://developers.deezer.com/myapps) for additional music sources.

 ### Installation

+#### Docker Installation (Recommended)
+
 1. Clone the repository:
   ```bash
-   git clone https://github.com/christianlouis/musicround.git
-   cd musicround
+   git clone https://github.com/christianlouis/QuizzicalBeats.git
+   cd QuizzicalBeats
+   ```
+
+2. Configure environment variables in a `.env` file (copy from `.env.example`):
+   ```env
+   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:
+   ```bash
+   docker-compose up -d
+   ```
+
+4. Access the application at `http://localhost:5000`.
+
+#### Manual Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/christianlouis/QuizzicalBeats.git
+   cd QuizzicalBeats
   ```

 2. Create a virtual environment:
   ```bash
-   python3 -m venv venv
-   source venv/bin/activate
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

 3. Install dependencies:
@@ -46,79 +102,62 @@
   pip install -r requirements.txt
   ```

-4. Set up environment variables in a `.env` file:
-   ```env
-   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
-   ```
+4. Set up environment variables in a `.env` file (copy from `.env.example`).

-5. Initialize the SQLite database:
+5. Initialize the database:
   ```bash
-   python
-   >>> from app import db
-   >>> db.create_all()
-   >>> exit()
+   python run_migration.py
   ```

 6. Start the application:
   ```bash
-   python app.py
+   python run.py
   ```

-7. Open your browser and navigate to `http://localhost:5000`.
+7. Access the application at `http://localhost:5000`.

 ---

-## APIs Used
+## Deployment

- **Spotify API**:
-  - Used to import songs, playlists, and retrieve song metadata.
-  - [API Documentation](https://developer.spotify.com/documentation/web-api/)
+For production deployment, we recommend using Docker with proper security configurations. See our [Installation Guide](https://quizzicalbeats.readthedocs.io/admin-guide/installation.html) in the documentation for detailed deployment instructions.

- **Last.fm API**:
-  - Enriches tracks with genre information.
-  - [API Documentation](https://www.last.fm/api)
+### Security Considerations

-### 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`.
+- Always use HTTPS in production
+- Set up proper authentication methods
+- Use strong, unique secrets and passwords
+- Configure backups regularly

 ---

-## Changelog
+## Documentation

-### 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.
+Comprehensive documentation is available at [quizzicalbeats.readthedocs.io](https://quizzicalbeats.readthedocs.io/), including:
+
+- [User Guide](https://quizzicalbeats.readthedocs.io/user-guide/getting-started.html)
+- [Admin Guide](https://quizzicalbeats.readthedocs.io/admin-guide/installation.html)
+- [Developer Guide](https://quizzicalbeats.readthedocs.io/developer-guide/architecture.html)
+- [API Reference](https://quizzicalbeats.readthedocs.io/developer-guide/api-reference.html)
+- [FAQ](https://quizzicalbeats.readthedocs.io/faq.html)

 ---

 ## Project Structure

+The project follows a modular Flask application 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
+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
 ```

 ---
@@ -131,22 +170,7 @@ This project is licensed under the **MIT License**. See `LICENSE` for details.

 ## Contributing

-We welcome contributions! To contribute:
-
-1. Fork the repository.
-2. Create a feature branch:
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-3. Commit your changes:
-   ```bash
-   git commit -m "Add your feature description"
-   ```
-4. Push the branch:
-   ```bash
-   git push origin feature/your-feature-name
-   ```
-5. Open a pull request.
+We welcome contributions! Please see our [Contributing Guide](https://quizzicalbeats.readthedocs.io/developer-guide/contributing.html) for details on how to get started.

 ---

@@ -155,3 +179,9 @@ We welcome contributions! To contribute:
 - **Developer**: Christian Krakau-Louis
 - **Email**: [christian@kaufdeinquiz.com](mailto:christian@kaufdeinquiz.com)
 - **GitHub**: [christianlouis](https://github.com/christianlouis)
+
+---
+
+<p align="center">
+  <em>Where trivia meets the rhythm.</em>
+</p>