GSOC 2021: Short CB Reviews & Pin Recordings

Tags: #<Tag:0x00007f510db17ed8>

This proposal consists of two of the smaller sized projects suggested on the MusicBrainz Wiki.

Personal Information

  • Nickname: Jason
  • IRC Nick: jasondk
  • MB username: whirlwind
  • Github: jdaok
  • Time Zone: UTC-8

Create short music reviews on ListenBrainz using the CritiqueBrainz API

Project Overview

ListenBrainz should allow users to write short reviews for tracks, release groups, and artists directly through our website using the CritiqueBrainz API. This project aims to drive increased contributions of reviews to CritiqueBrainz by making it easier to submit them. Reviews submitted through this feature should also populate the ListenBrainz feed.

Project Description + Mockups

Users will be able to write reviews through the ‘My Listens’ page.

enter image description here

The user will be prompted to select the entity to review and write the review directly from ListenBrainz.

Users will be able to view reviews that they and their followers wrote on their User Feed.

(clicking on the review card will open the full review on CritiqueBrainz)


Submitting Reviews

The user will first authorize ListenBrainz to post reviews with their CritiqueBrainz account through OAuth 2 (The cb_auth_token will be stored in the “user” table).

Submitting reviews requires the entity MBID which can be retrieved with the track metadata:

Release Group MBID

Lastfm_release_mbid: must lookup RELEASE_GROUP_MBID using MB API.

Otherwise, must lookup release MBID using LABS API (mbid-mapping),
then lookup RELEASE_GROUP_MBID using MB API.

Artist MBID

Lastfm_artist_mbid: can be used as is.

Artist_msid: must lookup artist MBID using LABS API (artist-credit-from-artist-msid)

Recording MBID

Must lookup recording MBID using LABS API (mbid-mapping).

submitReviewToCB()will be added to send post requests to CB’s API.

Fetching Reviews to Display On User Feed

Currently the CritiqueBrainz API allows searching for reviews by CB user UUID (whereas LB uses musicbrainz_id’s instead). The CB API will be first modified to allow for searching reviews by musicbrainz_id.

The process of fetching reviews to display on the user feed:

Reviews would be searched for every musicbrainz_id in the user’s following list and themselves.

Pin Favorite Recordings to Profile

Project Overview

Currently all a user can do to show their love for a recording is to “love” it or recommend it. This project aims to allow for ListenBrainz users to pin their favorite recording to their profiles with a short blurb. This feature will allow users to get a better idea of what kind of music their following circle is interested in and make user profiles more personalized.

Project Description + Mockups

Users will be able to pin recordings from their ‘My Listens’ page.

enter image description here

The Pin Track modal will look like this: (Users will only be able to have one track pinned at a time and the typed blurb will be capped at 280 characters.)

When visiting other profiles the pinned track will display at the top of the ‘Listens’ tab.

Also all tracks the user has ever pinned will be displayed on

(Tracks can be deleted from this tab as well).

On the User Feed: if anyone the User is following has a recording pinned, it will appear under the BrainzPlayer.

(one pinned recording will display per user).



A separate Postgres table will store pinned tracks:

Column Type Nullable Default
user_id INTEGER not null
track_metadata JSONB not null
blurb_content VARCHAR
currently_pinned BOOLEAN not null TRUE
created TIMESTAMP (w/ tz) not null NOW()
  • User_id will reference id from the “user” table.
  • track_metadata will contain recording_msid, artist/release/track name, and additional info.


The new API routes and corresponding SQL queries will look like this:

Pin a track to the user’s profile and submit it to the server:

POST /pin/pin-track {
    user_id: 63241,
    track_metadata: {track metadata}
    blurb_content: ‘My favorite song right now!’ 

UPDATE pinned_track SET currently_pinned = FALSE WHERE user_id = :user_id AND currently_pinned = TRUE
INSERT INTO pinned_track (user_id, track_metadata, blurb_content, created)
// Returns response status

Unpin a track from the user’s profile and update the server:

POST /pin/unpin-track {
    user_id: 63241,

UPDATE pinned_track SET currently_pinned = FALSE WHERE user_id = :user_id AND currently_pinned = TRUE
// Returns response status

Get the pinned track for a single user

GET /pin/user/<user_id>/get-user-pin {
    user_id: 63241,

SELECT (user_id, track_metadata, blurb_content, created) FROM pinned_track WHERE user_id = :user_id AND currently_pinned = TRUE
// Returns json with pinned track or none

Get the pinned tracks of every user in a user’s following list

GET /pin/user/<user_id>/get-user-following-pins {
    user_id: 63241,

// Will iterate over a list of musicbrainz ID’s.
SELECT (user_id, track_metadata, blurb_content, created) FROM pinned_track WHERE user_id = :user_id AND currently_pinned = TRUE
// Returns json with pinned tracks or none, and count

Get the pinned track history of a user

GET /pin/user/<user_id>/get-user-pin-history {
    user_id: 63241,

SELECT (user_id, track_metadata, blurb_content, currently_pinned, created)  FROM pinned_track WHERE user_id = :user_id
// Returns json with pinned tracks or none, and count

Delete a track from pinned history

POST /pin/delete-pin {
    user_id: 63241,
    track_metadata: {track metadata}
    created: 1617436332

DELETE FROM pinned_track WHERE user_id = :user_id AND track_metadata = :track_metadata AND created = :created
// Returns response status


Pre-Community Bonding Period

I plan to work on tickets and features to get more experience with the code structure, and related technical skills .

Community Bonding Period

  • Modify CB API to support review search by musicbrainzID
  • Make sure there is a clear roadmap defined for both projects

Week 1-2: Begin CritiqueBrainz project

  • Implement CB OAuth
  • Create barebones “Write Review” modal
    • Make sure the button calls submitReviewToCB() and submits for the correct entity.
  • Write corresponding tests

Week 3-4:

  • Write get_cb_review_events()
  • Implement UI components
    • “Write review” modal
    • Timeline Event Card
  • Write frontend tests

Week 5:

  • Buffer period to finish project if behind. Otherwise continue first evaluation

Week 6-7: Begin Pin Recording project

  • Implement pinned_track schema
  • Write API endpoints + routes
  • Write SQL queries
  • Write corresponding tests

Week 8-9:

  • Implement UI components
    • Pin track modal
    • Pinned track cards
    • Pinned track history tab
    • Pinned tracks list in user feed
  • Write frontend tests

Week 10:

Buffer period to catch up if behind. Then finish writing documentation and fixing bugs or start on stretch goals. final evaluation!

Stretch Goals / Post-GSOC Ideas :

  • “Reviews” tab that shows user’s CritiqueBrainz reviews on LB profiles
  • User feed customization: allow users to filter which events they want to see on their feed (only display listens, reviews, etc.)

Information About Me

I am a sophomore studying computer science who will be attending University of California, Davis in the fall. I started contributing to ListenBrainz in January.

Tell us about the computer(s) you have available for working on your GSoC project!

I have a desktop computer running Windows 10 with an Intel i7 processor and 8 GB RAM.

When did you first start programming?

My first experiences programming were making ROBLOX games in middle school (but I only started to take programming seriously in high school).

What type of music do you listen to? (Please list a series of MBIDs as examples.)

I listen to a lot of experimental pop music and R&B. I also like electronic and dance music.

What aspects of the project you’re applying for (e.g., MusicBrainz, AcousticBrainz, etc.) interest you the most?

I’m an obsessive tracker of my listening history, I love music, metadata, and collecting information about my listening habits :smile: The music data that LB collects is public which is useful in building tools that improve music recommendation technologies. The ListenBrainz project stands out because it’s open source and any passionate individual can contribute.

Have you ever used MusicBrainz to tag your files?

I haven’t used MusicBrainz to tag my files yet.

Have you contributed to other Open Source projects? If not, do you have other code we can look at?

I am new to open source but many of my projects can be found on my GitHub.

What sorts of programming projects have you done on your own time?
I have made a lot of interactive websites as portfolios or shops or calculators.

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

I will likely be able to dedicate 40+ hours to GSoC each week.

Do you plan to have a job or study during the summer in conjunction with Summer of Code?

I would be working part time on the weekends but it should not interfere with my availability for GSoC significantly, and I will be out of school and available for the entire duration of the program.


Overall, this looks really good! I have a few general comments.

  • The OAuth to CB is not ideal, but probably what we should do for this project. Ideally, we’d just need to OAuth to once and use that to recognize users, but that’s a separate project. I would get in touch with lucifer and ruaok about it though.

  • Another thing I’d like to see is more thinking about failure modes. For example, what happens if the labs API isn’t able to map a msid to an MBID, how do we surface that to the user?

  • It’d be great if we could have something in CB (maybe a source field) which we can later use to recognize which reviews come from LB.

  • We should also think about metrics we want to track and such. This might the perfect place to start using brainzutils metrics system in LB. I would love to see graphs of number of reviews added and such.

  • Would love for the timeline to clearly mark deliverables for each week or such, I think that really helps when actually working on the project. Also, try to think of this in a way that things can be released every week or so. I’d prefer that instead of two huge releases each during an evalution period.

More specific implementation related comment:

I don’t think we’ll want to hit the CB API to get feed events, we should store them in the user_timeline_event table.

1 Like