YouPlay

A streamlined music streaming service that generates playlists based on the user's current mood.

Developed by: Heather Browning, Joshua Lopes, Sebastian Nunez, Yixin (Fiona) Zhao

Table of Contents

• Technologies
• Project Board
• Demos
• Core Features
  • Authentication
  • Player Controls
  • Song Search
  • Playlist Management
  • Playlist Interaction
• Getting Started
• Product Spec
  • User Stories
  • Screen Archetypes
  • Navigation
  • Wireframes
• Internal Services
• Data Models

Technologies

• Language: Swift
• iOS Framework: SwiftUI
• Auth: Firebase Auth
• Music Playback: Spotify iOS SDK
• Song Metadata: Spotify Web API
• Database
  • NoSQL: Firebase Firestore
  • Object Storage: Firebase Storage

Project Board

You can find our project board here.

Demos

You can find a series of short demos GIFs here.

Core Features

Authentication

• Complete authentication flow (login, sign up, logout) using email and password alongside Google OAuth
• Users can update their profile picture with direct upload to Firebase Storage
• Password reset functionality via email

Player Controls

• Player interface displaying the currently playing song with audio playback controls
• Users can view song details by clicking on the crumb-bar
• Users can add songs to a playlist directly from a menu

Song Search

• Users can search for any song
• Users can view their recently played songs

Playlist Management

• Users can create and delete playlists
• Users can remove songs from a playlist

Playlist Interaction

• Users can play any song
• Playlists are kept up-to-date using the lastModified date
• Users can refresh their playlists
• Implemented search for songs within a playlist by text

Getting Started

1. Check out CONTRIBUTING.md

Read through our contributing document to get up-to-speed with project standards and expectations.

2. Create a Firebase iOS application

Our application runs mostly through Google's Firebase platform.

You can go here to get started setting up an iOS application.

3. Create a Spotify API application

Head over to your Spotify Dashboard and register a new application.

App name: YouPlay

App description: A mood based music streaming service.

Website: Can be left empty

Redirect URI: spotify-ios-you-play://spotify-login-callback

Which API/SDKs are you planning to use?

• [x] Web API
• [x] iOS

After you have done the initial setup, open the app's Settings and add the following iOS app bundles:

• com.you-play.YouPlay

Your settings should be similar to this.

Lastly, make sure the App bundle within XCode matches above.

Note: If the bundle ID is NOT available in XCode, you can add a suffix (ex. com.you-play.YouPlay-Sebastian). Make sure to update it in your Spotify Dashboard settings.

4. Run the App Locally

1. Clone the repo: git clone https://github.com/you-play/YouPlay/
2. Download the GoogleService-Info.plist (not required if you have your own Firebase app) and SpotifyService.plist from our Google Drive (or you can find empty "templates" here)
3. Replace/add the CLIENT_ID and CLIENT_SECRET in the SpotifyService.plist with your own Spotify credentials
4. Add the GoogleService-Info.plist and SpotifyService.plist into /ios-app/YouPlay/ folder (Tip: you can drop the files directly into the XCode UI file explorer)
5. Build and start the app in Xcode

Product Spec

User Stories

Required Must-have Stories

As a user, I want to select my current mood from a select list of songs (based on energy, and dance-ability...) so I can quickly receive a playlist that matches how I'm feeling.

As a user, I want to be able to play, pause, and skip songs (no shuffle, forward and backward) in the playlist so I can bypass tracks that don't quite fit my mood or take a break.

As a user, I want to discover new music tailored to my mood so I can expand my musical tastes while staying within the emotional context I prefer.

As a user, I want to save playlists generated based on my mood so I can listen to them again later.

As a user, I want to see the name of the currently playing song and its artist so I can explore more from artists I like.

As a user, I want to adjust the number of songs on the playlist based on my available time so that the music lasts for my desired listening period.

As a user, I want to be able to "Like" tracks and have a "Liked Tracks" playlist automatically generated so I can improve future playlist recommendations.

As a user, I want to provide feedback on playlist suggestions so that the app can refine its future recommendations for me.

Optional (Nice-to-have Stories)

As a user, I want to create custom moods so I can have even more personalized playlists that reflect my unique feelings.

As a user, I want to combine multiple moods into a single playlist so I can enjoy a mix that reflects my complex emotional state.

As a user, I want to set mood-based alarms so I can wake up or be reminded with music that fits how I want to feel.

As a user, I want to see visualizations or artwork that match the mood of the current playlist so I can enhance my listening experience.

As a user, I want the option to filter songs by language or genre within a mood category so I can tailor the music even further to my

Screen Archetypes

• Login Screen
  • As a user, I must be able to log in
• Sign-up Screen
  • As a user, I must be able to create an account
• Profile screen
  • As a logged-in user, I should be able to click on my avatar and be taken to a profile screen.
• Mood Selector
  • As a logged-in user, I want to be prompted to select the mood I am in
• Suggested Songs Screen
  • As a logged-in user, I want to be able to see several songs that
• Unique Song Screen
  • As a user, I want to be able to click on a song cover and see the song in full screen.
  • As a user, I would like to navigate through a song
• My Playlist Screen
  • As a logged-in user, I want to be able to see all of my playlists
• Unique Playlist Screen
  • As a logged-in user, I want to be able to be able to browse through the songs in my playlist.
• Search bar
  • As a logged-in user, I should be able to search for songs.

Navigation

Tab Navigation (Tab to Screen)

• [x] Home
• [x] Search
• [x] Playlists

Flow Navigation (Screen to Screen)

• [x] Login/Sign-up
  • Leads to Home
• [x] Profile (after clicking "Log out")
  • Leads to Login/Sign-up
• [x] Home (after clicking a Playlist) Leads to the Playlist screen for it
• [x] Home (after clicking a Song)
  • Leads to Song/Playback (bottom sheet) for it
• [x] Song/Playback (after dismissing a Song bottom sheet)
  • Leads to Home
• [x] Song/Playback (after hitting the "Add to Playlist" button)
  • Leads to PlaylistSelection bottom sheet

Wireframes

Digital Wireframes

Internal Services

These are the main planned network services available in the app.

Note: These are not kept up-to-date.

AuthService

Handles all internal communication and authentication with Firebase Auth.

PlaylistService

Handles internal playlist management (creation, delete, etc.).

PlaybackService

Handles all audio playback controls connected to the Spotify SDK controller.

SpotifyService

Connects the application to the Spotify Web API and allows querying and fetching song metadata.

StorageService

Handles object storage communication with Firebase Storage.

UserService

Handles user metadata access and retrieval (profile picture, demographics, etc.)

Data Models

These are the core planned data models for the app.

Note: These are not kept up-to-date.

User

Property	Type	Description
uid	String?	Firestore ID
username	String	Username of the user
email	String	Email of the user
id	String	Unique identifier (fallback to UUID if uid is nil)
age	Int?	Age of the user (optional)
gender	Gender?	Gender of the user (enum or optional string)
profileImageUrl	String?	URL of the user's profile image (optional)

Player

Property	Type	Description
repeatState	String	State of repeat functionality
shuffleState	Bool	State of shuffle functionality
isPlaying	Bool	Indicates if a song is currently playing
song	Song	Information about the currently playing song
actions	Actions	Actions that can be performed on the player

Actions

Property	Type	Description
interruptingPlayback	Bool	Indicates if playback is being interrupted
pausing	Bool	Indicates if playback is being paused
resuming	Bool	Indicates if playback is being resumed
seeking	Bool	Indicates if seeking within the playback
skippingNext	Bool	Indicates if skipping to the next track
skippingPrev	Bool	Indicates if skipping to the previous track
togglingRepeatContext	Bool	Indicates toggling repeat for the current context
togglingShuffle	Bool	Indicates toggling shuffle mode
togglingRepeatTrack	Bool	Indicates toggling repeat for the current track
transferringPlayback	Bool	Indicates if playback is being transferred

Album

Property	Type	Description
albumType	String	Type of the album (e.g., "album", "single")
totalTracks	Int	Total number of tracks in the album
href	String	URL of the album
id	String	Unique identifier of the album
images	[AlbumImage]	Array of images representing the album
name	String	Name of the album
uri	String	Spotify URI of the album
artists	[Artist]	Array of artists who contributed to the album
tracks	Tracks	Information about the tracks in the album
popularity	Int	Popularity score of the album

SpotifyImage

Property	Type	Description
url	String	URL of the album image
height	Int?	Height of the album image in pixels
width	Int?	Width of the album image in pixels

Artist

Property	Type	Description
id	String	Unique identifier of the artist
name	String	Name of the artist

Song

Property	Type	Description
documentID	String?	Firestore document ID
title	String	Title of the song
artists	[String]	Array of artist names contributing to the song
imageURL	String	URL of the image representing the song
id	String	Unique identifier for the song

TracksResponse

Property	Type	Description
items	[Song]	Array of song responses representing tracks
limit	Int	Maximum number of items returned in the response
offset	Int	Offset for the paginated response
total	Int	Total number of items available