# Usage Guide

This guide covers the main features and navigation of RSPlayer's web interface.

## Navigation

RSPlayer uses a single-page application with path-based routing. The main sections are accessible via the navigation bar:

| Section | URL | Description |
|---------|-----|-------------|
| Player | `/` | Main playback controls and current track info |
| Queue | `/queue` | Current playback queue |
| Playlists | `/library/playlists` | Saved playlists |
| Library | `/library/files` | Music library browser |
| Settings | `/settings` | Configuration options |

### Keyboard Navigation

Press **?** anywhere to show the keyboard shortcuts help:

![Keyboard Shortcuts](/_assets/player_keyboard_shortcuts.png)

| Key | Action |
|-----|--------|
| 1 | Now Playing |
| 2 | Queue |
| 3 | Library (Playlists) |
| 4 | Settings |
| F / A / P / R / O / T | Library sub-pages: Files / Artists / Playlists / Radio / Podcasts / Stats |
| / | Focus search field |
| ? | Show/hide keyboard shortcuts |

## Player Page

The Player page is the main interface for controlling playback.

![Player Main](/_assets/player_main.png)

### Track Information

The top section displays information about the currently playing track:

- **Title** - Song title (clickable to search in library)
- **Artist** - Artist name (clickable to filter by artist)
- **Album** - Album name (clickable to search in library)
- **Genre** and **Date** - Additional metadata
- **Audio format** - Codec, bit depth, and sample rate (e.g., "FLAC - 24 / 96000 Hz")
- **Loudness** - LUFS value and normalization gain (when enabled)

### Playback Controls

| Control | Function |
|---------|----------|
| Play/Pause | Start or pause playback |
| Previous | Skip to previous track |
| Next | Skip to next track |
| Shuffle/Repeat | Cycle through: Sequential → Random → Loop Single → Loop Queue |
| Heart | Like/unlike the current track |
| Lyrics | Open synchronized lyrics modal |
| Visualizer | Toggle music visualizer (shown when visualization is enabled in Settings) |

### Progress Bar

- Drag to seek within the track
- Current time and total duration displayed
- Hover to see seek position tooltip

### Volume Control

- Mute/unmute button
- Volume down/up buttons
- Slider for precise volume adjustment
- Percentage display

?> Depending on platform/settings, volume control may use ALSA mixer, PipeWire, or RSPlayer software gain mode.

### Keyboard Shortcuts

| Key | Action |
|-----|--------|
| Space | Play / Pause |
| ← / → | Previous / Next track |
| Shift+← / → | Seek back / forward 10s |
| ↑ / ↓ | Volume up / down |
| M | Mute / Unmute |
| L | Like / Unlike track |
| Y | Toggle lyrics |
| S | Shuffle / Repeat mode |
| V | Cycle visualizer mode |
| 1-4 | Navigate: Player / Queue / Library / Settings |
| F / A / P / R / O / T | Library: Files / Artists / Playlists / Radio / Podcasts / Stats |
| / | Focus search field |
| ? | Show keyboard shortcuts help |
| Esc | Close modal |

### Synchronized Lyrics

RSPlayer integrates with LRCLIB for synchronized lyrics.

![Lyrics Modal](/_assets/player_lyrics.png)

1. Press **Y** or click the lyrics button on the player
2. Lyrics sync automatically with playback
3. Current line is highlighted
4. Plain lyrics shown if synchronized version not available

## Queue Page

The Queue page shows all tracks in the current playback queue.

![Queue](/_assets/player_queue.png)

### Queue Actions

| Action | Description |
|--------|-------------|
| Search | Find songs in the queue |
| Add URL | Add streaming URL(s) to queue |
| Save | Save queue as a playlist |
| Focus | Show queue starting from current song |
| Clear | Remove all items from queue |

### Queue Item Actions

Each song in the queue has a menu with:

- **Play Next** - Move song to play after current track
- **Play** - Start playing this song immediately
- **Remove** - Remove from queue

### Drag and Drop

Reorder queue items by dragging the handle (⠿) on the left side of each item.

## Playlists Page

Manage your saved playlists and auto-generated collections.

![Playlists](/_assets/player_playlists.png)

### Playlist Types

- **User Playlists** - Playlists you create and save
- **Albums** - Automatically detected albums from your library
- **Genres** - Auto-generated playlists by genre

### Playlist Actions

When you select a playlist, a modal appears with options:

- **Load** - Replace queue with playlist contents
- **Add to queue** - Append playlist to current queue
- **Add next** - Add playlist after current track

## Library Page

Browse your music collection with multiple views.

### Files View

Browse by directory structure.

![Library Files](/_assets/player_library.png)

- Navigate through your music directories
- Expand/collapse folders
- Add folders or individual files to queue
- Search across your entire library

### Artists View

Browse by artist name.

![Library Artists](/_assets/library_artists.png)

- Alphabetical artist listing
- A–Z jump rail on the right edge (shown once the list has 20+ artists):
  - Tap a letter to jump straight to the first artist under it
  - Press and drag up/down along the rail to scrub continuously — the list follows your finger, with a large letter bubble in the middle of the screen so you can see where you are
  - Lift your finger to stop; letters with no artists are dimmed and skipped over automatically
- Click artist to see their albums and songs
- Quick add to queue options

### Radio View

Manage internet radio streams.

![Library Radio](/_assets/library_radio.png)

- **Favorites** lists your own stations and the ones you starred while browsing. It is the first tab, shown when the page opens.
- **Add station** stores a stream by hand: enter a name, the stream URL and, if you like, a logo URL. The station stays in Favorites until you remove it. Hover (or tap) a station for **Play now**, **Add to queue**, **Edit** and **Remove**; removing asks for confirmation.
- **Search**, **Countries**, **Languages** and **Tags** browse the [radio-browser.info](https://www.radio-browser.info) directory; the heart button keeps a station in Favorites.
- Click a station to play it. It plays directly, without being added to the queue, and the station playing is highlighted.

While a station plays:

- **Next** and **Previous** (in the player, the desktop tray, media keys, the Android notification or a hardware panel) switch to the next or previous station in Favorites: your starred stations first, then the ones you added by hand, each sorted by name.
- Now Playing shows a **Live radio** badge with the station name; the seek bar, the 10-second skip buttons and the playback mode button are hidden. The heart adds or removes the station from Favorites.
- **Back to queue** (on Now Playing and on the Queue page) stops the radio and continues the queue song where you left it. Playing anything from the queue or the library also switches back to the queue.
- **Add to queue** is still there if you do want a station in the queue.

### Podcasts View
Subscribe to podcasts and listen to episodes; RSPlayer remembers where you stopped.

![Subscriptions list](/_assets/podcasts_subscriptions.png)

**Subscriptions** shows your shows as a grid, with a badge for unplayed episodes. Open a show to see its episodes newest-first with date, length and time left. Tap a title to expand the show notes. Each episode offers:

![Episode list](/_assets/podcasts_episodes.png)

- **Play** (resumes a started episode where you left off). The episode plays directly, without being added to the queue. When it ends, the next newer unplayed episode of the same show follows; **Next** / **Previous** move to the newer / older episode. **Back to queue** returns to your queue where you left it, as for radio.
- **Play next** / **Add to queue**, to play an episode as part of the queue instead
- **Mark played / unplayed** — episodes are marked played automatically once 95 % has been heard (configurable), and are shown dimmed

The show header has **Refresh** (re-fetch the feed now) and **Unsubscribe** (tap twice to confirm). Feeds are refreshed in the background, hourly by default.

**Search** finds shows by name in the Apple Podcasts directory, or in Podcast Index when you have entered an API key under Settings → Podcasts. Paste an RSS feed URL into the same box to subscribe to a feed that is not listed. With the search directory set to None (the default on a new Android installation), search is off and the box only takes feed URLs.

Episodes are seekable like local files, and the Now Playing page links the show name back to its episode list. Positions are tracked when RSPlayer plays the audio itself, not in browser playback mode.

### Stats View

View library statistics and loudness analysis progress.

![Library Stats](/_assets/library_stats.png)

- Total songs, albums, artists
- Total plays and liked songs
- Loudness analysis progress
- Total duration
- Top genres chart
- Albums by decade

### Adding to Queue

Right-click or use the action menu on any item:

- **Add to queue** - Append to end of queue
- **Add next** - Add after current track
- **Play** - Replace queue and play immediately
- **Load** - Load directory contents to queue

## Settings Page

Configure RSPlayer settings. For detailed configuration options, see the [Configuration](configuration.md) page.

![Settings Overview](/_assets/settings_main.png)

### Quick Settings Reference

| Section | Description |
|---------|-------------|
| Appearance | Theme selection, album art background and cover download (Last.fm) |
| Remote Access | Desktop app and Android: allow other devices on the network to open the player (off by default on Android) |
| Playback | Audio interface, auto-resume |
| Volume Control | Volume backend, mixer, step |
| Visualization & Normalization | Visualization, loudness normalization |
| DSP Equalizer | Parametric EQ, presets, CamillaDSP import |
| Music Library | Music directories, network storage |
| Multiroom | Synchronized playback across devices |
| Podcasts | Search directory (Apple Podcasts / Podcast Index + API key / None), feed refresh interval, episodes kept per show, played threshold |
| Hardware | USB command channel, power control |
| System | Restart, shutdown |

## Multiroom Playback

Play the same music on several RSPlayer devices at once, synchronized:

1. Enable multiroom in **Settings → Multiroom** on each device (restart required)
2. On the leading device, open the player page — discovered rooms appear in the **Multiroom** panel below the controls
3. Toggle rooms on to group them; everything the leader plays now plays everywhere in sync
4. Each room keeps its own volume and EQ; followers show a banner with a **Leave group** button

![Multiroom panel on the leader's player page](/_assets/multiroom_player_leader.png)

See the [Multiroom Playback](multiroom.md) page for details, settings, and troubleshooting.

## Loudness Normalization

When enabled, RSPlayer automatically normalizes volume across tracks:

1. Enable in Settings → Visualization & Normalization
2. Set target loudness (default: -18 LUFS)
3. Tracks are analyzed in background during idle
4. Progress visible on Library Stats page

The normalization preserves dynamic range while ensuring consistent perceived loudness across your library.