[GSOC 2026] Showcase MusicBrainz events in ListenBrainz

MetaBrainz GSoC applications
, , ,
1

Contact Information

Name: Haris
Email: shj076tk@gmail.com
Matrix Handle: harizz076
LinkedIn: https://www.linkedin.com/in/shaikh-haris-jamal-a25684286
Mentor: @mr_monkey and @anshgoyal31
Timezone: Indian Standard Time (GMT +5:30)
Languages: English, Hindi, Punjabi

Introduction

Hi, I am Haris, a third year ECE dual degree student at IIIT-H. I am an undergrad researcher at the Music Cognition Group at the Cognitive Science Lab in my college. I did some basic web dev in 8th and 9th grade and started coding properly once I joined my college. I learnt basic programming along with DSA in C and C++ and I am also comfortable in Python. Through navigating courses and hackathons in my college, I have experience with HTML, CSS, React and Kotlin. I have a passion for working in teams and managing people and I am known to be fully committed to each and everything I take up. I have been recently working on a project (that hopefully develops into a publication) and I plan to integrate the scrobbling feature from ListenBrainz into it (effectively introducing more people to ListenBrainz :))

Signal-based Yield for Responses to Audio (SYRA): A mobile application made in Kotlin that synchronises streaming behaviour, experience sampling prompts, and wearable sensor data in real time. SYRA allows us to examine how specific patterns of music use correspond to physiological states and subjective experience across days and weeks.

Why Me?

I believe this org is the best fit for me as I love listening to music and my research is on music (particularly on how music is used for emotional regulation). I have never felt like I belong more to an org than I did when I joined the MetaBrainz community. I am highly committed to everything I believe in and this motivates me to work for long hours and pay attention to detail. Everything I have taken up in my college, I have done an extraordinary job at. I love the community and I wholeheartedly believe in MetaBrainz’ end goal (World domination >:). I love interacting with new people joining the community as well as the older members. The community has always been very understanding and supportive of me as well as other newly joined contributors. This has helped me open a few PRs (listed below) and the detailed feedback helped me learn throughout the process.

  1. LB-1878: Standardize recording_msid in JSONL listen export
  2. LB-1884: Implement Navidrome ‘Starred’ tracks import
  3. LB-1973: Fix the scroll-bar on “Fresh releases” page

Working on LB-1973 has also given me a good understanding of the Fresh Releases page, which is great because the Events page is going to reuse a lot of it. My contributions are not limited to code either. I love contributing to the community in every way I can, whether it is updating the wiki, opening tickets, or just yapping on the matrix channel.

Proposed Project

MusicBrainz contains structured information about musical events such as concerts, festivals, competitions, and other performances that audiences can attend. These events are stored as first-class entities in the MusicBrainz database and are linked to artists, venues, and other related metadata.

The goal of this project is to integrate this event data into ListenBrainz so that users can discover upcoming events related to the artists they listen to. Currently, ListenBrainz focuses on listening history and recommendations, but it does not surface real-world music events connected to the artists in a user’s listening profile.

This project will introduce a system that fetches event data from MusicBrainz, stores a cached representation inside the ListenBrainz database, and surfaces relevant events across the application.

Schema Changes

To support event discovery, artist-following, and event notifications, several new tables will be introduced in the ListenBrainz database. These tables allow the system to cache MusicBrainz event data, track which artists a user follows, and generate timeline events for users when relevant concerts or festivals are detected. Indexes are also added on frequently queried columns for optimization.

The below diagram illustrates the proposed schema changes:

657x500
657x5001146×872 82.2 KB

  1. The mapping.mb_event_metadata_cache table is added to cache event metadata from MusicBrainz for fast access.

    CREATE TABLE mapping.mb_event_metadata_cache (
    dirty        BOOLEAN DEFAULT FALSE,
    last_updated TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    event_mbid   UUID NOT NULL PRIMARY KEY,
    data         JSONB NOT NULL
);

CREATE INDEX mb_event_metadata_cache_idx_dirty ON mapping.mb_event_metadata_cache (dirty);

    We add the below functions to mbid_mapping/manage.py:

    @cli.command()
@click.option("--use-lb-conn/--use-mb-conn", default=True, help="whether to create the tables in LB or MB")
def build_mb_event_cache(use_lb_conn):
    """
        Build the MB event metadata cache that LB uses.
    """
    create_mb_event_cache(use_lb_conn)

    @cli.command()
@click.option("--use-lb-conn/--use-mb-conn", default=True, help="whether to create the tables in LB or MB")
def update_mb_event_cache(use_lb_conn):
    """
        Update the MB event metadata cache that LB uses incrementally.
    """
    incremental_update_mb_event_cache(use_lb_conn)

    We run build_mb_event_cache(use_lb_conn) to populate the cache by connecting to the MusicBrainz database, fetching all events and their metadata, serializing each event as a JSONB object and inserts into the table, keyed by the event MBID.

    We include incremental_update_mb_event_cache(True) in the update-all-mb-caches cron job to ensure the MusicBrainz event cache is incrementally refreshed alongside the other metadata caches. The cache can also be updated via the manual command added in mbid_mapping/manage.py.

  2. The user_artist_follow table is added to track which artists are followed by users.

    CREATE TABLE user_artist_follow (
    user_id     INT NOT NULL,
    artist_mbid UUID NOT NULL,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    PRIMARY KEY (user_id, artist_mbid),
    FOREIGN KEY (user_id) REFERENCES "user"(id) ON DELETE CASCADE
);

CREATE INDEX user_artist_follow_user_idx ON user_artist_follow (user_id);

CREATE INDEX user_artist_follow_artist_idx ON user_artist_follow (artist_mbid);

  3. The user_timeline_event table is used to store event notifications that appear in a user’s feed.

    When a relevant event occurs (a user follows an artist or an event is announced), a row is inserted into this table, using queries like:

    INSERT INTO user_timeline_event (user_id, event_type, metadata, created)
VALUES (
    123,
    'notification',
    jsonb_build_object(
        'creator', 'listenbrainz-events-bot',
        'message', 'You started following Radiohead'
    ),
    NOW()
);

    INSERT INTO user_timeline_event (user_id, event_type, metadata, created)
VALUES (
    123,
    'notification',
    jsonb_build_object(
        'creator', 'listenbrainz-events-bot',
        'message', 'New event announced: Radiohead - New York, 2026-07-18'
    ),
    NOW()
);

Features

We want to fetch event data from MusicBrainz and store a cached representation inside the ListenBrainz database. This cached data will then be used to implement the following features:

  1. Search also shows events
    When a user uses the search bar, they will also be able to filter and see Events that match their query.

    1600×908 106 KB

    A new component EventSearch will be added in frontend/js/src/search/EventSearch.tsx to handle event search results, utilizing the useQuery hook for efficient asynchronous data fetching and automatic caching. The table rendered in this component mirrors the design and structure of the ArtistSearch results table, to maintain consistency across entity types. The main search page frontend/js/src/search/Search.tsx will be updated to include an Events pill and render EventSearch when the user selects it. The invalidsearchtypes in the same file should permit event as a valid search parameter.

    import EventSearch from "./EventSearch";

// added to the pill row:
<Pill
    id="search-type-event"
    onClick={() => setSearchType("event")}
    active={searchType === "event"}
    type="secondary"
>
    Events
</Pill>

// added to the results section:
{searchType === "event" && searchTermValid && (
    <EventSearch searchQuery={searchTerm} />
)}

    Type definitions in frontend/js/src/search/types.d.ts will be extended to include EventTypeSearchResult, modeled after the MusicBrainz JSON API schema.

  2. Showing events on artist pages
    When a user visits an artist page, they will be able to see upcoming and past events for that artist, such as concerts or festivals where they are performing. This will allow users to quickly discover live performances by artists they are interested in.

    1600×906 117 KB

    A new section for displaying artist events needs to be added to the artist page in frontend/js/src/artist/ArtistPage.tsx. An EventCard component (analogous to the current ReleaseCard component) will be defined to display individual event details.

    A HorizontalScrollContainer will be used to render a horizontal, scrollable row of EventCard components (again, similar to how it’s done for the ReleaseCard components). The events section renders upcoming and past groups separately at the bottom of the page.

    A get_events_for_artist() method will be implemented in listenbrainz/webserver/views/entity_pages.py to query upcoming and past events separately (so that one category doesn’t starve the other).

  3. A dedicated events page
    When a user visits the events page, they will be able to browse upcoming and past events globally, as well as a personalised feed of events from artists they follow. This is similar to the existing Fresh Releases page. An individual detail page will also be added for each event, allowing users to see full information such as the setlist, dates, and performer details.

    1600×906 74.9 KB

    1600×905 95.5 KB

    1600×656 53.6 KB

    1600×779 71.5 KB

    A new UserEvents component needs to be added in frontend/js/src/user/events/UserEvents.tsx. It will have two tabs: ‘All’ for a random global selection of events and ‘For You’ for events from artists the user follows, along with a sidebar for filtering by upcoming, past or cancelled status and event type, and a timeline slider for scrolling through grouped results (like in the Fresh Releases page). The slider needs a small style adjustment with a smaller circle and a larger gap between the labels (implemented in the mockups), since the current Fresh Releases slider overlaps its labels.

    A _get_followed_artist_events() handler should be added to listenbrainz/webserver/views/events_api.py to retrieve the user’s followed MBIDs from the user_artist_follow table and perform a join against the musicbrainz.l_artist_event relationship table. The ‘Main Performer’ or ‘Performer’ for an event should be identified and featured on the EventCard.

    @events_api_bp.get("/user/<mb_username:user_name>/events")
@crossdomain
@ratelimit()
def get_followed_artist_events(user_name):
    user = db_user.get_by_mb_id(db_conn, user_name)
    if not user:
        raise APINotFound("User %s not found" % user_name)

    include_past = _parse_bool_arg("past", True)
    include_future = _parse_bool_arg("future", True)
    count = _parse_int_arg("count", DEFAULT_EVENTS_COUNT)

    events = _get_followed_artist_events(
        user["id"], include_past=include_past,
        include_future=include_future, count=count
    )
    return jsonify({"payload": {"events": events, "user_id": user_name}})

  4. Allowing users to manually follow artists
    When a user visits an artist page, they will be able to follow that artist directly. This lets them receive event notifications for artists they care about, even if those artists are not currently among their top listened-to artists.

    1600×503 95.2 KB

    Three new endpoints need to be added to listenbrainz/webserver/views/social_api.py to handle artist-following: a GET to check follow status, a POST to follow, and a POST to unfollow. The follow endpoint also writes a notification into the user’s timeline feed immediately on follow:

    @social_api_bp.post("/artist/<artist_mbid>/follow")
@crossdomain
@ratelimit()
def follow_artist(artist_mbid: str):
    current_user = validate_auth_header()
    inserted = db_user_artist_follow.follow_artist(
        db_conn, current_user["id"], artist_mbid
    )
    if inserted:
        artist_name = _artist_name_for_notification(artist_mbid)
        db_user_timeline_event.create_user_notification_event(
            db_conn,
            current_user["id"],
            NotificationMetadata(
                creator="listenbrainz-events-bot",
                message=f"You started following {artist_name}",
            ),
        )
    return jsonify({"status": "ok", "artist_mbid": artist_mbid, "follows_artist": True})

    On the frontend, the follow button is wired into frontend/js/src/artist/ArtistPage.tsx. The button renders conditionally for logged-in users:

    {Boolean(currentUser?.auth_token) && (
  <button
    type="button"
    className="btn btn-info"
    onClick={toggleArtistFollow}
    disabled={followLoading}
  >
    {followLoading ? "..." : isFollowingArtist ? "Unfollow" : "+ Follow"}
  </button>
)}

    In listenbrainz/db/user_timeline_event.py, we add create_user_notification_event(), which creates notifications in the user feed for both artist follows and relevant events.

    def create_user_notification_event(db_conn, user_id: int, metadata: NotificationMetadata) -> UserTimelineEvent:
 """ Create a notification event in the database and returns it. 
 """
 return create_user_timeline_event(
     db_conn,
     user_id=user_id,
     event_type=UserTimelineEventType.NOTIFICATION,
     metadata=metadata
 )

  5. Event notifications in the user feed
    ListenBrainz already maintains listening statistics and user activity feeds. When a user follows an artist and that artist has an upcoming event, a notification will appear in their My Feed, the same page that already displays listens, pins and social activity.

    1295×502 39.2 KB

    The existing user_timeline_event table and its notification event type can be reused to deliver event announcements. A background job needs to be added that periodically queries the user_artist_follow table, looks up upcoming events for each followed artist via mapping.mb_event_metadata_cache, and inserts a notification row for each. The notification uses the same create_user_notification_event helper already used for the follow action.

API Endpoints

  • GET /user/<mb_username>/events fetches a personalized feed of events for artists the user follows.
  • GET /event/<event_mbid> retrieves the full details for a specific event.
  • GET /artist/<artist_mbid>/events returns upcoming and past events specifically for one artist.
  • POST /artist/<artist_mbid>/follow allows the authenticated user to follow an artist.
  • POST /artist/<artist_mbid>/unfollow removes the artist from the user’s follow list.
  • GET /artist/<artist_mbid>/follow checks to see if the logged in user follows a specific artist.
  • GET /user/<mb_username>/following lists all users and artists that the specified user is currently following.

Timeline

Week 1
Design the rough database structure for storing MusicBrainz events inside ListenBrainz.

Week 2
Plan how events will be synced and how they will be displayed in different parts of the application.

Week 3
Experiment with small prototypes for fetching and storing MusicBrainz event data.

Week 4
Implement the basic database schema for events and users following artists.

Week 5
Work on importing event data from MusicBrainz into ListenBrainz. Building a reliable script or background task that fetches and stores event information.

Week 6
Expose the stored events through backend APIs. We should be able to retrieve events for an artist and fetch a list of upcoming events globally.

Week 7
Implement the logic for matching events with artists that users listen to frequently.
Explore how to show events to users in the UI (take help from @aerozol).

Week 8
Integrate the event matching logic with the existing ListenBrainz user feed system so that users can receive notifications for upcoming events related to their favorite artists.

Week 9
Improve the reliability and performance of event queries and background tasks.

Week 10
Demonstrate that events can be imported, queried, and connected to artists and users. Get feedback from the community to refine the implementation and address any issues.

Week 11
Add event sections to artist pages so that users can see upcoming concerts or festivals for that artist.

Week 12
Create a dedicated events page where users can explore upcoming events globally or events related to their listening history.

Week 13
Implement a “follow artist” feature so that users can manually follow artists and receive notifications about their events.

Week 14
Focus on bug fixes, performance improvements, and polishing the overall user experience.

Weeks 15-17
Code cleanup, documentation, testing.
(Exams during Week 16)

Due to the scope of the project, it will take ~350 hours to complete it.

Community affinities

What type of music do you listen to?

Heres a list of a few songs ive been listening to recently:

  1. KALYANI (3ca7b533-eec6-49fb-b407-37863c61eb55)

  2. Banda Kaam Ka (1c5b06c4-036a-4f1e-90b5-53776919e379)

  3. Thehra (c32f0b37-a192-44d5-bed6-1be440dc2143)

What aspects of ListenBrainz interest you the most?

The open data philosophy, the Music Listening Histories Dataset, the importance of big data projects for music research.

Have you ever used MusicBrainz Picard to tag your files or used any of our projects in the past?

Yess! I used it for the first time while writing the proposal because it was mentioned here and I got curious. Its really cool, thanks to whoever made this question :)) I have been actively using Listenbrainz since November to track and analyse my music listening activity. I’m also in the process of integrating Listenbrainz to one of my research projects mentioned above.

Programming precedents

When did you first start programming?

First year of college

Have you contributed to other open source projects?

Work on personal Open-Source projects:

SYRA

Practical requirements

What computer(s) do you have available for working on your SoC project?

I have a Dell Inspiron laptop running EndeavourOS with 16 GBs RAM and i7 13th gen.

How much time do you have available per week, and how would you plan to use it?

25–30 hours/week. No other internships. However, I will be doing music cognition research and plan to work from my lab over the summer as it provides a good environment for me to be productive.

3 Likes
2

In the mockups and proposal, I have not used the events art. When I looked through most of the events in MusicBrainz, they did not have art work so I thought for now it might look a little ugly as most of the events will then have a generic image. What do you guys think about it: @aerozol @mr_monkey @anshgoyal31

3

I’m not a maintainer but “thank you” .

I did not feel like I just read AI slop , I hope you get it :smile:

1 Like
4

We want to encourage users to add more data (e.g. event art) to MusicBrainz, and showing annoying generic art on LB will do that.

But that doesn’t mean you have to show the art everywhere - I would mainly expect it on the dedicated page for an event (it doesn’t look like your mockups includes this?)

1 Like
6

Hi, I see your point, I’ve updated the mockups. I’m using the ListenBrainz logo as the placeholder if an event does not have event-art. Also, added the mockups for individual event pages. TYSM for the suggestions :)))

7

Hi @Haris076 ,

The proposal is starting well, thanks for posting it :slight_smile:

I will say at a quick read-through, while you lay out the various parts of the project fairly well there aren’t nearly enough details about implementation for me to give you a full review.

As just one example of this, “These tables allow the system to cache MusicBrainz event data” is about all you say about this.
How is the cache created? What do the SQL queries look like? What does the cache contain? When/how is it updated?

For each technical aspect listed in the timeline, please add as much details as you can so we can evaluate the proposed solution form a technical standpoint rather than just a feature description.

1 Like
8

Hello @mr_monkey ,

Thanks for reviewing the proposal, based on your feedback, I have updated the proposal with technical details about everything required (according to me ie). I also came across LB-1549 (Pull MeB user area (OAuth)) while going through the associated tickets, I believe that wont take long to implement in this project and can be implemented after (or before?) the GSOC period. Please let me know your feedback on the updated proposal and the above stated assumption.