gitea-admin/gh-christianlouis-quizzicalbeats
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive documentation for Quizzical Beats

Browse Source 
- Created a detailed database schema document outlining tables, relationships, and key fields.
- Added OAuth integration documentation covering Spotify and Dropbox authentication processes.
- Introduced a FAQ section addressing common user inquiries about the application.
- Developed a user-friendly index page for easy navigation of the documentation.
- Specified documentation dependencies in requirements.txt for building the documentation site.
- Expanded user guide with sections on account management, creating rounds, exporting rounds, getting started, importing songs, and user interface navigation.
- Updated mkdocs.yml for improved site structure and navigation.
This commit is contained in:
Christian Krakau-Louis
2025-05-13 11:25:20 +02:00
parent 4646c80a15
commit 204941a1dc
23 changed files with 3558 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-guide/account-management.md
+111
View File
@@ -0,0 +1,111 @@
# Account Management
This guide explains how to manage your Quizzical Beats account, including profile settings, integrations, and authentication options.
## Profile Settings
Manage your personal information and preferences:
1. Click your username in the top-right corner
2. Select "Profile" from the dropdown menu
3. Here you can:
- Update your username
- Change your email address
- Edit your first and last name
- Modify your password
- Update your Dropbox export path
## Authentication Methods
Quizzical Beats supports multiple authentication methods:
### Local Username/Password
1. Go to Profile > Change Password
2. You can:
- Update your current password
- View your last login time
### OAuth Providers
Connect and use third-party authentication:
1. Navigate to your Profile page
2. Here you can connect/disconnect:
- Spotify account
- Google account (if enabled by your administrator)
- Dropbox account (for file exports)
- Authentik (if enabled by your administrator)
## Email-Based Account Identification
Quizzical Beats uses your email address as the primary identifier for your account, which provides several benefits:
### Single Account Across Login Methods
- If you login with username/password and later use Google or Authentik with the same email address, **you'll be automatically logged into the same account**
- There's no need to manually link accounts - the system recognizes you based on your email
- Your profile data, saved rounds, and settings remain consistent regardless of how you login
For example:
1. You register with username "musicfan" and email "you@example.com"
2. Later, you click "Sign in with Google" using the same email "you@example.com"
3. The system will recognize and log you into your existing "musicfan" account
4. All your data, settings, and history will be preserved
### Switching Between Login Methods
You can freely alternate between:
- Username/password login
- Google authentication (if enabled)
- Authentik authentication (if enabled)
As long as all methods use the same email address, you'll always access the same account.
### Benefits
- **Simplified Experience**: No need to remember which login method you used previously
- **Data Consistency**: Your preferences and data remain unified across login methods
- **Flexible Authentication**: Choose the most convenient login method for your current situation
## Managing OAuth Connections
For each connected service:
1. View connection status and details
2. Disconnect services when needed
3. Re-authorize when tokens expire
4. See token expiration information
## Custom Audio Files
Upload and manage your custom audio files:
1. Navigate to Profile > Audio Settings
2. Here you can:
- Upload custom intro music
- Upload custom outro music
- Upload custom replay sound
- Generate audio using text-to-speech
## Account Security
Keep your account secure:
1. Use a strong, unique password
2. Log out from shared computers
3. Check your last login time
4. Review connected applications regularly
## Troubleshooting
**Can't Log In**:
1. Try the "Forgot Password" option
2. Check that you're using the correct OAuth provider
3. Clear browser cookies and cache
4. Contact your administrator if problems persist
**OAuth Connection Issues**:
1. Disconnect and reconnect the service
2. Ensure you're granting all required permissions
3. Check that your third-party account is active and in good standing
docs/user-guide/creating-rounds.md
+75
View File
@@ -0,0 +1,75 @@
# Creating Rounds
This guide explains how to create, configure, and manage music quiz rounds in Quizzical Beats.
## Understanding Round Types
Quizzical Beats offers several types of quiz rounds:
- **Random Selection**: Creates a diverse round with randomly selected songs
- **By Decade**: Songs from a specific decade that has been used the least in your quizzes
- **By Genre**: Songs from a specific genre that has been used the least in your quizzes
- **By Tag**: Songs that share a specific tag from your collection
## Creating a Basic Round
To create a new quiz round:
1. From the Dashboard or Rounds page, click "Create New Round" or "Build Round"
2. Enter an optional name for your round
3. Select the round type by choosing one of the available cards:
- Random Selection
- By Decade
- By Genre
- By Tag (select a specific tag from the dropdown)
4. Click the corresponding "Generate" button for your chosen round type
5. Review the generated round with its selected songs
6. Optionally modify the round name
7. Click "Save This Quiz" to save your round
## Reviewing Generated Rounds
When a round is generated, you'll see:
1. A preview of all songs in the round
2. Information about each song (title, artist, year, genre)
3. Audio previews you can play to check each song
4. Options to save the round or generate a different one
## Managing Saved Rounds
After saving a round, you can manage it from the round detail page:
1. Edit the round name by clicking the edit icon next to the title
2. Add or remove songs
3. Reorder songs by dragging and dropping them
4. Save your changes using the "Save Changes" button
## Song Management
To modify the songs in your round:
1. On the round detail page, you can:
- Remove songs by clicking the trash icon
- Add new songs by clicking the "Add Song" button
- Search for specific songs in the song library
- Reorder songs using drag and drop
2. After making changes, click "Save Changes" to update the round
## Export Options
Create different formats of your round:
1. **Generate MP3**: Creates an audio file with all songs, intro/outro, and announcements
2. **Generate PDF**: Creates a printable document with the round information
3. **Export to Dropbox**: Saves your round files to your connected Dropbox account
4. **Send Email**: Sends the round details via email
## Deleting Rounds
To delete a round:
1. Navigate to the round detail page
2. Click the "Delete Quiz" button
3. Confirm deletion in the confirmation dialog
4. The round and its associated files will be permanently removed
docs/user-guide/exporting-rounds.md
+72
View File
@@ -0,0 +1,72 @@
# Exporting Rounds
This guide explains the available methods for exporting your music quiz rounds from Quizzical Beats.
## Available Export Options
Quizzical Beats currently supports the following export options:
- **PDF**: Round document with questions, answers, and song information
- **MP3**: Audio file with all songs concatenated for playback during your quiz
- **JSON**: Metadata about the round and songs (exported automatically with Dropbox exports)
## Local Export
To export a round to your local device:
1. Navigate to the Rounds page
2. Select the round you want to view
3. Click the "Download MP3" or "Download PDF" button to save the respective file
## Dropbox Export
Quizzical Beats integrates with Dropbox to easily store your rounds in the cloud:
### Connecting to Dropbox
1. Go to your Profile page
2. Find the "Connected Services" section
3. Click "Connect Dropbox"
4. Follow the authorization prompts from Dropbox
5. Once connected, your Dropbox status will show as "Connected"
### Setting Your Dropbox Export Path
1. Go to your Profile page > Edit Profile
2. Find the "Dropbox Export Path" field
3. Enter your preferred folder path or use the default "/QuizzicalBeats"
4. If your account is connected, you can click "Browse" to select a folder
5. Save your changes
### Exporting Rounds to Dropbox
1. Navigate to the Rounds page
2. Select the round you want to export
3. Click "Export to Dropbox" button in the export options section
4. In the export modal, choose whether to include MP3 files
5. Click "Export Round" to send the files to your configured Dropbox folder
The system will create a folder structure in your Dropbox with the following format:
```
/[Your Export Path]/Round_[ID]_[Round Name]/
├── round_[ID].mp3 (if MP3 option was selected)
├── round_[ID].pdf
└── Metadata/
└── round_[ID]_metadata.json
```
After the export completes successfully, you will see shared links to access each exported file directly.
## Troubleshooting Exports
### Failed Dropbox Export
1. Check your Dropbox connection status in your Profile
2. If your token has expired, reconnect your Dropbox account
3. If the export fails because MP3 generation is required, click the provided link to generate the MP3 first
4. Verify you have sufficient Dropbox storage space
5. Check for any error messages displayed during the export process
### MP3 Export Issues
1. Ensure all songs in the round have valid preview URLs
2. Try regenerating the round MP3 by clicking the "Generate MP3" button on the round page
3. If some songs lack preview URLs, you may need to edit those songs to add valid URLs
docs/user-guide/getting-started.md
+62
View File
@@ -0,0 +1,62 @@
# Getting Started with Quizzical Beats
Welcome to Quizzical Beats, your ultimate music quiz round generator! This guide will help you get started with the application and create your first music quiz round.
## Creating Your Account
1. Navigate to the Quizzical Beats login page
2. Click on "Register" to create a new account
3. You can register using:
- Email and password
- Google account
- Spotify account
- Authentik (if enabled by your administrator)
## Setting Up Spotify Integration
To access Spotify's vast music library:
1. Go to your account settings
2. Click on "Connect to Spotify"
3. Follow the authorization prompts
4. Once connected, you'll be able to import songs and playlists directly from Spotify
## Understanding Music Metadata
Quizzical Beats uses multiple music services to provide rich metadata for your songs:
1. **Spotify**: Provides song previews, album artwork, release dates, and audio features
2. **Deezer**: Alternative source for song previews and metadata
3. **Last.fm**: Enhances songs with genre information and music tags
4. **ISRC Matching**: When available, uses standardized recording codes to match songs across services
This multi-source approach ensures your music library has comprehensive information for creating diverse quiz rounds based on genres, decades, and other musical characteristics.
## First-Time Setup
After registering and logging in:
1. Visit your profile settings to customize your experience
2. Upload custom intro/outro/replay sounds if desired
3. Configure your email preferences for notifications
## Creating Your First Round
Once you're set up, you can create your first quiz round:
1. Click on "Create New Round" from the dashboard
2. Choose a round type (random, by genre, by decade, etc.)
3. Set the number of songs/questions
4. Click "Generate Round"
## Exporting Your Round
After creating a round, you can export it in various formats:
1. PDF document with questions and answers
2. MP3 files for playback
3. Directly to Dropbox (if connected)
## Next Steps
Now that you've created your first round, explore the [User Interface](user-interface.md) guide to learn about all the features available in Quizzical Beats.
docs/user-guide/importing-songs.md
+89
View File
@@ -0,0 +1,89 @@
# Importing Songs
This guide explains the various methods for importing songs into Quizzical Beats to build your music quiz library.
## Music Service Integrations
Quizzical Beats supports importing songs from popular streaming services:
### Spotify Integration
#### Connecting Your Spotify Account
1. For full functionality, you'll need to connect your Spotify account
2. Login to Quizzical Beats and authorize the Spotify connection
3. Once connected, you can access and import songs from Spotify
#### Importing from Spotify
There are several ways to import songs from Spotify:
1. **Import Official Playlists**:
- Navigate to Import > Official Playlists
- Browse playlists from official Spotify accounts
- Filter by keywords if needed
- Click "Import" on the playlist you want to add
2. **Import Your Playlists**:
- Navigate to Import > From Playlist
- Enter a Spotify playlist URL or ID
- Click "Import Playlist"
- The songs will be added to your library
3. **Import Individual Albums or Tracks**:
- Navigate to Import > Album or Import > Song
- Enter the Spotify URL or ID of the album/track
- Click "Import" to add the songs to your library
### Deezer Integration
Quizzical Beats also supports importing songs from Deezer:
1. **Import Deezer Playlists**:
- Navigate to Import > From Playlist
- Select "Deezer" as the platform
- Enter a Deezer playlist URL or ID
- Click "Import Playlist"
2. **Import Deezer Albums or Tracks**:
- Navigate to Import > From Deezer
- Choose to import an album or track
- Enter the Deezer URL or ID
- Click "Import" to add to your library
## Creating Rounds from Imported Songs
You can create rounds directly from imported playlists:
1. Navigate to Import > From Playlist
2. Enter the playlist URL and select the platform (Spotify or Deezer)
3. Optionally provide a name for your round
4. Click "Import Playlist"
5. Review the generated round
6. Click "Save This Quiz" to create the round
## Viewing Imported Songs
After importing songs:
1. Go to the Songs page to see your newly imported music
2. The songs will be displayed with available metadata including:
- Title and artist
- Album and year
- Genre (when available)
- Preview URLs
## Troubleshooting Import Issues
**Missing Audio Previews**: Some tracks may not have preview URLs available. In this case:
- Try importing from a different source (Spotify vs. Deezer)
- Look for an alternative version of the song
- Some songs may not have preview URLs available from any source
**Duplicate Songs**: The system will automatically detect duplicates based on:
- Spotify/Deezer IDs
- ISRC codes when available
**Limited Imports**: For performance reasons, when creating rounds from playlists:
- Only a limited number of songs (typically 8-10) will be included in a round
- All songs are saved to your library for future use
docs/user-guide/user-interface.md
+64
View File
@@ -0,0 +1,64 @@
# User Interface Guide
This guide provides an overview of the Quizzical Beats user interface to help you navigate the application efficiently.
## Dashboard
The dashboard is your main hub in Quizzical Beats, providing quick access to:
- **Recent Rounds**: Your most recently created quiz rounds
- **Quick Actions**: Buttons for common tasks (Create New Round, Import Songs)
- **System Status**: Information about your Spotify connection, Dropbox status, etc.
## Main Navigation
The main navigation menu is located at the top of the screen and includes:
- **Dashboard**: Return to the main dashboard
- **Rounds**: View and manage all your quiz rounds
- **Songs**: Browse and manage your song library
- **Import**: Access options for importing songs from Spotify and other sources
- **Export**: Options for exporting your quiz rounds
- **Profile**: Access your user profile and settings
## Rounds Page
The Rounds page displays all your created quiz rounds with:
- **Search & Filter**: Find rounds by name, date, or type
- **Round Cards**: Preview of each round with options to edit, play, or export
## Song Library
The Song Library provides a comprehensive view of all songs in your database:
- **Search**: Find songs by title, artist, album, or year
- **Filter Panel**: Filter songs by genre, decade, tags, and more
- **Preview**: Play song snippets directly in the browser
## Round Creator
When creating or editing a round:
- **Round Properties**: Set name and round criteria
- **Song Selection**: Add songs manually or use the auto-generator
- **Arrangement**: Reorder songs in your round
- **Preview**: Test your round with the built-in player
## Settings Area
The account settings area allows you to:
- **Profile**: Update your user information
- **Password**: Change your password
- **OAuth Connections**: Manage connections to Spotify, Dropbox, and other services
- **Audio Settings**: Configure custom intro, outro, and replay sounds
## Admin Settings
For administrators, additional settings include:
- **System Settings**: Configure global application settings
- **User Management**: Manage user accounts
- **System Health**: Monitor application status
- **Backup & Restore**: Manage database backups