By: CS2103-AY1819S1-T13-3 Since: Aug 2018 Licence: MIT

1. Introduction

The JxMusic is a music platform that lets you add to, organize and play your digital audio collection on your computer. The player is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI).

2. Quick Start

  1. Ensure you have Java version 9 or later installed in your Computer.

  2. Download the latest jxmusic.jar here.

  3. Copy the file to the folder you want to use as the home folder for your JxMusic player.

  4. Open a terminal in the folder, enter the command java -jar jxmusic.jar.

    • The command should generate a library folder next to the jar file containing several sample mp3 files.

    • Otherwise, enter unzip jxmusic.jar "library/*"

    • Alternatively, download the library.zip file and unzip it next to the jar.

    • Ensure that you have the library folder with the sample mp3 files otherwise jxmusic won’t start.

    • Then run java -jar jxmusic.jar

  5. The GUI should appear in a few seconds.

    Ui

  6. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

  7. Some example commands you can try with build-in tracks and playlists:

    • playlist list : lists all playlists

    • playlist newp/playlist1 t/Marbles : creates a new playlist named playlist1 with mp3 file Marbles to the JxMusic Player.

    • playlist playp/playlist1 : plays the playlist1

    • exit : exits the app

  8. Refer to Section 3, “Features” for details of each command.

  9. To add the new tracks to the library, add the mp3 files to the library folder.

  10. Restart the file so that your new tracks could be scanned and showed in UI.

3. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in playlist new p/PLAYLIST, PLAYLIST is a parameter which can be used as playlist new p/playlist1.

  • Items in square brackets are optional e.g stepback [s/SECONDS] can be used as stepback or as stepback s/20.

3.1. Viewing help : help

Format: help

3.2. Playing a track : play t/

Plays a track. If there is a playlist or track playing, it will be stopped and the track will be played.
Format: play t/[TRACK]

  • TRACK is an optional parameter, referring to the name of an existing track in the library folder.

  • If TRACK is not specified, the first track in the library folder sorted by file name will be played.

Examples:

  • play t/
    Plays the first track in the library folder sorted by file name if there is any.

  • play t/Some Song
    Plays the track named "Some Song" if it exists in the library folder.

3.3. Playing a playlist : play p/

Plays a playlist. Similarly to playing a track, if there is a playlist or track playing, it will be stopped and the playlist will be played.
Format: play p/[PLAYLIST]

  • PLAYLIST is an optional parameter, referring to the name of an existing playlist in the library folder.

  • If PLAYLIST is not specified, the first playlist in the library sorted by name will be played.

Examples:

  • play p/
    Plays the first playlist in the library folder if there is any.

  • play p/Favourites
    Plays the playlist named "Favourites" if it exists in the library folder.

3.4. Pausing a playing track : pause

Pauses a playing track.
Format: pause

Examples:

  • play t/Some Song
    pause
    The track is paused.

3.5. Continuing a paused track : play

Continues a paused track.
Format: play

Examples:

  • play t/Some Song
    pause
    play
    "Some Song" will continue playing from where it is paused.

3.6. Stopping a play : stop

Stops the track from playing.
Format: stop

Examples:

  • play t/Some Song
    stop
    play
    "Some song" stops playing and replays from the beginning.

3.7. Getting the duration of current playing/paused/stopped track: duration

Displays the duration of current playing/paused/stopped track.
Format: duration

  • play t/Some Song
    duration
    The duration of the "Some Song" is displayed on ResultDisplay pane.

3.8. Seeking time point : seek

Steps to the specified time point of the current track.
Format: seek d/TIME

  • TIME is in the format of [[h ]m ]s each of which represents a unit of time that will be summed up to get the time point. Only unsigend integers are allowed as time inputs.

  • Examples of valid TIME:

    • 10 (10 sec)

    • 1 59 (1 min 59 sec)

    • 100 (100 sec = 1 min 40 sec)

    • 1 100 (1 min + 100 sec = 2 min 40 sec)

    • 1 99 99 (1 hr + 99 min + 99 sec = 2 hr 40 min 39 sec)

Examples:

  • play t/Some Song
    seek d/1 10
    The track seeks to the 1 min 10 sec point and starts from there.

  • play t/Some Song
    seek d/100
    The track seeks to the 1 min 40 sec point and starts from there.

  • play t/Some Song
    seek d/200000
    If TIME is longer than the song duration, the seek command fails.

3.9. Listing all playlists : playlist list

Shows the list of all playlists in the library.
Format: playlist list

3.10. Searching for a playlist : playlist search

Searches for playlists by names.
Format: playlist search QUERY

  • QUERY is a string to be searched from the names of the playlists, which doesn’t need to be an exact match.

Examples:

  • playlist search Fav
    Searches for playlists that has Fav in their names.

3.11. Creating a playlist : playlist new

Creates a new playlist with specific tracks and saves it into the library.
Format: playlist new p/PLAYLIST [t/TRACK]…​

  • PLAYLIST refers to the playlist’s name.

  • TRACK refers to the track’s name.

Examples:

  • playlist new p/Favourites t/Some Song t/Some Song 2
    Creates a new playlist with the name Favourites and adds the tracks named Some Song and Some Song 2.

3.12. Deleting a playlist : playlist del

Removes an existing playlist from the library.
Format: playlist del INDEX

  • INDEX refers to the playlist’s index in the playlist panel.

Examples:

  • playlist del 1
    Deletes the first playlist in the panel if it exists.

3.13. Listing all tracks : track list

Shows a list of all tracks in the library.
Format: track list

3.14. Searching for a track : track search

Searches for tracks by names.
Format: track search QUERY

  • QUERY is a string to be searched from the names of the tracks, which doesn’t need to be an exact match.

Examples:

  • track search aliez
    Searches for tracks that has aliez in their names.

3.15. Adding a track into a playlist : track add

Adds a track into a playlist. Track can be chosen by using its name or its index in the track list panel.
Format: track add p/PLAYLIST [t/TRACK]…​ Format: track add p/PLAYLIST [i/INDEX]…​

  • PLAYLIST refers to an existing playlist’s name.

  • TRACK refers to the name of an existing track in the library folder.

  • INDEX refers to the index of a track in the track list panel.

Examples:

  • track add p/Favourites t/Some Song t/Some Song2
    Adds the track named "Some Song" and "Some Song2" to the "Favourites" playlist.

  • track add p/Favourites i/1 2
    Adds the first and second track in the track list panel to the "Favourites" playlist.

3.16. Deleting a track from a playlist : track del

Removes a track from a playlist. Track can is chosen by using its appeared sequence in playlist card.
Format: track del p/PLAYLIST INDEX

Track is selected by its index not its name.

  • PLAYLIST refers to an existing playlist’s name.

  • INDEX refers to the index of the track in the PLAYLIST.

Examples:

  • track del p/Favourites i/3
    Deletes the 3rd track in "Favourites" playlist.

3.17. Stepping a track : step [coming in v2.0]

Steps forward by default 10 seconds or specified time in seconds.
Format: step [s/SECONDS]

  • SECONDS is the number of seconds to step forward.

  • If SECONDS is negative, the command behaves similar to stepback.

Examples:

  • play t/Some Song
    step
    The track moves forward to 10 seconds later of the track and keeps playing.

  • play t/Some Song
    step s/100
    Stepping forward 100 seconds.

  • play t/Some Song
    stop s/-100
    Using negative value for SECONDS will apply the same behaviour as stepback. The track steps backward 100 seconds.

3.18. Stepping back : stepback [coming in v2.0]

Steps back by default 10 seconds or specified time in seconds.
Format: stepback [s/SECONDS]

  • SECONDS is the number of seconds to step backward.

  • If SECONDS is negative, the command behaves similar to step.

Examples:

  • play t/Some Song
    stepback
    The track moves backward 10 seconds earlier of the track and keeps playing. If the track has just played for less than 10 seconds, the track replays.

  • play t/Some Song
    stepback s/100
    Stepping back 100 seconds.

  • play t/Some Song
    stepback s/-100
    Using negative value for SECONDS will apply the same behaviour as step. The track steps forward 100 seconds.

3.19. Replay a track : replay [coming in v2.0]

Replays a track before the track ends to start from the beginning.
Format: replay

Examples:

  • play t/Some Song
    seek t/100
    replay
    The track plays from the beginning.

3.20. Skipping to the next track : next [coming in v2.0]

Plays the next track.
Format: next

Examples:

  • play p/Favourites
    next
    If the last track is being played, the playlist ends and stops.

  • play t/Some Song
    repeat track
    next
    “Some Song” will replay.

  • play p/Favourites
    repeat playlist
    next
    Go to the next track. Since repeat playlist is on, if it is the last track of the playlist playing, the first track of the playlist will play.

  • play p/Favourites
    shuffle
    repeat playlist
    next
    Go to the next track. Since shuffle and repeat playlist are on, if it is the last track playing, the next shuffled repeat will play.

3.21. Skipping to the previous track : prev [coming in v2.0]

Plays the previous track.
Format: prev

Examples:

  • play p/Favourites
    prev
    Plays the previous track. If the current track is first track in playlist, replays the same track since there is no previous track.

  • play t/Some Song
    repeat track
    prev
    “Some Song” will replay.

  • play p/Favourites
    repeat playlist
    prev
    Go to the previous track. Since repeat playlist is on, if it is the first track of the playlist playing, the last track of the playlist will play.

  • play p/Favourites
    shuffle
    repeat playlist
    prev
    Go to the previous track. Since shuffle and repeat playlist are on, if it is the first track playing and there was no previous track, the same track repeats.

3.22. Repeatedly playing a track : repeat track [coming in v2.0]

Switches the repeat mode to repeatedly play a single track. The command works even without any track playing. Upon running this command, any subsequent track will be played on repeat.
Format: repeat track

Examples:

  • play p/Favourites
    repeat playlist
    repeat track
    Switches to repeat track mode. The currently playing track will be on repeat.

  • repeat track
    play t/Some Song
    “Some Song” will play on repeat.

  • repeat track
    play p/Favourites
    The first track of the “Favourites” playlist will play on repeat.

3.23. Repeatedly playing a playlist : repeat playlist [coming in v2.0]

Switches the repeat mode to repeatedly play a single playlist. The command works even without any playlist playing. Upon running this command, any subsequent playlist will be played on repeat.
Format: repeat playlist

Examples:

  • play p/Favourites
    repeat track
    repeat playlist
    Switches to repeat playlist mode. “Favourites” will play on repeat.

  • repeat playlist
    play p/Favourites
    “Favourites” will play on repeat.

  • repeat playlist
    play t/Some Song
    “Some Song” will play on repeat.

3.24. Turning off repeat mode : repeat off [coming in v2.0]

Turns off the repeat mode
Format: repeat off

Examples:

  • play p/Favourites
    repeat playlist
    repeat off
    Switches off repeating mode.

3.25. Shuffling a playlist : shuffle [coming in v2.0]

Switches on shuffle mode to play tracks in random order.
Format: shuffle

  • When a playlist is in playback (either playing or paused), shuffle will put the rest of the playlist into random order.

  • shuffle will have no effect when track repeating mode is on.

Examples:

  • shuffle
    play p/Favourites
    “Favourites” will play in random order.

  • play p/Favourites
    repeat playlist
    shuffle
    Subsequent tracks will be played in random order. When all the tracks in the playlist has been played, the next repeat will be shuffled.

  • play p/Favourites
    repeat track
    shuffle
    The track being repeated will continue to play until repeat off only then subsequent tracks will play in random order from the remaining unplayed tracks in the playlist.

3.26. Turning off shuffle mode : shuffle off [coming in v2.0]

Turns off the shuffle mode
Format: shuffle off

Examples:

  • play p/Favourites
    shuffle
    shuffle off
    Switches off shuffling mode.

3.27. Clearing all entries : clear

Clears all entries from the library.
Format: clear

3.28. Exiting the program : exit

Exits the program.
Format: exit

4. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the library folder it creates with the file that contains the data of your previous library folder.

5. Command Summary

5.1. Commands for controlling playback

  • Play track : play t/[TRACK]

  • Play playlist : play p/[PLAYLIST]

  • Pause track : pause

  • Continue track : play

  • Stop playing : stop

  • Seek time point : seek d/TIME
    eg. seek d/1 10

  • Step : step [s/SECONDS]
    eg. step s/100

  • Stepback : stepback [s/SECONDS]
    eg. stepback s/100

  • Replay : replay

5.2. Commands for aiding the use of playback commands

  • Get duration : duration

5.3. Commands for controlling sequence of playback

  • Skip to next track : next

  • Skip to previous track : prev

  • Repeat track : repeat track

  • Repeat playlist : repeat playlist

  • Turn off repeat mode : repeat off

  • Shuffle playlist : shuffle

  • Turn off shuffle mode : shuffle off

5.4. Commands for managing playlists in library

  • List all playlists : playlist list

  • Search for playlist : playlist search QUERY
    eg. playlist search Fav

  • Create playlist : playlist new p/PLAYLIST [t/TRACK]…​
    eg. playlist new p/Favourites t/Some Song t/Some Song 2

  • Delete playlist : playlist del INDEX
    eg. playlist del INDEX

5.5. Commands for managing tracks in playlist

  • Add track to playlist : track add p/PLAYLIST t/TRACK
    eg. track add p/Favourites t/Some Song

  • Delete track from playlist : track del p/PLAYLIST i/INDEX
    eg. track del p/PLAYLIST i/1

  • List all tracks : track list

  • Search for tracks : track search QUERY
    eg. track search Fav