📚 Contents

• What is the Project?
• Installations
• Setting up Databases for Windows and Linux
  • Setting up the Database
  • Importing the Artists & Tracks
• Setting up Databases for Mac
  • Script for Populating Database
• API Endpoints
• Running The App
• How did we create it?
  • The Creation Process

---

What is the Project?

This project is a web app that addresses the gender bias in the music streaming industry by generating playlists made exclusively of female artists. Using the Spotify and ReccoBeats APIs, the web app will gather user preferences and create personalised, bias-aware music recommendations. It also uses OAuth to save this generated playlist to a users account.

---

Installations

1. Clone the repository
2. Install Dependencies - pip install -r requirements.txt for all packages used in the project.
3. Update .env with your configuration:

DB_HOST=localhost
DB_USER= # Insert your username
DB_PASSWORD= # Insert your password
DB_NAME=playlist_generator # Name of database

4. Spotify credentials are required in order to set up the OAuth connection. This involves creating a Web API Spotify developer app, but note this is not needed as part of the set up of the app.

Spotify OAuth setup (optional)

1. Navigate to: https://developer.spotify.com/documentation/web-api.
2. Log in with your Spotify Account and then navigate here: https://developer.spotify.com/dashboard.
3. Then click create app.
4. Give this a relevant name and description, and set your redirect URI to be your relevant base URL /authcallback. For example, http://127.0.0.1:5000/authcallback.
5. Then tick Web API for the 'Which API/SDK are you planning to use?'.
6. Finally tick to agree with Spotify's Terms of Service and save.
7. You can then use your Client ID and secret as global variables within the auth/auth_config.py file.

---

Setting up Databases for Windows and Linux:

Setting up the Database

Open the file at db\schema\playlist_generator_db.sql. Run each SQL statement to create the database as well as the tables. There should be 3 tables for you to create. artists, tracks, and recommendations.

Importing the Artists & Tracks

Importing the Artists

1. It is imperative artists is uploaded first in the database. To do this refresh your schemas on the left, then right-click on the artists table, and select Table Data Import Wizard.
2. Then you will need locate the artists.csv, which you will find at db\data\artist.csv .
3. When prompted select Use Existing Table, ensure you are using playlist_generator.artists.
4. Next ensure the configure settings are correct. spotify_artist_id matches spotify_artist_id and name matches name.
5. After this continue clicking Next, and it will be imported. 6. This can be checked by running SELECT * FROM artists;

---

Importing the Tracks

1. After uploading artists we can now import the track data. Now right-click on the tracks table, and select Table Data Import Wizard.
2. Then you will need locate the tracks.csv, which you will find at db\data\tracks.csv .
3. When prompted select Use Existing Table, ensure you are using playlist_generator.tracks and click next.
4. Now ensure all the source columns and destination columns match and click next.
5. After this continue clicking Next, and it will be imported. 6. This can be checked by running SELECT * FROM tracks;.

Now the database is ready to be queried!

---

Setting up Databases for Mac:

Script for Populating Database

1. Mac may prove difficult to follow the steps above so we have created a script to populate the database with data.
2. IMPORTANT: The script relies on the current file structure:
   1. db/data/ contains the CSV files
   2. db/scripts/ contains this script
   3. db/db_utils.py provides database connection and helper functions
   4. Do NOT rename, move, or delete these folders or files. The script uses relative paths and imports that depend on this structure, so changing it will break functionality.
3. Run the script import_cvs.py. Then you should receive confirmation:
   1. Inserting artists...
   2. Inserting tracks...
   3. CSV data inserted successfully!

Now the database is ready to be queried!

---

API Endpoints

Endpoint	Method	Description
/	GET	Serves the landing page
/quiz	GET	Renders the quiz form
/quiz-response	GET, POST	Processes quiz answers and renders the generated playlist
/create-playlist/<user_id>	GET	Creates a private Spotify playlist for the user
/playlist-added	GET	Displays playlist creation success or failure
/authcallback	GET	Handles Spotify OAuth callback, exchanges auth code for token, stores it, and redirects to playlist creation

---

Running The App

• Navigating to your root folder where the project is and run python app.py in the terminal.
• Alternatively you can navigate to app.py, right click and run.
  • Shortcut: ctrl+Shift+f10

Then open the link it shows in your terminal http://127.0.0.1:5000 This directs you to the homepage:

After you click "start the quiz" it will redirect you to the quiz endpoint: Here you can answer the questions from ranges strongly disagree to strongly agree. After this you can click generate playlist and it will generate you an all-female playlist!

Once the quiz has been completed, and you select Generate Playlist You will see the following page:

The next step is to save to your spotify account. Once you click this button it will redirect you to the Spotify login page:

You will receive confirmation on our endpoints that looks like this:

Now, it will be saved to your Spotify account and you can listen to your newly generated playlist!

---

How did we create it?

The Creation Process

Skeletal Database Creation

How We Chose Our Catalogue

• As a team we created a shared Excel spreadsheet with our favourite female artists. The reasoning was because Spotify doesn't store gender. So we instead had the idea to create our own database full of our favourites which will then be queried later down the line.
• A script was then run which looked up our artists with 10 of their songs to populate into a CSV file.

How we populated the Database

• We were able to grab song and artist ID's from the Spotify API using python which wrote it to a CSV file.
• The file was really with over 500+ songs, so we decided to keep it in that format and use the Import Wizard native to MySQL Workbench.

How we Mapped the Audio Features

• We unfortunately found we cannot get audio features from the Spotify API because the end point was deprecated.
• As a work-around we found we can get the same audio features from ReccoBeats API.
• The script was ran using our list of song ID's and artist ID's in our CSV file.

What are Audio Features?

Audio features in the Spotify API are numeric values that describe the musical qualities of a track. Things like danceability, energy, loudness, tempo, valence, and instrumentalness. They help quantify how a song sounds or feels. This was used in our recommendation process in our database.

How We Give Reccommendations

• For each quiz answer, we convert the user's choice into a target audio feature value.
• Every song has real feature values from Spotify. To measure how close a song is to the user’s ideal preferences, we compare each song’s feature to the target using a normalised squared distance.
• Squaring the difference penalises large mismatches more strongly, so a song that is perfect in 4 features but very bad in 1 will score lower than one that is consistently close across all features.
• Songs are sorted by score, the top candidates are selected, shuffled, and written to the recommendations table.

The Maths Visualised

API Endpoints

GET /

Purpose: Serves the main landing page of the application. Notes:

• Renders index.html from the custom_templates directory.
• Acts as the entry point to the user interface.

GET /quiz

Purpose: Displays the quiz interface where users provide answers used for playlist generation. Notes:

• Renders form.html, which contains the quiz form and frontend logic.
• The form submits user responses.
• This endpoint only renders the quiz page.

POST /quiz-response

Purpose: Processes the user's quiz responses, converts them into target audio feature values, and generates a recommended playlist.
Notes:

• Translates quiz answers into audio feature targets using the preference model.
• Generates and scores tracks using the playlist generator.
• Renders playlist.html with the recommended playlist and Spotify redirect link.

GET /create-playlist/<user_id>

Purpose: Creates a private Spotify playlist for the authenticated user using generated recommendations.
Notes:

• Requires a valid Spotify OAuth access token for the given user.
• Fetches recommended tracks from the database.
• Creates a private playlist in the user’s Spotify account and adds all tracks.
• Redirects to a confirmation page after creation.

GET /playlist-added

Purpose: Displays a confirmation page indicating whether the Spotify playlist was successfully created.
Notes:

• Reads the playlist creation status from query parameters.
• Renders playlist-added.html with success or error messaging.

---

    ♡  ∩_∩
   ( „• ֊ •„ ) ♡
|￣￣￣U   U￣￣￣￣￣￣￣￣￣￣￣￣￣￣|
|  Thanks for reading the README! |
|＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿＿|