By: Team CS2103T-F13-4 Since: Sept 2019 Licence: MIT

1. Introduction

Tired of using multiple sources on the internet to keep track of all your movies and tv shows that you want to watch? EzWatchlist is a solution to your entertainment problems!

EzWatchList is an application is for cinephiles who prefer to use a desktop for managing movies and tv shows. More importantly, EzWatchList 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).

  1. If you can type fast, EzWatchList works faster than traditional GUI apps.

  2. Keep track of movies and tv shows that you plan to watch or have watched.

  3. Access quick information about your favourite shows through our online database.

  4. Discover your personal movie habits, with our statistics page.

  5. Can’t find any good shows to watch? We will give you recommendations on what to watch based on your EzWatchlist usage.

Already interested? Jump to Section 2, “Quick Start” to quickly get started. Enjoy!

1.1. What else does EzWatchlist offer you?

  • Integration with an online database of shows, allowing you to search and get information about shows.

  • Functions and works without internet.

  • No installations required.

  • Auto-saves all data.

  • Dual-purpose interface, command line interface for those who prefer typing and graphical for those who prefer using a mouse.

1.2. How do I use EzWatchlist?

EzWatchlist was built with ease in mind hence our interface reflects this design philosophy.

Ui
Figure 1. EzWatchlist’s graphical interface

EzWatchlist is split into four different pages:

  1. Watchlist, where shows you want to watch are added.

  2. Watchedlist, where shows you have watched are located.

  3. Search, where you search for shows both online and offline.

  4. Statistics, where information about your viewing habits are shown.

This pages are represented by the sidebar panel shown visibly in Figure 1. Navigate between pages by using keyboard shortcuts 1, 2, 3, 4 respectively or through a button press on the graphical interface.

1.2.2. Interaction

commandline
Figure 2. EzWatchlist’s command line interface.

EzWatchlist uses Commands entered through the command line interface in figure 2 to interact with the application. Typing a command into the interface and entering it (by pressing Enter or clicking Go!) is the main way of interaction in the application. The following is an example of adding a movie into your watch list:

Steps to quickly add a movie

  • search n/ip man : Searched for movie named ip man in the offline and online database which will bring you to the search page automatically.

searchIpMan
Figure 3. Search page for "ip man".

  • add 2 : Adds "Ip Man" (2008) shown in entry 2 in Figure 3 into your watchlist.

watchlistIpMan
Figure 4. Watchlist page after adding the entry.

And that’s it. Our quick start guide will guide you to set up our application. If you like to learn more head straight into our features guide for a run down on our major features, or go to our commands guide to learn more on our commands. Otherwise, if you’re a developer and are interested to understand how each of our features were implemented, our developer guide breaks down each of our major components.

What are you waiting for? Start using EzWatchlist now!

2. Quick Start

  1. Ensure you have Java 11 or above installed in your Computer.

  2. Download the latest ezwatchlist.jar here.

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

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

  5. Interact with EzWatchlist with commands in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

  6. Some example commands you can try:

    • addn/Titanic t/movie : adds the movie named Titanic to the Watchlist.

    • delete3 : deletes the 3rd movie shown in either watch or watched page.

    • exit : exits the app

  7. Refer to Section 3.3, “User Commands” for details of each command.

3. Features

3.1. User-Interface

The UI consists of three parts: sidebar, command bar and various pages that could appear in the main panel. The following sections introduce these UI parts in details.

EzWatchlist gives users the ability to navigate easily through the Watchlist, Watchedlist, Search page and Statistics pages through the use of the side bar at the left of the main page of the graphical user interface. Moreover, keyboard shortcuts 1, 2, 3, 4 bring you to each page respectively.

Note: If user has selected the command box, type 1, 2, 3, 4 and enter to bring you to each page respectively.

3.1.2. Command bar

Users input commands in the command bar and any feedback will be displayed below the text area of command bar.

3.1.3. Watchlist Page

The watchlist page is the default page that is opened upon start-up of EzWatchlist. It shows the user’s unwatched movies and television series. The user can navigate to this list by clicking the “Watchlist” tab on the side bar or by using the keyboard short-cut 1.

Characteristics of the watchlist page:

  • Movie/TV show poster

  • Name of show

  • Genres

  • Actors

  • Description of the show

  • Running Time

  • Last watched episode (For TV series that have been updated using the watch command)

  • Checkbox to indicate if the show has been watched

Ui
Figure 5. Main page of the UI: watchlist page

3.1.4. Watched List Page

The user has the option to view the list of shows that have been marked as watched in the watched list. The user can navigate to this list by clicking the “Watched” tab on the side bar or by using the keyboard short-cut 2.

3.1.5. Search Page

The user can navigate to the search page to find a specific movie or television by searching for its name. The user can navigate to this list by clicking the “Search” tab on the side bar or by using the keyboard short-cut 3.

The search function may require some time to load the data from the API.
search page
Figure 6. Main page of the UI: search page

3.1.6. Statistics Page

The user can navigate to the statistics page to find a summary of his watching habits, preferences and history according to what is present in his lists. Examples include:

  • Movies added but might have forgotten to watch

  • Up to 3 most favourite genres

  • Recommendations

The user can navigate to this list by clicking the “Statistics” tab on the side bar or by using the keyboard short-cut 4.

The statistics function may require some time to load the data from the API the first time you start the application, or after you have made changes to your watchlist.
statistics page
Figure 7. Main page of the UI: statistics page

3.1.7. Details Page (Coming in v2.0)

Upon clicking a movie or tv show title, a pop-up window will emerge, with a detailed view of the movie or tv show. This page provides the user with more information about the show, like the year, cast and ratings. The user also has the ability to edit the details here.

3.2. Advanced Features

3.2.1. Parsing of Movie and Tv Show Information

In EzWatchlist, an online database is accessed so that all the information about your favourite Movies and Television Shows is updated, informative, and concise. What this means for you is that:

  • Posters of your EzWatchlist shows, can be displayed in EzWatchlist’s sleek dark interface.

  • Moreover, your offline shows can be synced with this database allowing the application to fill in the minor details for you.

  • Unsure of what actors played in your favourite movie? EzWatchlist will find that information for you.

You don’t need to do anything other than be connected to the internet. It is that easy!

3.2.2. Movie and Tv Show Recommendations

EzWatchlist has the ability to recommend Movies and TvShows to you based on your EzWatchlist usage. EzWatchlist will create your own personalized recommendations for you.

How to get your recommendations

  1. First, make sure that you have added at least one (offline or online) into EzWatchlist so that we can use that to generate recommendations for you.

  2. Then head to the Statistics Page by clicking 4 or pressing the Statistics. button on the in the interface.

  3. Now your recommendations as seen in Figure 5 will be shown prominently on the bottom of the Statistics Page, with movie recommendations on the left, and Tv Series recommendations on the right.

recommendations
Figure 8. Recommendations shown in the Statistics Page.

Excited? Enter your statistics page to get started on your recommendations. You might just find your next favourite!

3.2.3. Auto-Correct (Coming in v2.0)

EzWatchlist aims to provide a smooth experience for our typing users. All typing in EzWatchlist will be automatically corrected for you when typing in your commands.

Say goodbye to typing errors!

3.3. User Commands

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add n/SHOW_NAME t/SHOW_TYPE, SHOW_NAME and SHOW_TYPE are parameters which can be used as add n/The Angry Birds Movie 2 t/movie.

  • Items in square brackets are optional e.g n/SHOW_NAME t/SHOW_TYPE [s/DESCRIPTION] can be used as n/The Angry Birds Movie t/movie 2 d/Oscar-worthy or as n/The Angry Birds Movie t/movie.

  • Items with …​ after them can be used multiple times including zero times e.g. [a/ACTOR]…​ can be used as   (i.e. 0 times), a/Leonardo Di Carpio, a/Leonardo Di Carpio a/Christian Bale etc.

  • Parameters can be in any order e.g. if the command specifies n/SHOW_NAME t/SHOW_TYPE, t/SHOW_TYPE n/SHOW_NAME is also acceptable.

3.3.1. View help : help

Format: help

3.3.2. Add a show: add

User can add a show they are interested to watch in the watchlist by using
add command.

add can only work in Watchlist page and Watched page.

Format: add n/SHOW_NAME t/SHOW_TYPE [d/DATE_OF_RELEASE] [w/WATCHED] [r/RUNNING_TIME] [s/DESCRIPTION] [a/ACTOR_NAME]…​

  • Only SHOW_NAME, SHOW_TYPE are compulsory fields. Rest is optional.

  • SHOW_TYPE can only be 'movie' or 'tv'

  • WATCHED can only be 'true' or 'false'

  • SHOW_NAME, DESCRIPTION and ACTOR_NAME can be any words

  • DATE_OF_RELEASE must be in the format dd/MM/yyyy

  • RUNNING_TIME can be any number above 0

  • ACTOR_NAME can be more than one.

Examples:

  • add n/Titanic t/movie

  • add n/Friends t/tv

  • add n/John Wick t/movie d/24/10/014 w/false r/101 s/An ex-hit-man comes out of retirement to track down the gangsters that killed his dog and took everything from him. a/Keanu Reeves

  • add n/Joker t/movie d/3/10/2019 w/false r/122 s/In Gotham City, mentally-troubled comedian Arthur Fleck is disregarded and mistreated by society. He then embarks on a downward spiral of revolution and bloody crime. This path brings him face-to-face with his alter-ego: "The Joker". a/Joaquin Phoenix

3.3.3. Adding a show from search result page: add

This is an extension to the add feature. After user has searched from the show, user can add a show found in the search result page into their watchlist.

Format: add INDEX

INDEX is a positive integer and is limited to the number of shows found in search result page.

This add command can only be used if user is currently at search page, and has already searched for show using the search online command.

Example Usage:

Pre-condition: User has already searched for a show using search online command.

Step 1. User click (or use keyboard 3 key) on search page. User then input add 1 on command box.

add2

Step 2. User click (or press keyboard 1 key) on watch list page. User will see Joker movie added to watch list.

add3

3.3.4. Clear the WatchList: clear

Clear the WatchList
Format: clear

3.3.5. Mark/Unmark as watched : watch

To mark an unwatched show in the watchlist as watched, use the command format listed below.
Format: watch INDEX [e/EPISODE_NUMBER] [s/SEASON_NUMBER]

Before marking TV show’s seasons and episodes, you may want to use the sync command to ensure that the TV show’s season and episode details are up to date.

Example Usage:

  1. You want to mark "The Office" in the watchlist page as watched. Navigate to the watchlist by clicking on the watchlist tab or hitting the keyboard shortcut 1.

WatchTheOffice
Figure 9. Viewing an unmarked show

  1. Enter watch 1 into the command box in the watchlist tab.

Watch
Figure 10. Entering the watch command

  1. You may now view the show under the watched tab by clicking the watched tab or hitting the keyboard shortcut 2.

WatchedTheOffice
Figure 11. Viewing the newly marked show

Alternatively, you may click on the watched checkbox to toggle between whether a show is watched as indicated by the red arrow in the image below.

TheOfficeWatchCommand
Figure 12. Marking a show using the checkbox

  • The index refers to the index number shown in the displayed watchlist. The index must be a positive integer 1, 2, 3, …​

  • Any number of the optional fields may be provided.

  • Having only the index of the show will mark/unmark the show as watched.

  • Having the index and the episode number of the show will update the cumulative number of episodes of the show that are watched.

  • Having the index and the season number of the show will update the cumulative number of seasons of the show that are watched.

  • Having the index, season number and the episode number of the show will update the last watched episode to be the indicated episode of the indicated season of the show.

Using the watch command on an already watched show will un-mark the show as watched.
watch would only work in Watchlist page and Watched page.

Examples:

  • watch 1
    Marks/un-marks the first show of the list as watched.

  • watch 2 e/20
    Marks the first 20 episodes of the second show of the list as watched.

  • watch 2 s/5
    Marks all episodes of the first 5 seasons of the second show as watched.

  • watch 3 s/5 e/2
    Marks all episodes up to and including the second episode of the fifth season of the third show in the list as watched.

3.3.6. Edit a show’s details : edit

Edits an existing show in the list
Format: edit INDEX [n/SHOW_NAME] [d/DATE_OF_RELEASE] [w/WATCHED] [r/RUNNING_TIME] [s/DESCRIPTION] [a/ACTOR]…​

  • Edits the show at the specified INDEX. The index refers to the index number shown in the displayed watchlist. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing actors, the existing actors of the show will be removed i.e adding of actors is not cumulative.

  • You can remove all the show’s actors by typing a/ without specifying any actors after it.

edit would only work in Watchlist page and Watched page.

Examples:

  • edit 1 n/Joker a/Joaquin Phoenix
    Edits the name and actor name of the 1st show in the list to be Joker and Joaquin Phoenix respectively.

  • edit 2 a/
    Clears all existing actors of the 2nd show in the list.

3.3.7. Search for a show: search

Searches for shows whose names contain any of the given keywords from the online database, unless specified to be from the watchlist or watched list.

Format:

  • by name:
    search n/SHOW_NAME…​ [g/GENRE]…​ [a/ACTOR_NAME]…​ [o/FROM_ONLINE] [t/SHOW_TYPE] [w/HAS_WATCHED]

  • by genre:
    search g/GENRE…​ [n/SHOW_NAME]…​ [a/ACTOR_NAME]…​ [o/FROM_ONLINE] [t/SHOW_TYPE] [w/HAS_WATCHED]

  • by actor (from watchlist only):
    search a/ACTOR_NAME…​ [n/SHOW_NAME]…​ [g/GENRE]…​ [o/FROM_ONLINE] [t/SHOW_TYPE] [w/HAS_WATCHED]

    • SHOW_NAME, GENRE, ACTOR_NAME can be any words, as long as it does not contain /.

    • FROM_ONLINE and HAS_WATCHED can only be yes, true, no or false.

    • SHOW_TYPE can only be movie or tv.

Special commands to take note of:
o/no: to search from watchlist or watched list
o/no w/no: to search from watchlist only
o/no w/yes: to search from watched list only
When searching based on genre online, only movies will be searched.

For [o/FROM_ONLINE] [t/SHOW_TYPE] [w/HAS_WATCHED], if multiple entries are entered, only the last would be considered. e.g. "search n/Avengers t/movie t/tv" will be interpreted as "search n/Avengers t/tv".

Space between prefix and slash is not acceptable. e.g. "n /Avengers" will throw an error.
Space after prefix is acceptable. e.g. "n/ Avengers" will be interpreted as "n/Avengers".
The search is case insensitive. e.g "avengers" will match "Avengers".
The order of the keywords matter. e.g. "Chris Evans" will not match "Evans Chris".
Not only full words will be matched. e.g. "Joke" will also match with "Joker".


Example Usage:
You may want to search for movies named "Avengers" and also movies with an actor named "Tom". As shown below, assume that your watchlist only has a movie "Avengers: Endgame" that you have watched.

watchedPageWithAvengerEndgame
Figure 13. Current Watched Page with a movie watched "Avengers: Endgame"


  1. Navigate to the Search page by one of the following ways:

    • clicking on the search tab

    • hitting the keyboard shortcut 3

    • typing 3 in the command box and pressing enter

    • typing search in the command box and pressing enter as shown in the figure below

searchCommand
Figure 14. Entering of the search command


After you have entered the command, you will be led to the Search page as shown below.

emptySearchPage
Figure 15. Graphical Interface of the Search Page
You may skip Step 1 as you will be automatically be navigated to the Search Page when you key in any valid search command, such as the one in Step 2 below.


  1. Enters search n/Avengers a/Tom t/movie into the command box in the Search Page as shown below.

searchAvengerUserInput
Figure 16. Entering of the search command to search for shows


Press enter after entering the information shown above and wait for the information to load.

searchPageLoadingScreen
Figure 17. Loading Screen of the Search page

The loading page as shown above will appear while EzWatchlist searches for your shows.

You can go to the other pages in the mean time. Do allow some time for the search to load.


  1. Search page shows the list of shows based on search n/Avengers a/Tom t/movie.


Scenario A: You are offline
Only movies from the watchlist or offline database with the movie name "Avengers" or actor name "Tom" will be shown, as seen in the figure below.

searchPageSearchedForAvengersWhenOffline
Figure 18. Search Page showing the search results when offline


Scenario B: You are online
Only movies from the online database with the movie name "Avengers" or actor name "Tom" will be shown, as seen in the figure below.

searchPageSearchedForAvengersWhenOnline
Figure 19. Search Page showing the search results when online


Examples:

  • By name:

    • search n/Joker o/no
      Returns shows with the name "Joker" within the watchlist

    • search n/Avengers g/Science Fiction t/movie n/Spiderman
      (If online) Returns movies from the online database with the name "Avenger" or "Spiderman" and movies with the genre "Science Fiction"
      (If offline) Returns movies from the internal database, watchlist and watched-list with the name "Avenger" or "Spiderman" and movies with the genre "Science Fiction"

  • By genre:

    • search g/Action t/movie
      (If online) Returns movies from the online database with the genre "Action"
      (If offline) Returns movies from the internal database, watchlist and watched-list with the genre "Action"

  • By actor: (from watchlist only)

    • search a/Tom o/no w/no
      Returns shows within the watchlist with actor named "Tom"

3.3.8. Synchronise user's show data: sync

If user has lack of information about a certain show in their watch list, User can use sync command. Synchronise, sync, command will transfer all the information about a certain show (for example: show A) found in search result page with a show (for example: show A') that has the same name as Show A found in watch list.

Note:

  1. The show in the watch list must have at least a name and type.

  2. Names are not-case sensitive.

  3. Sync will WRITE OVER all the information of show with same name found in watchlist.

Format: sync INDEX

INDEX is a positive integer and is limited to the number of shows found in search result page.

Example Usage

Scenario 1: User has already input 'Titanic' show into watchlist manually.

Sync1

Step 1. User searches for Titanic show in search page.

Step 2. Titanic result page will be displayed. User input sync 2 to synchronise movie at index 2 of the list with a movie of same name found in watchlist.

Sync5

Step 3. Go to watchlist. New information of Titanic in watchlist will be displayed.

Sync6

Scenario 2. User has not input Titanic show into watchlist manually.

Sync21

Step 1. Similar to scenario 1, user searches for Titanic show in search page.

Sync4

Step 2. Titanic result page will be displayed. If user were to sync any index, error message will be displayed because there is no show of similar name found in watch list.

Sync22

Step 3. User can choose to use add 1 command to add show of index 1 found in search result page.

Sync23

3.3.9. Deleting a show : delete

Deletes the specified show from the watchlist.
Format: delete INDEX

  • Deletes the show at the specified INDEX.

  • The index refers to the index number shown in the displayed watchlist.

  • The index must be a positive integer 1, 2, 3, …​

delete would only work in Watchlist page and Watched page.

Examples:

  • delete 2
    Deletes the 2nd show in the watchlist.

  • search Angry
    delete 1
    Deletes the 1st show in the results of the search command.

3.3.10. Exiting the program : exit

Exits the program.
Format: exit

3.3.11. Saving the data

EzWatchlist’s data are saved in the hard disk automatically after any command that changes the data.
There is no need to save manually.

4. FAQ

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

5. Command Summary

  • Add : add n/SHOW_NAME t/SHOW_TYPE [d/DATE_OF_RELEASE] [w/WATCHED] [r/RUNNING_TIME] [s/DESCRIPTION] [a/ACTOR_NAME]
    e.g. add n/John Wick t/movie d/24 OCTOBER 2014 w/false r/101 s/An ex-hit-man comes out of retirement to track down the gangsters that killed his dog and took everything from him. a/Keanu Reeves

  • Add from search result page : add INDEX
    e.g. add 1

  • Sync : sync INDEX
    e.g. sync 2

  • Clear : clear

  • Watch : watch INDEX [e/EPISODE_NUMBER] [s/SEASON_NUMBER]

  • Delete : delete INDEX
    e.g. delete 3

  • Edit : edit INDEX [n/SHOW_NAME] [d/DATE_OF_RELEASE] [w/WATCHED] [r/RUNNING_TIME] [s/DESCRIPTION] [a/ACTOR]…​
    e.g. edit 2 n/John Wick a/Johnny Depp

  • Search

    • by name : search n/SHOW_NAME…​ [g/GENRE]…​ [a/ACTOR_NAME]…​ [o/FROM_ONLINE] [t/TYPE] [w/IS_WATCH]
      e.g. search n/Joker o/no searches for shows with the name 'Joker' within the watchlist

    • by genre : search g/GENRE…​ [n/SHOW_NAME]…​ [a/ACTOR_NAME]…​ [o/FROM_ONLINE] [t/TYPE] [w/IS_WATCH]
      e.g. search g/Action t/movie searches for movies from the online database with the genre 'Action'

    • by actor from watchlist : search a/ACTOR_NAME…​ [n/SHOW_NAME]…​ [g/GENRE]…​ [o/FROM_ONLINE] [t/TYPE] [w/IS_WATCH]
      e.g. search a/Tom searches from shows within the watchlist with actor named 'Tom'

  • Exit : exit

  • Help : help