song-quest

KO | EN

gitlite — search

#hacktoberfest #golang #android #deep-learning #docker #macos #nodejs #java #cli #kubernetes #vue #awesome-list #ios #openai

(★ 10)

A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.

song-quest Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🚧 Under Development

This repository is currently in active development to support **multiplatform** targets:
- Android  
- iOS  
- Web

For more details and latest progress, check out the [`multiplatform`](https://github.com/spongycode/song-quest/tree/multiplatform) branch.

<div align="center">
 <img src="assets/app_logo.jpg" width="128" height="128" style="display: block; margin: 0 auto"/>
 <h1>Song Quest 🎶</h1>
 A fully functional Android quiz game featuring audio challenges, leaderboards, and multiple categories.
</div>

## Installation

[<img src="https://github.com/user-attachments/assets/5f6c07aa-fe20-4508-90a7-79547dd241dd"
alt="Get it on Indus App Store"
height="70">](https://indusapp.store/pad93i9h)
[<img src="https://github.com/user-attachments/assets/b8d69317-bdd6-4014-96b4-6a6f6f126f4a"
alt="Get it on GitHub"
height="70">](https://github.com/spongycode/song-quest/releases/latest)

## Features 🌟
### Authentication
- Login: Users can securely log in to their accounts.
- Registration: New users can easily create accounts to start playing.
- Password Reset: Reset your password through the app, and a one-time password will be sent to your email.
### Gameplay
- Guess the Answer: Test your knowledge by guessing the correct answer listening the audio.-
- Multiple Categories: Choose from various exciting categories, each with tailored questions for an engaging gameplay experience.
- Limited Attempts: You have limited wrong attempts in each game play.
- Leaderboard: Compete with others and view the consistent leaderboard based on the highest scores.
- Game History: Track your progress by reviewing the history of games you've played.
### Profile
- Update Profile: Customize your profile details in the basic settings.

## Screenshots 📷
 
<img src="assets/mp_1.png" alt="drawing" width="600" />
<img src="assets/mp_2.png" alt="drawing" width="600" />
<img src="assets/mp_3.png" alt="drawing" width="600" />

## Video Preview 📹

[![Video Preview]()](https://github.com/spongycode/song-quest/assets/65273165/08f1f156-683c-49bd-9451-53132774e2b9)

## App Flow & Architecture 👷‍♂️
 
<img src="https://github.com/spongycode/song-quest/assets/65273165/85985538-56b2-4ad2-aab4-a613bb4bafe2" alt="drawing" width="800"/>

## Tech Stack 🛠️
- [Kotlin](https://kotlinlang.org/): Primary language for Android app development.
- [NextJS API Backend](https://nextjs.org/docs/pages/building-your-application/routing/api-routes): Utilizes NextJS for a powerful and flexible backend. See [here](https://github.com/spongycode/song-quest-backend) for implementation details.
- [Firebase](https://firebase.google.com/): Used for storing audio files, providing a scalable and reliable cloud storage solution.
- [MongoDB](https://www.mongodb.com/): Employed for a NoSQL database, handling normal query data storage efficiently.
- [Clean Architecture Pattern](https://developer.android.com/topic/architecture): Organizes code into distinct layers (UI, Domain, Data) for modularity and maintainability in Android app development.
- [MVVM](https://developer.android.com/topic/libraries/architecture/viewmodel): Architecture pattern (Model-View-ViewModel) for a structured and maintainable app design.
- [Hilt](https://developer.android.com/training/dependency-injection/hilt-android): Simplifies dependency injection in Android apps.
- [Ktor client](https://ktor.io/docs/getting-started-ktor-client.html): Facilitates asynchronous client-server communication.
- [Jetpack Compose](https://developer.android.com/jetpack/compose): Declarative UI toolkit for native Android apps.
- [Compose Navigation](https://developer.android.com/jetpack/compose/navigation): Navigation component for Jetpack Compose.
- [Material 3](https://m3.material.io/): Latest Material Design system for unified app aesthetics.
- [Datastore](https://developer.android.com/topic/libraries/architecture/datastore): Modern local data storage solution.

## Backend details

### Routes `api/mobile`
- `/gameplay`
 - `/create`: Create a new game.
 - `/question`: Upload new questions and fetch questions category-wise.
 - `/check`: Check the correct answer for the question.
 - `/highscore`: Fetch the leaderboard category-wise.
 - `/history`: Fetch the user's game history.
 - `/save`: Save the game.
- `/users`
 - `/register`: Register new users.
 - `/login`: Login users.
 - `/profile`: Get and update profile details.
 - `/resetPassword`: Reset password and send OTP via email.

### Data Models

- Game Model

```json
{
 "game": {
 "player": "String (required)",
 "score": "Number (default: 0.0)",
 "accurate": "Number (default: 0)",
 "questionsId": "Array of ObjectId (ref: 'Question')",
 "category": "String (required)",
 "isGameSaved": "Boolean (default: false)",
 "createdAt": "Date (default: Current timestamp)",
 "expireAt": "Date (default: Current timestamp)"
 }
}
```
**Note:** This project utilizes a [TTL (Time-to-Live) index](https://www.mongodb.com/docs/manual/core/index-ttl/) to automatically delete unsaved games after `300 seconds`. The index is based on the `expireAt` field and is configured to delete games where `isGameSaved` is false. This ensures efficient cleanup of temporary data.
- Question Model

```json
{
 "question": {
 "title": "String (required)",
 "songUrl": "String",
 "options": [
 {
 "optionid": "Number (required)",
 "value": "String (required)"
 }
 ],
 "correctOptionId": "Number (required)",
 "category": "String (required)",
 "totalAttempts": "Number (default: 0)",
 "difficulty": "Number (default: 0.5)",
 "altText": "String (default: '')",
 "createdAt": "Date (default: Current timestamp)"
 }
}
```
- User Model
```json
{
 "user": {
 "username": "String (required, unique, trim)",
 "email": "String (required, unique, trim)",
 "imageUrl": "String",
 "password": "String (required, 'Password is required')",
 "gamesPlayed": "Number (default: 0)",
 "forgotPasswordToken": "String",
 "forgotPasswordTokenExpiry": "Date",
 "refreshToken": "String",
 "createdAt": "Date (default: Current timestamp)"
 }
}
```

### Scoring
The score for each question is determined using the formula below.

```math
score = max(0, -0.00057 \times timeTaken^3 + 0.037 \times timeTaken^2 - 0.96 \times timeTaken + 10)
```

## Getting Started 🚀
To begin using Song Quest, clone the repository and open the project in Android Studio. Clone the backend server from [here](https://github.com/spongycode/song-quest-backend) and fill up the required environment variables mentioned in the `sample.env` file to set up your own server.

## Contributing 🤝
Feel free to contribute to this project by submitting issues, pull requests, or providing valuable feedback. Your contributions are always welcome! 🙌

## License 📄
Song Quest is released under the [MIT License](https://opensource.org/licenses/MIT). Feel free to modify or add to this list based on the specific features of your app.

## Happy coding! 🎉👩‍💻👨‍💻

song-quest

song-quest Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

song-quest

song-quest Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README