# User Interface dev notes

The primary user interface is implemented in python 3 and targets a 240x240 color LCD for output and four buttons as well as a four direction joystick with another button as user input. It's a simple state machine that interacts with the musikcube api running on the same device. at the end of each state, the display's framebuffer is updated before moving to the next state. 

## display layout and info
the 20 uppermost pixel rows are used for battery state, current time, total time.

the 20 lowermost pixel rows are used for 16 pixel tall marquee-style character output of artist/album/track information.

the 20 leftmost pixel columns are currently unused.

the 20 rightmost pixel columns are used for function indicators for the three buttons.

the remaining 200x200 pixel frame is used by track artwork, scrolling menus, etc.

A simple timer is started upon initialization that will flag a state to turn off the display after two minutes (by default) with no user interaction to conserve energy and display lifetime. The timer is reset to zero with any button pushes.

if display is off, it will not turn on unless the joystick button (by default) is pressed, to minimize inadvertent waking while in pocket.

## input

if state is PLAYING:

- joystick_up is volume_up_5_percent
- joystick_down is volume_down_5_percent
- joystick_left is seek_prev_10s
- joystick_right is seek_next_10s
- joystick_in is play_pause_toggle

- button_nw is pause_and_state_BROWSING
- button_ne is shuffle_toggle
- button_sw is prev_track 
- button_se is next_track 
    
if state is BROWSING:

- joystick_up is scroll_up
- joystick_down is scroll_down
- joystick_left is up_menu_level
- joystick_right is down_menu_level
- joystick_in is show_item_options

- button_nw is state_PLAYING
- button_ne is 
- button_sw is clear_current_queue
- button_se is state_SETTINGS
    
if state is SETTINGS:

- joystick_up is scroll_up
- joystick_down is scroll_down
- joystick_left is up_menu_level
- joystick_right is down_menu_level
- joystick_in is show_item_options

- button_nw is reboot
- button_ne is power_off
- button_sw is cancel_and_state_BROWSING
- button_se is save_and_state_BROWSING
    
### browsing menu hierarchy

- playlists
    - *dynamic list of playlists*
        - add to queue
        - replace queue
        - shuffle and replace queue
- artists
    - *dynamic list of artists*
        - by year
            - *dynamic list of albums chronologically*
        - by album
            - *dynamic list of albums alphabetically*
        - all tracks
            - by album
                - *dynamic list of tracks in album order chronologically*
            - by title
                - *dynamic list of tracks alphabetically*
- albums
    - *dynamic list of albums*
        - *dynamic list of tracks*

        
## musikcube api

a websocket (ugh) connection to the backend musikcube process that will actually be playing back the audio and maintaining the library database, queue, etc. we will simply be controlling playback and querying the library via api messages sent over the websocket connection. artwork can be fetched via http requests based on thumbnail_id metadata.

## states

### STARTUP

### PLAYING

### BROWSING

### SETTINGS

### SHUTDOWN