1. H.A.M.L. User Manual (CSE 412 Group Project)

1. H.A.M.L. User Manual (CSE 412 Group Project)

1.1. Setup

H.A.M.L. is supported on Linux and macOS, it does not support windows.

Interested in what the other shellscripts do?

In order to get started clone this repository:

git clone https://github.com/EthanG45/CSE412-HAML-Project.git

1.1.1. Step 1 - Python Dependencies

H.A.M.L. requires python3 and pip

H.A.M.L. requires the following Python dependencies:

PySimpleGUI
matplotlib
faker
psycopg2
psycopg2-binary

If you are on Linux, you need to install the following package:

sudo apt-get install python3-tk

If you are on macOS, you need to install the following package with homebrew (also get homebrew if you don't have it). You also have to recompile Python with tcl-tk headers:

brew install tcl-tk

Note we are assuming you are using pyenv for recompiling Python.

latestTclTk='8.6'

latestPython=`pyenv install --list | sed -e 's/^[[:space:]]*//' | grep --regexp '^[0-9]\.[0-9][\.0-9]*$' | (gsort --version-sort 2>/dev/null || sort --version-sort) | tail -n 1`

PYTHON_CONFIGURE_OPTS="--with-tcltk-includes='-I/usr/local/opt/tcl-tk/include' --with-tcltk-libs='-L/usr/local/opt/tcl-tk/lib -ltcl${latestTclTk} -ltk${latestTclTk}'"

pyenv install ${latestPython}

pyenv global ${latestPython}

Reference for this tcl-tk issue on macOS.

To download all the dependencies, simply run scripts/install.py using the command:

python3 scripts/install.py

1.1.2. Step 2 - PostgreSQL setup

H.A.M.L. relies on your machine having PostgreSQL. Follow their setup process to get it.

The following exports are expected in your terminal for the duration of using H.A.M.L.

export PATH="/Library/PostgreSQL/12/bin:${PATH}" # mac
export PATH="/usr/lib/postgresql/12/bin:${PATH}" # linux

export PGPORT=8888   # e.g. 8888. It sets the PORT to be this number 8888 which will be used by PostgreSQL
export PGHOST=/tmp    # sets the directory for the socket files

If you intend to use H.A.M.L. in more than one terminal session, then add the exports to your .bashrc or .zshrc. If not, then make sure to run the exports each time you use H.A.M.L. in your terminal.

1.1.3. Step 3 - Database setup

Run the ./scripts/init_db.sh command. This will setup the H.A.M.L. database on your machine. It must be run from the root directory.

./scripts/init_db.sh

1.1.4. Step 4 - Run the app

Run the app using the following gui.py file:

python3 src/gui.py

1.1.5. Already have the app setup?

Just run ./scripts/start_db.sh to start the database and ./scripts/stop_db.sh to stop it when you are done using the app.

./scripts/start_db.sh
./scripts/stop_db.sh

1.1.6. Done with H.A.M.L.?

Just run ./scripts/rm_db.sh to remove the database and delete this repository.

./scripts/rm_db.sh

1.2. Main Screen

HAML has 5 main tabs. They are:

Library
Add
Search
Insights
Feeling Lucky
Theme

1.3. 1.2 Library

Library is a group of tabs:

Song
Album
Artist
Record Label

1.3.1. `Song Library`

Displays all songs from the song table in our database. It allows a user to select a table element and either update, delete or rate a song using a slider.

1.3.2. `Album Library`

Displays all albums from the album table in our database. It allows a user to select a table element and either update or delete an album.

1.3.3. `Artist Library`

Displays all artists from the artist table in our database. It allows a user to select a table element and either update or delete an artist.

1.3.4. `Record Label Library`

Displays all record labels from the record label table in our database. It allows a user to select a table element and either update or delete a record label.

1.4. Add

Add is a group of tabs:

Song
Album
Artist
Record Label

1.4.1. `Add Song`

Add song allows a user to input a song title, genre, album title and release year. The release year uses a drop down menu for selection.

1.4.2. `Add Album`

Add album allows a user to input an album title and include the first song, which will contain the same elements as the add song function.

1.4.3. `Add Artist`

Add artist allows a user to input an artist name, age, which uses a slider, instrument, which uses a list box, and band name. It then asks what album the artist makes and requires the user to add an album using the same parameters from add album.

1.4.4. 1.3.4 `Add Record Label`

Add record label allows a user to input a company name, label location, and what album the record label published and asks for the title using a list box. It also asks for the date established, which is entered using a calendar GUI, or you can manually enter the data in the format YYYY-MM-DD.

1.5. Search

Search is a tab group that contains tabs:

Song
Album
Artist
Band
Record Label

1.5.1. `Search Song`

Asks the user for the song name and has a button called search and once pressed, will fill a table with all of the returned results with respect to the song name. There is also a rating slider to add a rating to the song and a delete button to delete the song and an update button that can be used to update the song details.

1.5.2. `Search Album`

Asks the user for the album title and has a button called search and once pressed, will fill a table with all of the returned results with respect to the album title. There are also delete and update buttons to delete the album and to update the album details.

1.5.3. `Search Artist`

Asks the user for the artist name and has a button called search and once pressed, will fill a table with all of the returned results with respect to the artist title. There are also delete and update buttons to delete the artist and to update the artist details.

1.5.4. `Search Band`

Asks the user for the band name and has a button called search and once pressed, will fill a table with all of the returned results with respect to the band name. There are also delete and update buttons to delete the band and to update the band details.

1.5.5. `Search Record Label`

Asks the user for the record label name and has a button called search and once pressed, will fill a table with all of the returned results with respect to the record label name. There are also delete and update buttons to delete the record label and to update the record label details.

1.6. Insights

Insights is a Group of Tabs:

Top 10 Songs
Genre Graph Song By User Rating
Top 10 Albums
Top 10 Worst Songs
Top 10 Worst Albums

1.6.1. `Top 10 Songs`

Display the top 10 songs in the database by overall average rating in one table and by user rating in another table.

1.6.2. `Graph Genre Song By User Rating`

Displays a distribution of genres by user rating.

1.6.3. `Top 10 Albums`

Display the top 10 albums in the database by overall average rating in one table and by user rating in another table.

1.6.4. `Top 10 Worst Songs`

Display the top 10 worst songs in the database by overall average rating in one table and by user rating in another table.

1.6.5. `Top 10 Worst Albums`

Display the top 10 worst albums in the database by overall average rating in one table and by user rating in another table.

1.7. Feeling Lucky

Feeling Lucky is a group of tabs:

Artists
Songs
Record Label by Album
Record Label by Song
Record Label by Band
Record Label by Instrument

1.7.1. `Artists`

Searches artist by song name and returns a table of artists by their song name.

1.7.2. `Songs`

Searches songs by year using a list box and artist using a drop down list and returns a table of information regarding the artists and songs entered.

1.7.3. `Record Label by Album`

Searches record label details by album. It uses a list box filled with all the album names for user selection.

1.7.4. `Record Label by Song`

Searches record label details by song. It uses a list box filled with all the song names for user selection.

1.7.5. `Record Label by Band`

Searches record label details by band. It uses a list box filled with all the band names for user selection.

1.7.6. `Record Label by Instrument`

Searches record label details by instrument. It uses a list box filled with all the instrument names for user selection.

1.8. Theme

1.8.1. `Theme`

Allows the user to select a theme from a list box and will change the graphical theme to match the theme selected.

1.9. Contribution

Note on the commit history: the app was mostly programmed using VSCode LiveShare using Ethan's machine. This means the commit history shows only Ethan contributing code, but everyone did.

General things everyone did roughly equally
- Fixed bugs together (after introducing bugs).
- Debug issues with the gui/sql, generally the ones they introduced sometimes just getting pulled in regardless to fix them even if they didn’t create them.
- Documented features and what they generally worked on.
Arvin Arasteh
- Implemented the initial database connection to the program’s frontend and implemented most of the SQL queries and functions
- Helped with the GUI’s different tabs, and created different graphs for the program
Aurelio Villalobos
- Wrote SQL queries to interact with the GUI.
- Wrote the user manual to explain how to use the program.
Joshua Webber
- First to start the gui and implement most of the tabs not all features within each tab though, but still many aspects of them.
- Edit the SQL functions for the implementation in the GUI
Ethan Gilchrist
- Worked on the GUI and a lot of the different tabs. Did most the work on the feeling lucky and insights tab. Helped on all other tabs.
- Helped with some of the SQL functions. Made and edited the video.
Jonathan Monk
- Wrote and helped on a lot of SQL functions.
- Made edits to the GUI.
Ramón Deniz
- Wrote custom GUI windows and components
- Debugged main issues revolving around the GUI

1.10. Developed using PySimpleGUI

https://pypi.org/project/PySimpleGUI/

1.11. Known Bugs

Insights Graphs don't auto update. This is an issue inherent to the way PySimpleGUI and MatPlotLib are integrated with one another. It's very difficult to redraw the graphs without causing excessive CPU and memory load. We were unable to fix this within the scope of the project.
Focus Issues. The macOS version of PySimpleGUI currently has an issue where pop-up windows break the focus from the main window and prevent it from returning. There are some hacky fixes to this, but certain built-in elements can't be prevented from having this issue. One instance is the use of the built-in PySimpleGUI calendar in one of our addition tabs. It prevents focus from returning to the main app. This bug is not present on Linux.

1.12. Repository Scripts

1.12.1. `./scripts/clean_db.sh`

Drops the sql tables from your local version of the database.

./scripts/clean_db.sh

1.12.2. `./scripts/demo.sh`

Runs a basic demo test of the database. Output is stored in the folder output

./scripts/demo.sh

1.12.3. `./scripts/enter_db.sh`

Very lazy script that just enters you into the PostgreSQL command line.

./scripts/enter_db.sh

1.12.4. `./scripts/init_db.sh`

Creates the H.A.M.L. database on your machine.

./scripts/init_db.sh

1.12.5. `python scripts/install.py`

Downloads the necessary packages to your machine.

python3 scripts/install.py

1.12.6. `./scripts/refresh_db.sh`

Refreshes the database by regenerating the PostgreSQL tables.

./scripts/refresh_db.sh

1.12.7. `./scripts/rm_db.sh`

Remove databases entirely from your local machine.

./scripts/rm_db.sh

1.12.8. `./scripts/start_db.sh`

Lazy script that starts the PostgreSQL database on your machine.

./scripts/start_db.sh

1.12.9. `./scripts/stop_db.sh`

Lazy script that stops the PostgreSQL database on your machine.

./scripts/stop_db.sh

1.13. Postgres Setup

1.13.1. `python3 postgres-setup/csv_generator.py`

This regenerates the database if you want to do that for some reason. The raw database is stored in the data folder.

1.14. How does the database work / where is the raw database?

The database is stored raw in the csv files under the data folder.

1.15. Video Demo of App

See a demo of the app here

Files

README.md

Latest commit

History

README.md

File metadata and controls

1. H.A.M.L. User Manual (CSE 412 Group Project)

1.1. Setup

1.1.1. Step 1 - Python Dependencies

1.1.2. Step 2 - PostgreSQL setup

1.1.3. Step 3 - Database setup

1.1.4. Step 4 - Run the app

1.1.5. Already have the app setup?

1.1.6. Done with H.A.M.L.?

1.2. Main Screen

1.3. 1.2 Library

1.3.1. Song Library

1.3.2. Album Library

1.3.3. Artist Library

1.3.4. Record Label Library

1.4. Add

1.4.1. Add Song

1.4.2. Add Album

1.4.3. Add Artist

1.4.4. 1.3.4 Add Record Label

1.5. Search

1.5.1. Search Song

1.5.2. Search Album

1.5.3. Search Artist

1.5.4. Search Band

1.5.5. Search Record Label

1.6. Insights

1.6.1. Top 10 Songs

1.6.2. Graph Genre Song By User Rating

1.6.3. Top 10 Albums

1.6.4. Top 10 Worst Songs

1.6.5. Top 10 Worst Albums