MyMusic - Checkpoint 4: Final Release Team # 4

Viktor Sjoestroem, Parker Mitchell, Jumaboev Sanjarbek Dept. Electronics and Computer Engineering

Chonnam National University Gwangju

https://github.com/vsjostro/oodp-music-player

I. Motivation

In this day and age of information and media overload, there still remains one form of media that we can fall back on to help us relax and be happy: music. Music is one of the most expressive forms of art/entertainment, a media form where everyone can find something that they like within. As avid music fans and programmers, we wanted to take on the challenge of creating a minimalist and usable music player ourselves. It is only natural that as programmers who are fans of music, we are also interested in the platform that they operate and are played on. As such, our application intends to provide a minimalistic approach to the common music player. Sometimes when listening to music using various music streaming/playing platforms, we feel that they are bloated with excessive features, making for a bad user experience.

Our application aims to provide a minimalistic approach to the common music listener. We wish to design a sleek, and simplified application that allows users to play music on their computer. With our application, the user will be able to enjoy a simple but well-functioning and understandable music listening platform on their computer. This aims to get rid of confusing and unnecessary features, and allow users to focus on what really matters: listening to their music.

II. Characteristics Related Applications Related applications include iTunes, Windows Media Player, and more. Windows media player and iTunes are applications that allow you to play various forms of media files located locally on a device, like videos and songs. Our application is similar to Windows Media Player or iTunes, where a user can play locally available music files on their computer, not stream music from a cloud platform.

Characteristics of the Target Application Our application will play music files found locally on the device this application is running on. It will have similar functionality to Windows Media Player and iTunes. However, ours will only play music and won’t offer the ability to purchase music. Key characteristics of our application include:

● Playing songs ● Pausing songs ● Skipping songs ● Adding songs from your local storage to the music player’s library ● Getting song lyrics from the online Genius music API ● Changing the volume of the music within the application ● Creating, editing, deleting playlists ● Song progress scrubbing (skipping to certain parts of a song) ● Favoriting songs ● Searching for songs/artists ● Shuffling songs ● Looping playlists

III. Function Specification Viktor

● void addSongToLibrary() ○ Adds songs to the library. The user is prompted to select a song file, then

is asked to enter song name and artist. The API will then start searching for the lyrics and artwork. After the API request is complete, all song information is stored to the database. If no internet connection is available, a default image is added as artwork.

● void addPlaylist() ○ Adds a new playlist. The user is prompted to add a name and description

of the new playlist. The description is optional, but a playlist name is mandatory. The playlist is added to the database.

● void removePlaylist() ○ Removes a playlist from the database and updates the view with the

remaining playlists. If the user tries to delete the song library or favorites playlist, the user will be notified that they cannot the selected item.

● void editPlaylist() ○ Method that asks the user if they want to edit the selected playlist name or

description. The new name/description is added to the database and the view is updated. Song library and Favorites cannot change name, but they can change description.

● void removeSong() ○ Method that removes the song that is currently selected from the selected

playlist. If the selected playlist is a user created one or the favorites, the song will be deleted from that playlist. If the selected playlist is the song library, the song will be deleted from the song library and from every playlist that contained the song.

● void updateSongTable() ○ Updates the song table whenever a song is added or removed to the

current playlist ● void playSong(Song song)

○ The method takes a song as input. The artwork and lyrics of the song will be displayed, if available. The JavaFX mediaplayer will get the path of the song file and begin playing the song. A thread is started to update the current song duration in the seekbar. When the current song duration

reaches the same value as the song length, the next song in the playlist will be played.

● void stopSong() ○ Stops the media player and sets songPlaying variable to false.

● void nextSong()

○ This method is called if the user presses the ‘next’ button or when the current song has ended. The next song in the playlist will be played. If shuffle mode is toggled, the next song will be a random song in the playlist. If loop mode is toggled and the current song is the last song in the playlist, the next song will be the first in the playlist.

● void prevSong() ○ Plays the previous song in the playlist when the user presses the ‘prev’

button ● void addSongToPlaylist()

○ The method adds a selected song to a playlist. When the “add song to playlist” menu item is selected, the user has to choose which playlist to add the song to.

● void volumeChanged() ○ This method updates the sound of the media player to the value that the

user has selected with the volume slider. ● void search()

○ This method searches for any songs or artists that match with the string that the user has entered. The song table will then display all songs that match the search. If no songs are found, the user will be notified.

Parker

● String[] getAPIDetails(String userInput) ○ This method populates an array with all the necessary APIDetails

attributes in one function, and then passes that to the constructor to be used.

● HttpResponse<String> getHTTPResponse(String userInput) ○ Gets an HttpResponse object from the Genius music API. It takes in the

given userInput string with the song title and artist name and gets the corresponding “song” object.

● JsonObject createJSONObject(HttpResponse<String> response) ○ Creates a JsonObject from the input response, so that we can parse the

JSON and retrieve the song information. ● JsonObject getSongObject(JsonObject jobject)

○ Method to get information about the song the user requested from the API response

● String extractSongTitle(JsonObject song) ○ Gets the correct/complete song title from the API response

● String extractArtistName(JsonObject song) ○ Gets the correct/complete artist name from the API response

● String extractSmallArtURL(JsonObject song) ○ Gets the url to the small album artwork from the API response

● String extractBigArtURL(JsonObject song) ○ Gets the url to the big album artwork from the API response

● String getAlbumArtPath(String songName, String artistName, String bigAlbumArtURL)

○ Method that uses the album artwork url, downloads the image to the resources/images folder, and then returns the path where the image was downloaded

● String extractLyrics(String songName, String artistName, String clientAccessToken)

○ Method that, with the help of a python script (now an executable) takes in the song and artist name and creates a text file containing the lyrics to that song. The method then returns the path where the text file is located.

IV. Requirements Req. no. Name Description Category

1 Play song The user should be able to select a song and play it Music functionality

2 Play next song after completion

The next song in the library should automatically play once the current song finishes Music functionality

3 Skip song The user should be able to skip a song Music functionality

4 Favorite Songs

The user should be able to "favorite", or "like" songs, and have those songs added to a "Favorites" playlist Playlists

5 Create playlist The user should be able to create a custom playlist and put songs in that playlist Playlists

6 Rename Playlist The user should be able to change the name of their playlists Playlists

7 Add songs to playlist The user should be able to add a song/songs to their playlists Playlists

8 Delete playlist The user should be able to delete a playlist that they have made Playlists

9 Change volume The user should be able to change the volume of their music via a control Music Functionality

10 Retrieve song information

The system should be able to retrieve song information through a RESTful API and a music information API, such as album artwork and lyrics API

11 Switch between playlists/library

The user should be able to switch between views of their playlists and the library of all songs System display

12 Add songs to library

The user should be able to add new songs to their application library from their local file system Song storage

13 Delete songs from library

The user should be able to delete unwanted songs from their music library Song storage

14 View album art of songs The music player will display album art of the current song, if available. API

15 View lyrics of current song

The music player will display lyrics of the current song, if available. API

17 Favorites playlist

When a user "favorites" a song, it should automatically be inserted into the favorites playlist Playlists

18 Editing menu

The user should be able to use a drop-down menu to activate/interact with certain features of the system, such as adding songs, deleting songs, making playlists, etc. System display

19 Scrubbing The user should be able to scrub through the song, skipping to parts within the song Music Functionality

V. Usecases

● Play a song ● Play the next available song when a song ends ● Skip a song ● Add songs to library ● Delete songs ● Search for songs ● Shuffling songs ● Looping playlists ● Display list of songs ● Searching within song ● Make playlists ● Name/rename playlists ● Add songs to playlists ● Delete songs from playlists ● Delete playlist ● Display song lyrics if available for the song ● Display album artwork if applicable ● System makes API request

Play a song

Main Path Alternate Path

1. A user wants to listen to a song

2. The user searches for and finds the song in their music library

2.1. The song is not in the user’s music library 2.2. The user adds the song to their music library

3. The user selects the song by clicking on it

with their mouse

4. The user clicks the play button

5. This click to play is captured along with the selected song and the music is played

6. The song plays its entire length and then

plays the next available song upon completion

Play the next available song when a song ends

Main Path Alternate Path

1. A song finishes playing

2. When the current time of the song is equal to the length of the song, the “next song” function will be called

3. The next song in the library will play

3.1. If the current song is the last song in the playlist, and the loop function is not toggled, the player will stop 3.2. If the current song is the last song in the playlist, and the loop function is toggled, the first song in the current playlist will play

Skip a song

Main Path Alternate Path

1. The user decides they want to play the next song, or the previous song

2. The user presses the skip button

3. Two possibilities exist: 3.1. If the user skips forward, then the

next song in the song list is retrieved

3.2. If the user skips backward, then the previous song in the song list retrieved

4. The song is retrieved and played

3.1.1. If there are no more songs to play, check if loop is toggled (refer to “Play the next available song when a song ends” 3.2.1. If there are no more songs to play (i.e. the user is playing the first song in the song list), the first song will continue to play

Add a song

Main Path Alternate Path

1. The user has a song locally stored on their computer in some location

2. The user presses the “add song” button

3. A browser window opens that allows the

user to search through their file system

4. The user navigates to their song file and selects it

5. The file extension is evaluated, and if it is

5.1. If the user selects a non-music file, an

a .mp3 or .wav then the system proceeds

6. The user types in the song and artist name

7. An API request is made to retrieve song

information

8. The song is added to the list of all songs, aka the library

error-message will pop up indicating the issue 7.1. If the API request fails, the song appearance in the library will default to the user input song and artist name, and no artwork or lyrics will be shown

Delete a song from the library

Main Path Alternate Path

1. The user selects a song in the library

2. The user clicks on “Remove”, then “Remove Song”

3. The selected song is deleted from the

library

4. The song file, album artwork and song lyrics are removed from the database (if applicable)

5. The database is reloaded to compensate

for the newly removed song

1.1. If the user doesn’t select a song and tries to click “Remove song”, a message will pop up saying that no song has been selected

Search for a song

Main Path Alternate Path

1. The user clicks on the search bar to activate a search

2. The user types in the song or artist they

are looking for

3. The user clicks “enter” and song table will display every matching result

4. The user can then click on the song to play

it or add it to a playlist

3.1. If the song or artist is not within the library, an empty table will appear

Shuffling Songs

Main Path Alternate Path

1. The user selects the shuffle toggle button from the bottom menu bar

2. A random song is selected from the current

playlist

3. The randomly selected song will be played once the current song ends or the user skips the current song

Looping playlists

Main Path Alternate Path

1. The user has a playlist open and wants to loop it

2. The user presses the loop toggle button

3. Once the current playlist finishes playing all

the songs, the player will return to the beginning of the playlist and play the songs starting from there Searching within song

Main Path Alternate Path

1. A song is playing

2. The user presses on the song progress bar and the music player will jump to that part of the song (the percentage of the progress bar is equal to the percentage of the song duration)

1.1 If a song is not playing, then the user cannot search within a song

Make a playlist

Main Path Alternate Path

1. User presses a “add playlist” button from menu

2. Input prompt opens and the user inputs a name for the playlist

3. Another prompt opens and the user writes a description

4. The playlist is added to the music player

2.1 If the user doesn’t set a name for the playlist, the user will be prompted to enter a name in order to create playlist 3.1 If the user doesn’t write a description, the description will remain empty

Rename a playlist

Main Path Alternate Path

1. The user selects the playlist they want to rename

2. The user selects “edit” then “edit playlist”,

then “name”

3. A window opens allowing the user to enter

in the new name

4. The new name is assigned to the playlist and displayed

2.2. If the user tries to rename the Library or Favorites pages, a message appears saying they cannot edit these names

Add songs to a playlist

Main Path Alternate Path

1. The user wants to add a song to a playlist

2. The user selects the song they want to add

3. The user presses “Add” then “Add song to

playlist”

4. A window appears showing the playlists the song can be added to

5. The user adds the song to one of their

custom playlists or to the “favorites” playlist

6. The song is added to the playlist

2.1. If the user presses “add song to playlist” before a song is selected, a message will appear telling the user to first select a song

Delete songs from a playlist

Main Path Alternate Path

1. The user opens a playlist

2. The user selects a song they want to

2.1. If the user tries to press remove before

remove

3. The user then presses “remove” then “remove song”

4. The song is removed from the playlist, and

using the ID of the playlist and the ID of the song, it is removed from the database

5. The database is updated to reflect the

changes

selecting a song, then a message appears telling them to select a song first

Delete playlist

Main Path Alternate Path

1. The user selects which playlist to remove

2. The user presses a “delete playlist” button

3. A dialog box asks the user to confirm the removal of the playlist

4. The playlist is removed

4.1 If user presses “cancel” or exits the dialog box, the playlist is not removed

Display list of songs

Main Path Alternate Path

1. The user opens the music library 1.1. The user selects a different playlist, and the table of songs specific to that playlist are displayed

Display song lyrics if available for the song

Main Path Alternate Path

1. The user plays a song

2. The lyrics for the song are retrieved from the database

3. The “lyric” window opens, displaying all the lyrics to the song, where the user can scroll through the song lyrics

2.1. If the song lyrics were not available from the API when the song was added, then no lyrics will appear in the lyrics window

Retrieve/Display album artwork if applicable

Main Path Alternate Path

1. A song is played

2. The application retrieves album artwork from the database

3. If a song object has valid artwork, then the artwork is displayed to the main screen

2.1. If the song artwork was not available from the API when the song was added, then no artwork will appear in the artwork window

System makes API request

Main Path Alternate Path

1. User adds a song to library

2. User enters song and artist name

3. System initiates API request

4. The system tries to get an HTTPResponse

from the API

5. The response status code is captured and evaluated

6. The response code is 200, which means

the request was successful

7. The information is sent back to the system and stored within the song object

6.1. The response code is not 200, indicating the request failed 6.1.2. ‘Null’ is returned from the request, and the song object is filled with ‘null’ 6.1.3. Album artwork and lyrics will not be displayed

VI. Usecase Diagram Our diagram became quite complex, as we made our usecase diagram with every usecase in mind. As such, we have made four usecase diagrams. Since there are 3 blurred categories that the usecases can fall into (music funcitonality, playlist functionality, and song library functionality), we have made diagrams for each of these. These diagrams are more detailed for each section than the usecase diagram that encompasses all of them. The final usecase diagram is a more simplified one that covers every usecase.

Entire usecase diagram

Music functionality usecase diagram

Playlist functionality usecase diagram

Song library functionality usecase diagram

VII. Sequence Diagrams

VIII. User Interface Designs Mock-up

Actual Application

IX. Class Diagram

X. Screenshot of API manual

Method summary of MusicPlayerDatabase

XI. Screenshot of Application Demo Here is a picture of a moderately filled out music library. You can see the songs, the additional playlists, and the lyrics to the song.

Here is a picture showing the search functionality. I typed in “last dinos” and the song from Last Dinosaurs appeared in the window.

XII. Work Distribution Viktor I worked on the main functionality of the application, the GUI, database integration, and connecting the API results to the songs. Classes done: MusicPlayer, MusicPlayerView, MusicPlayerController, MusicPlayerDatabase, Song, Playlist. Lines of code: 1735 Parker As you can see above, our work distribution was largely based on function distribution. At a higher level, I was in charge of all API related tasks. I developed the APIDetails class which handled retrieving song information from the internet. I also developed the procedure to download and save song lyrics and album artwork from the internet so that the paths to their files could be stored in the databases for preservation. I also developed a python script (which we turned into an executable so that we could launch it as a new process) that utilizes a Genius wrapper to get the lyrics of a song from the Genius website. Total lines of code: 460 (including python script, but not including code written to test features)