PartyPlaylist Documents

use-cases.md

Overview

PartyPlaylist is a music sharing application that allows users to join a session as participants, where one of the participants will be the host of the session. The application will play the sound of the song from the host, allowing other participants to listen to the same music simultaneously. Each session will have a unique link that will be shared with participants to join the session. Participants will be required to login using their Google account.

Features

• Session creation: The host can create a new session and get a unique link to share with the participants.

• Join session: Participants can join the session by clicking on the unique link, without needing to enter a session ID or password.

• Google login: Participants will be required to login using their Google account.

• Music playback: All participants will have the control to switch to different songs, adjust the volume, and skip to a specific part of the song.

• Manage participants: The host can kick out participants from the session.

• Playlist management: Participants can add songs to the playlist, remove songs from the playlist, and move songs up and down the playlist.

Use Cases

1. Log in
2. Log out
3. Create a new session
4. Join a session
5. Add to playlist
6. Remove from playlist
7. Move song to top of the playlist
8. Move song to bottom of the playlist
9. Move song up one song
10. Move song down one song
11. Play/Pause the current song
12. Play the next song
13. Play the previous song
14. Jump to a specific position in current song
15. Kick out participant
16. Find a new host
17. End session
18. Leave session

1. Log in

Expands

Actors: User

Trigger: The user clicks on the "Log in" button.

Preconditions: The user is not logged in.

Postconditions: The user is logged in.

Main Flow:

1. The user clicks on the "Log in" button.
2. The user is redirected to the login page.
3. The user logs in using their Google account.
4. The user is redirected back to the home page.

2. Log out

Expands

Actors: User

Trigger: The user clicks on the "Log out" button.

Preconditions: The user is logged in.

Postconditions: The user is logged out.

Main Flow:

1. The user clicks on the "Log out" button.
2. The user is logged out.

3. Create a new session

Expands

Actors: Host

Trigger: The host clicks on the "Create a new session" button.

Preconditions: The host is logged in.

Postconditions: A new session is created and the host is redirected to the session page.

Main Flow:

1. The host clicks on the "Create a new session" button.
2. The host is redirected to the session page.

4. Join a session

Expands

Actors: Participant

Trigger: The participant enters the unique link to join the session.

Preconditions: The participant is logged in.

Postconditions: The participant is redirected to the session page.

Main Flow:

1. The participant enters the unique link to join the session.
2. The participant is redirected to the session page.

5. Add to playlist

Expands

Actors: Participant

Trigger: The participant clicks "Add to playlist" button.

Preconditions: The participant is joined in the session.

Postconditions: The song is added to the playlist.

Main Flow:

1. The participant clicks "Add to playlist" button.
2. The participant enter a song url.
3. The song is added at the bottom of the playlist.

6. Remove from playlist

Expands

Actors: Participant

Trigger: The participant clicks "Remove song from playlist" button.

Preconditions: The participant is joined in the session.

Postconditions: The song is removed from the playlist.

Main Flow:

1. The participant clicks "Remove song from playlist" button.
2. The participant selects a song to remove from the playlist.
3. The song is removed from the playlist.

7. Move song to top of the playlist

Expands

Actors: Participant

Trigger: The participant clicks "Move song to top of the playlist" button on the song item.

Preconditions: The participant is joined in the session.

Postconditions: The song is moved to the top of the playlist.

Main Flow:

1. The participant clicks "Move song to top of the playlist" button on the song item.
2. The song is moved to the top of the playlist.

8. Move song to bottom of the playlist

Expands

Actors: Participant

Trigger: The participant clicks "Move song to bottom of the playlist" button on the song item.

Preconditions: The participant is joined in the session.

Postconditions: The song is moved to the bottom of the playlist.

Main Flow:

1. The participant clicks "Move song to bottom of the playlist" button on the song item.
2. The song is moved to the bottom of the playlist.

9. Move song up one song

Expands

Actors: Participant

Trigger: The participant clicks "Move song up one song" button.

Preconditions: The participant is joined in the session.

Postconditions: The song is moved up one song.

Main Flow:

1. The participant clicks "Move song up one song" button.
2. The song is moved up one song.

10. Move song down one song

Expands

Actors: Participant

Trigger: The participant clicks "Move song down one song" button.

Preconditions: The participant is joined in the session.

Postconditions: The song is moved down one song.

Main Flow:

1. The participant clicks "Move song down one song" button.
2. The song is moved down one song.

11. Play/Pause

Expands

Actors: Participant

Trigger: The participant clicks "Play" button, "Pause" button, "Next" button, "Previous" button or clicks anywhere on the progress bar.

Preconditions: The participant is joined in the session.

Postconditions: The player is updated.

Main Flow:

1. The participant clicks "Play" button.

2. The player starts playing the song.

3. The participant clicks "Pause" button.

4. The player pauses the song.

5. The participant clicks "Next" button.

6. The player plays the next song in the playlist.

7. The participant clicks "Previous" button.

8. The player plays the previous song in the playlist.

9. The participant clicks anywhere on the progress bar.

10. The player jumps to the selected position in the song.

12. Play next song

Expands

Actors: Participant

Trigger: The participant clicks "Next" button.

Preconditions: The participant is joined in the session.

Postconditions: The player plays the next song in the playlist.

Main Flow:

1. The participant clicks "Next" button.
2. The player plays the next song in the playlist.

13. Play previous song

Expands

Actors: Participant

Trigger: The participant clicks "Previous" button.

Preconditions: The participant is joined in the session.

Postconditions: The player plays the previous song in the playlist.

Main Flow:

1. The participant clicks "Previous" button.
2. The player plays the previous song in the playlist.

14. Jump to a specific position in current song

Expands

Actors: Participant

Trigger: The participant clicks anywhere on the progress bar.

Preconditions: The participant is joined in the session.

Postconditions: The player jumps to the selected position in the song.

Main Flow:

1. The participant clicks anywhere on the progress bar.
2. The player jumps to the selected position in the song.

15. Kick out participant

Expands

Actors: Host

Trigger: The host clicks "Kick out" button

Preconditions: The host is joined in the session.

Postconditions: The participant is kicked out of the session.

Main Flow:

1. The host clicks "Kick out" button.
2. The participant is kicked out of the session.

16. Find a new host

Expands

Actors: System

Trigger: The host leaves the session.

Preconditions: The host is joined in the session and there are still participants in the session.

Postconditions: The system finds a new host.

Main Flow:

1. The host leaves the session.
2. The system finds a new host.

17. End session

Expands

Actors: Host

Trigger: The host clicks "End session" button.

Preconditions: The host is joined in the session.

Postconditions: The session is ended.

Main Flow:

1. The host clicks "End session" button.
2. The session is ended.

18. Leave session

Expands

Actors: Participant

Trigger: The participant clicks "Leave session" button or the session is ended.

Preconditions: The participant is joined in the session.

Postconditions: The participant leaves the session.

Main Flow:

1. The participant clicks "Leave session" button.
2. The participant leaves the session.

Alternative Flow:

1. The session is ended.
2. The participant leaves the session.

Websocket Events

• session-join - When a user joins a session (connect websocket).

• session-leave - When a user leaves a session (disconnect websocket).

• session-kick-out - When a user is kicked out of the session.

• session-end - When a user ends the session.

• session-find-new-host - When a user is kicked out of the session and the system finds a new host.

• session-new-host-found - When a user is kicked out of the session and the system finds a new host.

• queue-song-add - When a user adds a song to the playlist.

• queue-song-remove - When a user removes a song from the playlist.

• queue-move-song-top - When a user moves a song to the top of the playlist.

• queue-move-song-bottom - When a user moves a song to the bottom of the playlist.

• queue-move-song-up - When a user moves a song up one song.

• queue-move-song-down - When a user moves a song down one song.

• player-play - When a user plays a song.

• player-pause - When a user pauses a song.

• player-next - When a user plays the next song in the playlist.

• player-previous - When a user plays the previous song in the playlist.

• plyer-jump - When a user jumps to a specific position in the song.

POST users - usecase login

"create user, and login"
authorization: "Bearer Token"
body : {
	uid:string;
}
return :
	status 201
	response: {
		data : {
			uid:string
		}
	}
	status 202
	response : {
		message: "user already exists"
	}	

POST sessions - usecase create a new session

"Create a new Session"
authorization: "need to loggedIn (Bearer Token) and Online" 
body: {
	name:string //name of the session
}
return: 
	status 201
	response: {
		data: {
			code: string
		}
	}

GET sessions/{code}

"get Session detail"
authorization: "need to loggedIn (Bearer Token)"
return:
	status 200
	response: {
		data: {
			name: string,
			host: {
				uid:string,
				email?:string,
				displayName?:string,
				photoURL?:string
			}
		}
	}

DELETE sessions/{code} - usecase end session

"End session, only host"
authorization: "need to loggedIn (Bearer Token) and Online"
return:
	status 204 "no content"

POST sessions/{code}/participants - usecase join a session

"Add User to a Session"
authorization: "need to loggedIn (Bearer Token) and Online" 
body: {
	
	// TODO: username alias??
	// alias: string
	userId: string
	
} 
return:
	status 201

GET sessions/{code}/participants

"Get All Participant on a session"
authorization: "need to loggedIn (Bearer Token)"  
return: 
	status 200
	response: {	
		data: {
			participants : [{
				uid:string,
				email?:string,
				displayName?:string,
				photoURL?:string
			}]
		}
	}

DELETE sessions/{code}/participants/{userId} - usecase kick out participant, leave session

"Delete participant from a session, only host, or its user"
authorization: "need to loggedIn (Bearer Token) and online"  
return: 
	status 204 "no content"

POST sessions/{code}/songs - usecase add to playlist

"Add a new song to a session"
authorization: "need to loggedIn (Bearer Token) and Online" 
body: {
	channelName: string,
	thumbnailURL: string,
	videoId:string,
	videoTitle:string,
	videoURL:string
}
return:
	status 201
	response: {
		data: {
			songId: number
		}
	}

GET sessions/{code}/songs

"Get all song based on a position from a session, need to be logged in"
authorization: "need to loggedIn (Bearer Token)" 
return:
	status 200
	response: {
		data: {
			songs : [{
				songId: number,
				channelName: string,
				thumbnailURL: string,
				videoId:string,
				videoTitle:string,
				videoURL:string,
			}]
		}
	}

PUT sessions/{code}/songs/{songId} - usecase move song to top of the playlist, move song to bottom of the playlist, move song up one song, move song down one song

"do a user action, queue up, queue down, move to top of the queue"
authorization: "need to loggedIn (Bearer Token) and Online" 
body : {
	action: "queueUp" || "queueDown" || "top" |"bottom"
}
return 
	status 200

DELETE sessions/{code}/songs/{songId} - usecase remove from playlist

"delete song from session"
authorization: "need to loggedIn (Bearer Token) and Online" 
return 
	204 "no content"

CLIENT EVENT

"player.play" Play/Pause the current song

"player.pause" Play/Pause the current song

"player.next" play the next song,

"player.previous" play the previous song

"player.jump" jump to a specific position in current song

	payload : {
		seconds: number
	}

SERVER EVENT

"participant.leave"

	payload : {
		user: {
			uid:string,
			email?:string,
			displayName?:string,
			photoURL?:string		
		}
	}

"participant.join"

	payload : {
		user: {
			uid:string,
			email?:string,
			displayName?:string,
			photoURL?:string		
		}
	}

"player.play" Play/Pause the current song

"player.pause" Play/Pause the current song

"player.next" play the next song,

"player.previous" play the previous song

"player.jump" jump to a specific position in current song

	payload : {
		seconds: number
	}

"session.host.change"

	payload : {
		newHost:  {
			uid:string,
			email?:string,
			displayName?:string,
			photoURL?:string		
		}
	}

To Be Determined Later:

• usecase log out

Handle unexpected quick disconnection / connection interuption / buffer so endSession event is closed

https://socket.io/docs/v4/connection-state-recovery#usage