Introduction
Contact Information
Name: Harsh Singh Bhadauria
IRC nick: harsh-bhadauria
Email: hsb.harsh070@gmail.com
GitHub: harsh-bhadauria
LinkedIn: Harsh Singh Bhadauria | LinkedIn
About Me
I’m Harsh Singh Bhadauria, currently a sophomore at IIITDM Jabalpur, pursuing B.Tech in Computer Science and Engineering. I have a deep passion for both music and development— the ability to take an idea from your mind and bring it to life never ceases to amaze me. I work across multiple domains, from Game Development to Android, blending both design and development to create engaging experiences. I came across ListenBrainz as I was learning digital music production, and have been an avid user since.
In addition to building apps and games, I also enjoy competitive programming, tackling complex problems, and refining my problem-solving skills. I have some experience with the required tech stack and have made a few contributions to the ListenBrainz Android repository. However, I’m eager to expand my skills further, diving into new development challenges and exploring ways to enhance both functionality and user experience.
I have worked on redesigning the player UI, fixing bugs, and also helped in making figma designs for the Playlist and Listening Now screens.
My PRs: Check here
Project Overview
About ListenBrainz
ListenBrainz is an open-source project by the MetaBrainz Foundation that enables users to publicly record their music listening history. By collecting this data, ListenBrainz offers personalized recommendations, insightful statistics, and serves as a platform for users and developers to explore and analyze music listening habits. Users can integrate ListenBrainz with various music services and players, including Spotify and Rhythmbox, and import listening data from platforms like Last.fm. All collected data is openly available, supporting transparency and fostering research in music-related fields.
Problem to be Addressed
The current onboarding experience in the ListenBrainz Android app has some usability and functionality challenges that impact user engagement, retention, and overall transparency. This project aims to improve the onboarding flow by redesigning it to ensure a seamless, informative, and user-friendly experience while maintaining transparency about permissions and login requirements.
Challenges in the Existing Onboarding Flow
A smooth and intuitive onboarding process is key to user retention. If users struggle with permissions, login, or unclear flows, they are more likely to abandon the app before fully engaging with its features.
Some of the key issues with the current onboarding process include:
-
Abrupt Permission Requests: Users are prompted for critical permissions without context, which may lead to confusion or rejection. Additionally, there is no fallback mechanism to explain why the permissions are necessary when users deny them.
-
Unintended Exits: The onboarding process has loopholes that allow users to unintentionally exit before completing the necessary steps, rendering the flow ineffective.
-
Incomplete Listen Submission Setup:
-
The app does not guide users through enabling notification access, selecting apps for listen submission, or disabling background battery optimizations—key settings required for the app to function properly.
-
Users are not informed about the consequences of not enabling these services, leading to potential confusion later.
-
-
Login Flow Issues: The current login process is suddenly prompted without sufficient explanation of its benefits, potentially discouraging users from signing in.
-
Reliance on a Non-Customizable Library: The existing onboarding implementation depends on an external library, which limits customization and the ability to tailor the experience to ListenBrainz’s specific needs.
-
Lack of Update Notifications: Users are not consistently informed when a new version of the app is available on the Play Store or GitHub (for F-Droid users), leading to outdated installations.
Expected Deliverables
-
Custom Multi-Step Onboarding Flow: A redesigned, fully customizable onboarding experience built using native Android components (e.g., Jetpack Compose) that guides users through the app’s key features and settings.
-
Structured Permission Handling:
- Implementation of clear rationale dialogs and fallback mechanisms that prompt users with alternative workflows when permissions are initially rejected.
- A unified permission module that can be easily extended to include new permissions in the future.
- Integrate runtime checks for permission-dependent actions. For example, when a user attempts an action (such as playing a song) without the required permission (e.g., storage access), display a toast message stating, “Permission missing, please check Settings.”
-
Guaranteed Onboarding Completion: An onboarding flow that prevents users from unintentionally exiting before completing all critical steps, ensuring higher user retention and proper setup.
-
Enhanced Listen Submission Configuration: Dedicated screens within the onboarding flow where users can:
- Grant notification access permissions.
- Select which apps should be monitored for listen submissions.
- Disable battery optimizations for seamless background listen submission.
- Understand the rationale behind why these permissions are required and what features would not work without them.
-
Replacement of the External Library: Removal of the existing third-party onboarding library (limurse) and replacement with an extensible Jetpack Compose based implementation.
-
App Update Alert System: An integrated feature that checks for new app versions from the Play Store (or GitHub for F-Droid users) and notifies users with a one-time alert per update, ensuring they always have access to the latest features and fixes.
New Onboarding Workflow
-
Introduction: When the user first opens the app there will be a sequence of three pages that introduce ListenBrainz’s core features and benefits in an easy-to-digest narrative.
-
User-Friendly Navigation: Allow users to navigate both forwards and backwards using swipe gestures and include a prominent “Next Page” button to ensure smooth progression.
-
Consistent Branding: Use coherent visual elements (corresponding to the ListenBrainz website) to reinforce brand identity and create a memorable first impression.
Welcome Splash Screen Designs
The flow for the login screen would be as follows-
- On the first launch, the user is greeted with the welcome splash screen.
- After progressing through three introductory screens, the Login screen is displayed with two options: logging in with an existing account or creating a new account.
- When an option is selected, a webview window opens to redirect the user to the appropriate URL(
https://musicbrainz.org/register?returnto=https://listenbrainz.org/login/andhttps://listenbrainz.org/login/) - In case of errors during the process, an error view overlay appears over the webview, providing an error message along with a “Retry” button.
- Upon a successful login, the user is directed to the permission request screen.
Improvements in the existing web view
- Loading Indicator: A
CircularProgressIndicatorwill be displayed at the center while the web view loads, ensuring the user sees immediate feedback during network delays. - Error Handling: An
onReceivedErrormethod will set an error flag (hasError), triggering an overlay with an error message and a “Retry” button. This overlay will be semi-transparent to maintain context. - Retry Mechanism: Tapping “Retry” will reset the error state and reloads the URL, giving users an easy way to re-attempt the login process.
I plan to put requests for various permissions on the same screen, which will make it simpler for the user to see at a glance which permissions are required, as well as make it easier to add more permission requests in the future as and when needed.
-
Clear Permission Requests: The screen currently asks for four permissions: sending notifications (for player controls), reading notifications (to track listens), file access (to read and play music files), and disabling battery optimisation to maintain smooth performance.
-
Full Transparency and Choice: Each permission request comes with a clear rationale about why it is necessary for the app to function properly. However, users can still proceed without granting them, with a clear warning about limited functionality. This warning shall later reflect in the app’s settings as well.
-
Extensible Design: The permissions setup is designed to be extendable as new features are introduced– any additional permissions required can simply be added to the list without hassle.
The listening app selection was earlier buried within the settings which made it easy to miss. Now there will be a screen right after the notification request screen, which presents a list of listening apps installed in the user’s device, and lets them choose what apps they want to submit listens from. This helps us prevent taking listens from any apps that the user didn’t intend to send them from (like calls, audio recordings, etc). This selection can be changed later from settings as well.
Designs for 1. Sign In Screen, 2. Permission Request Screen, 3. Listening Apps Screen
(Please note that the design mockups presented here are preliminary drafts intended to convey initial concepts. I plan to discuss these drafts with mentors and engage with experienced designers to gather feedback and refine the designs.)
Permissions Implementation & State Handling
As we need our new permission system to be modular and extensible, we can implement either a permissions data class or an enum. While both approaches have their merits, the set of permissions is more or less fixed and unlikely to change, thus using an enum is a solid choice.
Also we could implement a toast saying “missing permission” whenever a user performs some action that requires a specific permission which they have denied. For example, if the user has denied storage access and tries to play a song, there should be a toast saying “permission missing, check settings”.
Handling Different Permission States
-
No-Action
- The user has not yet been prompted or has not responded to the permission request.
- Will be the default state for each permission
- Initial Request: During onboarding (or when a feature is first used), the app triggers a permission request.
-
Granted
- The user accepts the permission request.
- Proceed Normally: The app immediately enables features that depend on the granted permission.
- UI Feedback: The permission no longer shows any warnings, and no additional prompts are needed.
- State Update: The permission’s state is updated to “granted”.
-
Denied-Once
- The user denies the permission the first time.
- On Start Popup: At the next app startup, a pop-up is displayed, alerting the user that some permissions are missing and that the app might not function properly.
- User Options in Popup:
- Later: The user can choose to ignore the prompt, which leaves the permission in a “denied-once” state.
- Enable: Alternatively, the user can tap a button that takes them to a dedicated “Missing Permissions” screen.
- Do not ask again: The the state transitions to “denied-twice”
- If the user does nothing, the state remains as “denied-once” until the next opportunity to request it.
-
Denied-Twice
- The user has denied the permission for the second time, potentially selecting “Don’t ask again” (or simply denying on a second prompt).
- There will not be further explicit popups or prompts
- Visual Emphasis: In the settings screen, any permission in the “denied-once” or “denied-twice” states is highlighted so the user knows action is required.
- State will change to granted when the user decides to grant the permission.
Update Notification
A Jetpack Compose-based update notification dialog will be implemented. The following steps are involved:
- Detect the installation source (Play Store or other sources like F-Droid/GitHub).
- Check for updates and compare the latest available version with the installed version.
- Show a prompt with three options:
- Update Now – Directs users to the appropriate store for updating.
- Remind Me Later – Closes the prompt, to be shown again in future checks.
- Dismiss Permanently – Prevents future notifications until manually enabled.
This dialog will be shown once whenever the app opens unless permanently dismissed by the user.
Designs for Update Notification
App Update Implementation
Store Detection and Version Retrieval:
At launch, the app determines its installation source by checking the installer package via the PackageManager. If the app was installed from the Play Store (typically identified by "com.android.vending"), it will use Google’s in‑app update API. Otherwise, for installations such as F‑Droid, it employs a custom update mechanism. Concurrently, the app retrieves its current version using BuildConfig.VERSION_NAME to enable version comparisons.
Fetching the Latest Version:
For Play Store users, the latest version is determined using the Play Store’s update mechanisms (will require google play app update dependencies). For non-Play Store installations, the app makes a network call (using Retrofit) to GitHub’s releases API at https://github.com/metabrainz/listenbrainz-android/releases/latest to fetch update details. The JSON response provides a tag_name (e.g., “2.8.1”), which represents the latest version, along with a download URL.
Once the latest version is fetched, the app compares it with the current version. If the fetched version is newer than the current version, the app proceeds to notify the user about the available update.
Identifying Audio Apps
For identifying audio apps, I start by defining a list of permissions that are essential for an audio app. These permissions can include reading media audio, running a foreground service for media playback, Bluetooth access, etc. —this list is not comprehensive and we can change the permissions to see which combination results in the best filtering.
Next, I retrieve the list of all installed packages along with the permissions they have requested using the PackageManager. I then iterate through each package and check if it has requested every permission from my required list. If an app meets this criterion, it is identified as an audio app.
There will be a “show all apps” button which will show all the audio apps according to our old approach.
Please note that adopting this approach requires the use of the QUERY_ALL_PACKAGES permission. This permission allows the application to view the complete list of installed packages on the device, which provides a broad picture of the device’s software setup. Because of its sensitive nature, Google mandates a strict review process for any application that requests this permission. This permission cannot be requested from the user at runtime—it is granted at install time, meaning that its use must be declared upfront in the manifest.
The alternative approach would be to use an intent based approach where we look for apps that include "android.intent.category.APP_MUSIC" in their manifest–
However, some apps might not include this category despite being an audio app, so they might be missed by this approach.
Minor Changes to Settings
To align with the updated onboarding flow and update notifications, it would be a good idea to tweak the settings page a bit. We need to make sure that users have a dedicated section where dismissed update notifications and previously denied permissions are visible and can be adjusted if needed.
Project Timeline
| Period | Task(s) |
|---|---|
| Community Bonding Period (May 8 - June 1) | - Meet mentors and fellow contributors; join community discussions. - Explore ListenBrainz documentation and past project discussions. - Finalize project requirements and communication workflows. |
| Week 1-2 (June 2 - June 15) | - Finalize designs with reviews from mentors and designers. - Discuss removal of the limurse library and implement a custom Jetpack Compose solution. - Create dummy screens to test navigation and fix backstack issues. - Design the UI and animations for welcome screens using Jetpack Compose ( HorizontalPager). |
| Week 3-4 (June 16 - June 29) | - Implement the permissions enum class with detailed descriptions. - Develop UI for the permissions request screen using enum values. - Handle four basic permissions: Sending Notifications, Reading Notifications, Storage Access, and Battery Optimization. |
| Week 5-6 (June 30 - July 13) | - Develop UI for the screen where users select apps to send listens. - Replace current settings to navigate to this screen with proper user state handling. - Test all implementations on various Android versions for compatibility. - Ensure the app correctly handles denied permissions. - Fix bugs and improve UI/UX based on mentor feedback. |
| Midterm Evaluation (July 14 - July 18) | - Submit the midterm evaluation report showcasing current progress. - Address identified bugs and incorporate mentor feedback. - Refine the project roadmap based on insights and recommendations. |
| Week 7-8 (July 19 - August 1) | - Implement a redesigned login screen that aligns with the onboarding flow. - Ensure errors are handled gracefully to maintain a smooth onboarding experience. - Implement an in-app update notification with a “Check for Updates” option in settings. |
| Week 9-10 (August 2 - August 15) | - Add a “Missing Permission” dialogue in the settings and polish any inconsistencies. - Implement runtime checks for missing permissions with corresponding toasts. - Conduct comprehensive compatibility and UI testing on different devices and screen sizes. |
| Week 11 & Final Evaluation (August 16 - August 25) | - Gather feedback from mentors, designers, and the community; fix bugs/issues accordingly. - Compose a comprehensive technical report detailing all implemented features. - Streamline the codebase by removing redundant dependencies and optimizing performance. - Finalize and submit the final GSoC evaluation. - If time permits, work on extra features/enhancements. |
Post GSoC Plans
Even after GSoC concludes, I am fully committed to contributing to ListenBrainz Android on a long-term basis. A few features/enhancements I’d like to work on are:
- Music Search: Currently the app only supports searching for users. I’d like to implement a comprehensive search functionality that allows users to look up playlists, albums, releases, and artists.
- Expanding the Explore Section: I love features like “Hue Sound” and “Music Neighbourhood”. They make ListenBrainz feel so personal and special, and it would be amazing to have them available in the app as well.
- In-App Radio: The ListenBrainz app redirects users to the website when they use the Radio feature. Adding this functionality directly within the app will create a seamless experience for users who want to discover similar music.
- Improved Listen Management: Enhancing listen submission controls and enabling features like in-app deletion of listens via the ListenBrainz API.
- General UI/UX Enhancements, and many many other features.
I look forward to remaining an active contributor to ListenBrainz Android, continuously improving the app and supporting the broader open-source community. My commitment extends well beyond GSoC, ensuring that the project evolves in line with the needs of its users.
Other Information
Tell us about the computer(s) you have available for working on your SoC project!
I am currently working on my SoC project using my ASUS Vivobook S 14, an Intel EVO H-Series laptop powered by an Intel Core i5 12th Gen 12500H. This system has served me well for development and testing, providing both the portability and performance needed for my work.
When did you first start programming?
I began programming in 10th grade with Python, which laid the foundation for my subsequent learning journey. I later picked up GDScript for game development, deepened my understanding of C/C++ during college, and have since embraced Kotlin—a language I have grown to love.
What type of music do you listen to?
When it comes to music, my tastes are eclectic- I enjoy a wide range of genres, from old Bollywood tunes and Sufi music to Indie Pop. A few of my favourite MBIDs are:
- 2bba1a1d-39eb-4caf-aeac-33fa5baf4eb2
- 46fb5e69-baf2-45cd-951f-a24a77935368
- 16ef6737-c42e-4843-84b3-c49f247bdc46
What aspects of the project you’re applying for interest you the most?
I’m particularly excited by ListenBrainz’s commitment to open data and community-driven insights into music listening habits. Being a music enthusiast, I’m drawn to the idea of tracking, visualizing, and analyzing not just my personal listening patterns, but also contributing to a platform that helps users explore and understand trends in music consumption.
Have you contributed to other Open Source projects? What sorts of programming projects have you done on your own time?
This is my first venture into contributing to an open source project, and I am very excited about the opportunity. In my personal time, I have developed several Android applications for my own use, continuously exploring new libraries and technologies. Additionally, I enjoy creating games using the Godot engine, which has broadened my programming experience.
How much time do you have available, and how would you plan to use it?
I am fully available during the coding period and can commit 35–40 hours per week. Since this timeframe aligns with my semester break, I have no other commitments, allowing me to focus entirely on contributing to the project.
