> ## Documentation Index
> Fetch the complete documentation index at: https://percy.klappstuhl.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Music Playback, Queue Management, and Audio Filters

> Play music from YouTube, Spotify, Apple Music, and SoundCloud — control playback, shape your sound with filters, and sync with friends.

Percy's music player lets you stream tracks and playlists from the biggest music platforms directly into any voice or stage channel. Search by name or paste a URL, manage a live queue, shape your sound with audio filters, and even sync playback with what a friend is listening to on Spotify — all without leaving Discord.

## Quick start

Join a voice channel, then ask Percy to play something. Percy will join your channel automatically and start playing.

```
/play Never Gonna Give You Up
/play https://open.spotify.com/track/... --source sp
/play lofi beats --source yt
```

<Tip>
  Use `/playsearch` instead of `/play` to browse a list of results and choose the exact track you want before it's added to the queue.
</Tip>

## Source flags

By default, Percy searches YouTube Music. Use the `--source` flag to search a different platform.

| Flag | Platform                          |
| ---- | --------------------------------- |
| `yt` | YouTube / YouTube Music (default) |
| `sp` | Spotify                           |
| `sc` | SoundCloud                        |
| `am` | Apple Music                       |

Pass the flag inline or select the platform from the slash-command dropdown:

```
/play synthwave mix --source sc
/play dark academia playlist --source am
```

## Playback commands

| Command               | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `/play <query>`       | Search for a track or playlist and add it to the queue               |
| `/playsearch <query>` | Search and pick from a list of results                               |
| `/connect [channel]`  | Join a voice or stage channel                                        |
| `/leave`              | Disconnect Percy from the voice channel                              |
| `/stop`               | Stop playback and clear the queue                                    |
| `/toggle`             | Toggle between paused and playing (aliases: `/pause`, `/resume`)     |
| `/loop <mode>`        | Loop the current `track`, the whole `queue`, or turn looping `off`   |
| `/shuffle`            | Randomly reorder the queue                                           |
| `/seek <timestamp>`   | Jump to a position in the current track                              |
| `/volume <0–100>`     | Set the playback volume                                              |
| `/queue`              | View all tracks currently in the queue                               |
| `/forceskip`          | Skip the current track immediately, bypassing DJ votes               |
| `/back`               | Go back to the previous track                                        |
| `/jump-to <position>` | Jump to a specific position in the queue                             |
| `/cleanupleft`        | Remove tracks added by members who have since left the voice channel |

### Examples

```
/seek 1:30
/volume 80
/loop track
```

You can also use relative volume adjustments with a `+` or `-` prefix:

```
/volume +10
/volume -15
```

## Audio filters

Filters shape the tone and texture of your audio in real time. Apply one or combine several to dial in your sound.

| Filter              | Effect                                          |
| ------------------- | ----------------------------------------------- |
| `/filter equalizer` | Manually adjust individual frequency bands      |
| `/filter bassboost` | Boost low-end frequencies                       |
| `/filter nightcore` | Speed up and pitch-shift for a nightcore effect |
| `/filter 8d`        | Rotating 8D spatial audio effect                |
| `/filter lowpass`   | Roll off high frequencies for a warmer sound    |

Use `/filter` on its own to see which filters are currently active, and `/filter reset` to clear all of them at once.

```
/filter bassboost
/filter
/filter reset
```

<Note>
  Filters apply to everyone listening in the voice channel — not just you. Coordinate with your server before stacking multiple filters.
</Note>

## Listen together

Sync Percy's playback with whatever a member is currently listening to on Spotify. Percy joins your voice channel, plays the same track, and seeks to the exact position they're at — then follows along as the song changes.

```
/listen-together start @Member
/listen-together stop
```

Percy tracks the member's Spotify presence in real time. If they pause, skip, or switch tracks, Percy mirrors those changes automatically. Listen together stops if the member leaves Spotify or closes the session.

## DJ system

Server admins can grant trusted members a DJ role that gives them elevated control over the queue — including the ability to skip, stop, and adjust volume regardless of standard voting rules.

```
/dj add @Member
/dj remove @Member
```

Grant the DJ role to members you trust to manage the music. Remove it the same way if they no longer need elevated control.

## Lyrics

Pull up lyrics for the current track — or any song — with a single command. Percy fetches synced, time-stamped lyrics when available and falls back to plain text automatically.

```
/lyrics
/lyrics Never Gonna Give You Up
```

<Note>
  Percy needs to be in a voice channel before most playback commands will work. If Percy isn't connected yet, run `/connect` to bring it into your channel first.
</Note>