# JaTubePlayer — User Interface Guide
## Main Window
### Top Bar
| Control | What it does |
|---|---|
| **Search box** ("Search YouTube…") | Type a video title, channel name, or keyword here and press **Enter** or click the search button to search YouTube. |
| **🔎 Search button** | Runs a YouTube search using whatever is typed in the search box. |
| **📁 Playlist dropdown** | Shows your saved YouTube playlists. Select one from the list before clicking Enter Playlist. |
| **▶ Enter (Playlist) button** | Loads the playlist selected in the dropdown into the playlist panel on the right. |

The coloured dots on the far-right of the top bar are **status indicators** (Chrome Link, Discord, Google account). They are read-only — they just tell you whether each service is connected.

---

### Right Panel — Playlist

| Control | What it does |
|---|---|
| **Playlist list** | Shows all videos currently loaded. Single-click to select a video; double-click to play it immediately. |
| **▶ Play button** | Plays whichever video is currently selected (highlighted) in the list. |
| **✨ Recommend button** | Loads a list of video recommendations based on your watch history. Requires "Record playback history" to be on. |
| **★ Star button** | Loads your personally starred (saved) videos into the playlist. |
| **📺 Subscription button** | Loads your YouTube subscriptions into the playlist. Requires Google login. |
| **❤ Like button** | Loads your YouTube liked videos into the playlist. Requires Google login. |
| **📄 File button** | Opens a file picker so you can load one or more local video or audio files. |
| **📁 Folder button** | Opens a folder picker and loads all supported media files in that folder as a playlist. |
| **◀ Prev button** | Goes to the previous page of results (for subscriptions, liked videos, etc.). |
| **Next ▶ button** | Goes to the next page of results. |

---

### Video Area

Clicking anywhere on the video itself **toggles play / pause**.
Scrolling the mouse wheel over the video area **adjusts the volume**.

---

### Bottom Transport Bar

#### Now Playing strip
Shows the title of the currently playing video. Read-only.

#### Progress slider
Drag left or right to **seek** (jump) to any position in the video.
The time counter on the left shows the current position; the one on the right shows the total duration.

#### Playback Mode (radio buttons — pick one)
| Button | What it does |
|---|---|
| **▶▶ Continue** | Plays through the playlist from start to finish, then stops. |
| **🔁 Replay** | Repeats the current video endlessly. |
| **🔀 Random** | Picks the next video at random from the playlist. |

#### Playback Controls
| Button | What it does |
|---|---|
| **⏮ Previous** | Skips back to the previous video in the playlist. |
| **▶ / ⏸ Play/Pause** | Starts or pauses playback. |
| **⏹ Stop** | Stops playback and resets the position to the beginning. |
| **⏭ Next** | Skips forward to the next video in the playlist. |
| **⛶ Fullscreen** | Toggles fullscreen mode on or off. |

#### Volume slider (🔊)
Drag to **set the volume** from 0 (mute) to 120 (max, which is above 100% for boosting quiet videos).
You can also scroll the mouse wheel over it.

#### Action Buttons
| Button | What it does |
|---|---|
| **⚙️ Settings** | Opens the Settings window. |
| **☆ Star** | Toggles the current video in/out of your personal starred list. The icon fills in (★) when it is starred. |
|**Sel**|Load selected video infomation
|**Now**|Load currently playing video infomation

---

## Settings Window

Opened via **⚙️ Settings**. Has seven tabs.

---

#### General
### Tab: Advanced Player Setting
| Control | What it does |
|---|---|
| **Max Resolution** dropdown | Sets the highest video quality the player will stream. Choices: 480p, 720p, 1080p, 1440p, 2160p (4K), 4320p (8K). Lower values save bandwidth. |
| **Auto retry on error** checkbox | If a video fails to load (e.g. network hiccup), the player automatically tries again instead of giving up. |
| **Audio only mode** checkbox | Disables the video track entirely — only audio plays. Useful for listening to music while saving data or GPU. |

#### Speed & Subtitle
| Control | What it does |
|---|---|
| **Playback Speed** slider (0.3× – 3.0×) | Speeds up or slows down the video. 1.0× is normal. 2.0× plays at double speed, 0.5× at half speed. |
| **Subtitle** dropdown | Selects which subtitle track to show. Choosing "No subtitles" turns them off. |

#### Cache & Buffer

These control how much video is pre-downloaded into memory to prevent buffering interruptions.

| Control | What it does |
|---|---|
| **Cache Duration** slider (10 – 300 s) | How many seconds of video to buffer ahead. Higher = smoother playback on slow connections, but uses more memory. |
| **Max Buffer Size** slider (16 – 2048 MB) | Maximum memory the player may use for the forward buffer. Higher lets more video be held in RAM. |
| **Max Back Buffer** slider (16 – 2048 MB) | How much already-played video is kept in memory. Higher means you can rewind further without re-downloading. |
| **Cache Pause Wait** slider (0.1 – 20 s) | If the buffer runs low, the player pauses and waits this many seconds for the buffer to refill before resuming automatically. |
| **Audio Wait Open** slider (1 – 10 s) | How long the player waits for the audio stream to become available when opening a video before it times out. |

#### Fullscreen

| Control | What it does |
|---|---|
| **Auto fullscreen on open** checkbox | Automatically goes fullscreen every time the app is lanched with `openwith` function. |
| **Hover Fullscreen** checkbox | In fullscreen, shows the playback controls when you hover the mouse near the bottom of the screen. |
| **Fullscreen Mode — Normal** radio | The window fills up your monitor, with only video frame and control section visible |
| **Fullscreen Mode — Fullscreen (all widgets)** radio | The entire app window expands to fill the monitor, keeping all buttons visible. |
| **Fullscreen Mode — Fullscreen to window** radio | The video expands to fill just the app window (not the whole monitor). |

#### Advanced

| Control | What it does |
|---|---|
| **Acrylic blur effect** checkbox | Turns on the Windows acrylic/frosted-glass transparency look on the app windows. |
| **Show MPV Log** button | Opens a separate log viewer window showing detailed playback messages — useful for diagnosing problems. |
| **Enable Drag and Drop** checkbox | Lets you drag a video or audio file from Explorer straight into the player. A restart is required for the change to take effect. |
| **Force Stop Loading** button | Immediately cancels a video that is stuck loading. Use this if a video hangs and does not respond. |
| **Show Cache Info** checkbox | Displays a small real-time cache usage indicator while a video is playing. |
**Choose Color button**| Opens the color picker used to customize the blur gradient overlay color applied to the player interface.
**Set Default button**| Restores the blur gradient color to the application's default value. Useful if custom colors make the UI difficult to read.

#### Color Picker

The color picker allows precise adjustment of the blur gradient color.

| Control | Function |
| --------------------- | ------------------------------------------------------------------------ |
| **Color wheel** | Selects the base hue (red, blue, green, etc.). |
| **Brightness slider** | Adjusts how bright or dark the chosen color is. |
| **Alpha slider** | Controls transparency of the overlay tint. |
| **Hex preview box** | Shows the resulting color in hexadecimal format used by the application. |
| **OK button** | Applies the selected color to the interface. |

##### Tips

For the best visual results with acrylic blur:

* Lower **Brightness**
* Lower **Alpha**

This produces a **soft translucent tint** that blends well with the Windows acrylic effect.

Very bright or fully opaque colors may reduce the visibility of UI elements.

---

#### External Services
| Control | What it does |
|---|---|
| **Chrome extension server** toggle | Starts or stops the local server that lets the JaTubePlayer Chrome extension send videos to the player. |
| **Discord Rich Presence** toggle | Enables or disables the Discord status integration (shows "Listening / Watching" on your Discord profile). |
| **Show playing on Discord** checkbox | When Discord Rich Presence is on, this controls whether the actual video title is shown. Turn it off to show a generic "idle" status instead. |

---

### Tab: Personal Playlist

#### YouTube Data

| Control | What it does |
|---|---|
| **Update Liked Videos** button | Fetches your current YouTube liked-videos list from the internet and saves it locally. |
| **Auto-update liked videos** checkbox | Automatically refreshes the liked-videos list every time when the `liked` button is clicked and before the playlist is loaded (requires internet). |
| **Update Subscriptions** button | Fetches your current YouTube subscriptions list and saves it locally. |
| **Auto-update subscriptions** checkbox | Automatically refreshes the YouTube subscriptions list every time when the `subscribed` button is clicked and before the playlist is loaded (requires internet).|
| **Update Playlists** button | Refreshes the list of your YouTube playlists so they appear in the top-bar dropdown. |

#### History

| Control | What it does |
|---|---|
| **Record playback history** checkbox | Switch history tracking. |
| **Reset History** button | Permanently clears all saved watch history and set to default. |

#### Remove from Playlist

| Control | What it does |
|---|---|
| **Remove Selected** button | Removes the item currently selected in the playlist from the current playlist view. This does **not** delete anything from YouTube, your disk, or any other source — it only removes it from the list shown right now. |

---

### Tab: Download

Use this tab to save a video or its audio to your computer.

| Control | What it does |
|---|---|
| **Audio (MP3)** radio button | Sets the download format to audio-only (MP3). Resolution selection is disabled in this mode. |
| **Video (MP4)** radio button | Sets the download format to video (MP4). You must also choose a resolution. |
| **Get Available** button | Fetches all available resolutions for the currently selected video from YouTube. |
| **Resolution** dropdown | Enter , or after clicking "Get Available", select the quality you want to download (e.g. 1080, 720, 480). |
| **Select Path** button | Opens a folder picker to choose where downloaded files are saved. |
| **Set Default** button | Resets the download location back to the built-in default folder inside the player's directory. |
| **Download Selected Video** button | Starts the download using the format and resolution you selected. A progress indicator popup will appears while downloading. |

---

### Tab: Quick Init

Quick Init lets the player automatically load a playlist source when it starts up, so you don't have to click anything each time.

| Control | What it does |
|---|---|
| **Enable quick startup** checkbox | Master switch — turns the whole Quick Init feature on or off. Everything below is disabled while this is off. |
| **Init Search** radio + text box + **Set Init Search** button | Type a search query in the box, then click Set Init Search. On the next startup the player will automatically search that term and load the results. |
| **Init Playlist** radio + dropdown + **Get Playlist** + **Set Playlist** buttons | Click Get Playlist to load your YouTube playlists into the dropdown, choose one, then click Set Playlist. On startup the player will load that playlist automatically. |
| **Init Local Folder** radio + **Select Folder** button | Choose a folder on your computer. On startup the player will load all media files from that folder. |
| **Init Recommendation** radio | On startup the player will load video recommendations based on your watch history. Requires "Record playback history" to be on. |

The text display at the top of the tab shows what the current Quick Init is set to.

---

### Tab: Account & Authentication

This tab manages your Google account, YouTube API key, browser cookies, and OAuth credentials.

#### Google Account
| Control | What it does |
|---|---|
| **Login Google** button | Opens a browser window for you to sign in with your Google account. Required for accessing liked videos, subscriptions, and playlists. |
| **Logout Google** button | Signs you out and removes your login session and stored data (liked vids, subed channels). |
| **Delete System Key** button | Deletes everything — your login session, the stored API key, and all the encryption keys used to protect them. Use this to completely reset authentication from scratch. |

#### API Key


| Control | What it does |
|---|---|
| **YouTube API entry box** | Paste your YouTube Data API v3 key here. |
| **Set API** button | Saves the API key you typed. After setting a new key, you need to re-login with Google. |
| **Delete Stored API** button | Removes the saved API key from the player. |

#### Cookie

| Control | What it does |
|---|---|
| **Select Cookie** button | Loads a `cookies.txt` file exported from your browser. This is useful for accessing `age-restricted videos`,`Member only video`, and bypass the ytdlp bot limitation . |
| **Remove Cookie** button | Removes the currently loaded cookie file from the player. |

#### Client Secrets
Cookie
| Control | What it does |
|---|---|
| **Select Client Secret** button | Loads the `client_secret.json` file from your Google Cloud project. Required for the Google OAuth login to work. |
| **Remove Client Secret** button | Removes the loaded client secret file from the player. |

---

### Tab: Version Info

| Control | What it does |
|---|---|
| **Update** button (yt-dlp section) | Downloads and installs the latest version of yt-dlp (the engine that fetches YouTube streams). Useful when videos stop playing due to YouTube changes. |
| **Visit Website** (yt-dlp) | Opens the yt-dlp GitHub releases page in your browser. |
| **Visit Website** (JaTubePlayer) | Opens the JaTubePlayer GitHub releases page in your browser. |
| **Check version at startup** checkbox | Automatically checks whether a newer version of yt-dlp or JaTubePlayer is available each time the app starts. |

Current and latest version numbers are shown as read-only labels for both yt-dlp and JaTubePlayer.

---

### Tab: Hotkeys

Global keyboard shortcuts that work even when the app is not in focus.

#### Set Hotkey section

| Control | What it does |
|---|---|
| **Function** dropdown | Pick which action you want to assign a hotkey to (e.g. Play/Pause, Next, Volume Up). |
| **Set Hotkey** button | Minimises the settings window and listens for your key combination. Press the keys you want, and they are automatically recorded and saved. |
| **Reset All to Default** button | Resets every hotkey back to the factory defaults all at once. |

#### Current hotkey display panels (read-only)
These panels show the currently assigned key combination for each action:

| Action shown | What the hotkey does |
|---|---|
| **Play / Pause** | Toggle playback |
| **Stop** | Stop the current video |
| **Next Video** | Skip to the next item in the playlist |
| **Previous Video** | Go back to the previous item |
| **Repeat Mode** | Switch playback mode to Repeat |
| **Random Mode** | Switch playback mode to Random |
| **Continuous Play** | Switch playback mode to Continue (sequential) |
| **Volume Up** | Increase volume |
| **Volume Down** | Decrease volume |
| **Toggle Minimize** | Minimize or restore the player window |