Tauon Music Box

https://github.com/taiko2k/tauon
Admin
Tauon Music Box is a powerful and streamlined desktop music player with support for gapless...
Tokens:20,216
Snippets:161
Trust Score:8.4
License:GPL-3.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Tauon Music Box on Windows (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Provides instructions for installing Tauon Music Box on Windows by downloading the installer from the project's GitHub releases page. This is a straightforward method for Windows users.

```bash
# Windows
# Download installer from GitHub releases
# https://github.com/Taiko2k/TauonMusicBox/releases
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/taiko2k/tauon/wiki/Building

Installs Python project dependencies from the requirements.txt file using pip. This should be done after activating the virtual environment.

```bash
pip install -r requirements.txt
```

--------------------------------

### Configure Discord Rich Presence (Non-Flatpak Tauon to Flatpak Discord)

Source: https://github.com/taiko2k/tauon/wiki/Flatpak-Extra-Steps

This command sets up Discord Rich Presence when using a non-Flatpak version of Tauon Music Box with a Flatpak-installed Discord client. It creates a symbolic link to enable communication. This configuration might be lost on reboot and should be run before starting Tauon. Omit `--user` and use `sudo` if Tauon was installed system-wide.

```bash
ln -sf {app/com.discordapp.Discord,$XDG_RUNTIME_DIR}/discord-ipc-0
```

--------------------------------

### Start Tauon Music Box

Source: https://github.com/taiko2k/tauon/wiki/Building

Launches the Tauon Music Box application by executing its main Python script.

```bash
python src/tauon/__main__.py
```

--------------------------------

### Install System Dependencies on Debian/Ubuntu

Source: https://github.com/taiko2k/tauon/wiki/Building

Installs required system dependencies for building Tauon on Debian or Ubuntu using apt. This covers development packages for audio, GUI, and Python integration.

```bash
sudo apt install -y libayatana-appindicator3-dev gir1.2-rsvg-2.0 libpipewire-0.3-dev libdbus-1-dev fonts-noto gir1.2-notify-0.7 libcairo2-dev python3-gi-cairo libwavpack-dev libsamplerate0-dev libopenmpt-dev libvorbis-dev libopusfile-dev libflac-dev libgme-dev libmpg123-dev
```

--------------------------------

### Install Tauon Music Box via Flatpak (Linux) (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Installs Tauon Music Box using the Flatpak package manager on Linux systems. This is the recommended installation method for Linux users, providing a sandboxed and easily manageable application.

```bash
# Flatpak (Linux - recommended)
flatpak install flathub com.github.taiko2k.tauonmb
flatpak run com.github.taiko2k.tauonmb
```

--------------------------------

### Install Tauon Music Box on macOS (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Details the installation process for Tauon Music Box on macOS, which involves downloading the DMG file from the project's GitHub releases page. This is the standard method for macOS users.

```bash
# macOS
# Download DMG from GitHub releases
# https://github.com/Taiko2k/TauonMusicBox/releases
```

--------------------------------

### Install System Dependencies on Fedora

Source: https://github.com/taiko2k/tauon/wiki/Building

Installs necessary system dependencies for building Tauon on Fedora using dnf. This includes development libraries for audio codecs, GUI toolkits, and Python bindings.

```bash
sudo dnf install gcc pygobject2-devel libnotify-devel SDL3-devel SDL3_image-devel wavpack-devel flac-devel libvorbis-devel opusfile-devel libopenmpt-devel libsamplerate-devel libmpg123-devel
```

--------------------------------

### Install System Dependencies for Tauon (Debian/Ubuntu) (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Installs necessary system dependencies for building Tauon Music Box on Debian-based Linux distributions like Ubuntu. This includes development libraries for audio backends, indicators, and image rendering.

```bash
# System dependencies (Debian/Ubuntu)
sudo apt install -y libayatana-appindicator3-dev gir1.2-rsvg-2.0 \
    libpipewire-0.3-dev libdbus-1-dev fonts-noto gir1.2-notify-0.7 \
    libcairo2-dev python3-gi-cairo libwavpack-dev libsamplerate0-dev \
    libopenmpt-dev libvorbis-dev libopusfile-dev libflac-dev \
    libgme-dev libmpg123-dev
```

--------------------------------

### Install Tauon Music Box via Pacman (Arch Linux) (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Installs Tauon Music Box on Arch Linux using the Pacman package manager. Alternatively, users can install it from the AUR using an AUR helper like 'yay'.

```bash
# Arch Linux (AUR or official)
sudo pacman -S tauon-music-box
# or from AUR: yay -S tauon-music-box
```

--------------------------------

### Install System Dependencies for Tauon (Fedora) (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Installs required system dependencies for compiling Tauon Music Box on Fedora Linux. This command ensures that all necessary development libraries and tools are present for the build process.

```bash
# System dependencies (Fedora)
sudo dnf install gcc pygobject2-devel libnotify-devel SDL3-devel \
    SDL3_image-devel wavpack-devel flac-devel libvorbis-devel \
    opusfile-devel libopenmpt-devel libsamplerate-devel libmpg123-devel
```

--------------------------------

### Set up Python Virtual Environment for Tauon (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Creates and activates a Python virtual environment for the Tauon Music Box project, and installs the required Python packages from the 'requirements.txt' file. This isolates project dependencies.

```bash
# Python environment setup
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

--------------------------------

### Start Playback at Specific Position

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Initiates playback from a specific track within a playlist. Requires the Playlist ID and the Position (index) of the track to start from. This is useful for resuming playback or starting a specific section of a playlist.

```http
GET /api1/start/<Playlist ID>/<Position>
```

--------------------------------

### Build TauonNowPlaying macOS App

Source: https://github.com/taiko2k/tauon/blob/master/src/nowplaying/README.md

This script builds the TauonNowPlaying macOS application. It requires Xcode Command Line Tools to be installed. The script changes the directory to 'src/nowplaying', makes the build script executable, and then runs it. The output is the 'TauonNowPlaying.app' located in 'src/nowplaying/build/'.

```bash
cd src/nowplaying
chmod +x build_app.sh
./build_app.sh
```

--------------------------------

### Start Playback at Specific Position with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Shows how to initiate playback from a specific track within a given playlist by providing the playlist ID and the track's position. This allows for targeted playback initiation.

```bash
# Start playback at specific playlist position
# Format: /start/<Playlist ID>/<Position>
curl http://localhost:7814/api1/start/12345/10
```

--------------------------------

### Tauon Spotify Integration Setup

Source: https://context7.com/taiko2k/tauon/llms.txt

Import and play your Spotify library using the Tekore library. Optional librespot can be used for local playback. This integration requires a Spotify Developer application for API access and is configured in Tauon's settings.

```python
# Spotify integration (from t_spot.py)
# Configure in Settings > Accounts > Spotify

```

--------------------------------

### Configure Tauon Music Box with Discord RP on NixOS (Nix)

Source: https://context7.com/taiko2k/tauon/llms.txt

Shows how to enable Discord Rich Presence support for Tauon Music Box when installing it on NixOS. This configuration is added to the system's 'configuration.nix' file.

```nix
# NixOS (with Discord RP support)
# In configuration.nix:
environment.systemPackages = [
  (pkgs.tauon.override { withDiscordRPC = true; })
];
```

--------------------------------

### Enable Discord Rich Presence in Tauon (NixPkg)

Source: https://github.com/taiko2k/tauon/wiki/Discord-RP

For NixPkg users, you can enable Discord Rich Presence by overriding the tauon package configuration. This involves specifying `withDiscordRPC = true;` in your Nix configuration.

```nix
tauon.override { withDiscordRPC = true; }
```

--------------------------------

### Get API Version and Playlists with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Demonstrates how to retrieve the API version and a list of all available playlists using curl commands. These endpoints provide basic information about the API and the user's music library structure.

```bash
# Get API version
curl http://localhost:7814/api1/version
# Response: {"version": 1}

# Get all playlists
curl http://localhost:7814/api1/playlists
# Response: {"playlists": [{"name": "My Music", "id": "12345", "count": 150}, ...]}}
```

--------------------------------

### Stream Audio Files with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Provides examples of how to stream audio files directly or as Opus-encoded transcoded audio using curl. It also shows how to report playback time for scrobbling purposes.

```bash
# Stream audio file directly (if can_download is true)
curl http://localhost:7814/api1/file/789 --output track.mp3

# Stream as Opus-encoded audio (transcoded via ffmpeg)
curl http://localhost:7814/api1/fileopus/789 --output track.opus

# Report playback time for scrobbling (hit every 3 seconds while playing)
curl http://localhost:7814/api1/playinghit/789
```

--------------------------------

### Get Lyrics for Track

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Fetches the lyrics for a specific track. Returns a JSON object containing the track ID and the lyrics text. If no lyrics are available, 'lyrics_text' will be an empty string.

```json
{
  "track_id": 1234,
  "lyrics_text": "Song lyrics go here, or empty string if none"
}
```

--------------------------------

### Get Tracks in Album

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Fetches all tracks belonging to a specific album within a playlist. This endpoint allows you to retrieve all songs from a particular album, identified by its Album ID.

```http
GET /api1/albumtracks/<Playlist ID>/<Album ID>
```

--------------------------------

### Enable 'Edit with Picard' Feature (Terminal)

Source: https://github.com/taiko2k/tauon/wiki/Flatpak-Extra-Steps

This command allows Tauon Music Box to interact with Picard on your host system, enabling the 'Edit with Picard' feature. This requires granting full sandbox escape. Note that only host-installed Picard will work; Flatpak-installed Picard will not be detected. Omit `--user` and use `sudo` if Tauon was installed system-wide.

```bash
flatpak override --user com.github.taiko2k.tauonmb --talk-name=org.freedesktop.Flatpak
```

--------------------------------

### Get Lyrics for a Track with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Shows how to retrieve the lyrics for a specific track using its ID. This endpoint is useful for applications that display lyrics alongside the currently playing music.

```bash
# Get lyrics for a track
curl http://localhost:7814/api1/lyrics/789
# Response: {"track_id": 789, "lyrics_text": "Song lyrics here..."}
```

--------------------------------

### Get Image Thumbnails

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Retrieves image thumbnails for tracks. Supports 'small' (max 75x75) and 'medium' (max 1000x1000) sizes. The returned content is a JPG image file. Size and aspect ratio may vary.

```http
GET /api1/pic/small/<Track ID>
GET /api1/pic/medium/<Track ID>
```

--------------------------------

### Get API Version

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Retrieves the current API version. This endpoint should be used to check for breaking changes before making other API calls. It returns a JSON object containing the version number.

```json
{
  "version": 1
}
```

--------------------------------

### Get All Tracks in Playlist

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Retrieves a list of all tracks within a specified playlist. The response is a JSON object containing an array of track objects, each with detailed metadata similar to the 'trackposition' endpoint.

```json
{
  "tracks": [
    ...
  ]
}
```

--------------------------------

### Get Albums in Playlist

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Retrieves a list of albums present in a specified playlist. The response format is similar to 'All tracks', but it only includes the first track of each album block. This is useful for browsing albums within a playlist.

```json
{
  "albums": [
    ...
  ]
}
```

--------------------------------

### Reset Flatpak Permissions (Terminal)

Source: https://github.com/taiko2k/tauon/wiki/Flatpak-Extra-Steps

This command reverts all custom Flatpak permissions for Tauon Music Box to their default settings. Use this if you encounter issues or want to return to the original configuration. Omit `--user` and use `sudo` if Tauon was installed system-wide.

```bash
flatpak override --user com.github.taiko2k.tauonmb --reset
```

--------------------------------

### Python ImportError Example for OS Compatibility

Source: https://github.com/taiko2k/tauon/wiki/Building-for-macOS

This Python ImportError demonstrates a common issue where an application built for a newer macOS version fails to run on an older one. The error message indicates a missing symbol (_XML_SetReparseDeferralEnabled) in the libexpat.1.dylib library, suggesting a mismatch between the application's build environment and the target operating system.

```python
ImportError: dlopen(/Applications/TauonMusicBox.app/Contents/Frameworks/python3.14/lib-dynload/pyexpat.cpython-314-darwin.so, 0x0002): Symbol not found: _XML_SetReparseDeferralEnabled
  Referenced from: <9E2CBFF4-656E-36B5-BE0F-74B73578A250> /Applications/TauonMusicBox.app/Contents/Frameworks/python3dot14/lib-dynload/pyexpat.cpython-314-darwin.so (built for macOS 15.0 which is newer than running OS)
  Expected in:     <034292C3-3063-3ACE-B831-DC1EDAF37333> /usr/lib/libexpat.1.dylib
```

--------------------------------

### Get Track Details by Position

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Fetches detailed information about a specific track at a given position within a playlist. The response includes track metadata such as title, artist, album, duration, and more. The 'id' field is a Track ID.

```json
{
  "title": "",
  "artist": "",
  "album": "",
  "album_artist": "",
  "duration": 180000,
  "id": 123,
  "position": 12,
  "album_id": 12,
  "track_number": "5",
  "can_download": true,
  "has_lyrics": false
}
```

--------------------------------

### Get Track Information with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Demonstrates how to retrieve detailed information about a specific track within a playlist, including metadata like title, artist, album, duration, and playback capabilities. This is useful for displaying track details or making playback decisions.

```bash
# Get track at specific playlist position
# Format: /trackposition/<Playlist ID>/<Position>
curl http://localhost:7814/api1/trackposition/12345/5
# Response: {
#   "title": "Track Name",
#   "artist": "Artist",
#   "album": "Album",
#   "album_artist": "Album Artist",
#   "duration": 180000,
#   "id": 789,
#   "position": 5,
#   "album_id": 2,
#   "track_number": "5",
#   "can_download": true,
#   "has_lyrics": false,
#   "path": "/path/to/file.mp3"
# }
```

--------------------------------

### Get Current Playback Status with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Shows how to fetch the current playback status, including whether the player is playing, paused, or stopped, along with details about the currently playing track. This is useful for monitoring playback and displaying information externally.

```bash
# Get current playback status
curl http://localhost:7814/api1/status
# Response: {
#   "status": "playing",
#   "inc": 12345,
#   "shuffle": false,
#   "album_shuffle": false,
#   "repeat": false,
#   "progress": 120000,
#   "auto_stop": false,
#   "volume": 50,
#   "playlist": "12345",
#   "playlist_length": 150,
#   "id": 789,
#   "title": "Song Title",
#   "artist": "Artist Name",
#   "album": "Album Name",
#   "position": 5,
#   "album_id": 2,
#   "track": {...}
# }
```

--------------------------------

### Get Player Status

Source: https://github.com/taiko2k/tauon/wiki/Remote-Control-API

Retrieves the current status of the music player. This includes information about the playback state (playing, paused, stopped), current track, volume, shuffle/repeat status, and playlist information. The 'inc' value indicates data changes.

```json
{
  "status": "stopped",
  "inc": 12345,
  "shuffle": false,
  "repeat": false,
  "playlist": "123",
  "playlist_length": 123,
  "id": 123,
  "title": "",
  "artist": "",
  "album": "",
  "progress": 120000,
  "auto_stop": false,
  "volume": 50,
  "position": 1,
  "album_id": 123,
  "track": {...}
}
```

--------------------------------

### Customize Column Colors in Tauon Themes

Source: https://github.com/taiko2k/tauon/wiki/Theming

Defines how to set custom colors for individual columns within a Tauon theme file. Uses RGB values followed by the column name. Supports specifying colors for the 'playing' row using a '+' suffix.

```text
240,50,50		column-codec
50,240,50		column-comment
50,50,240		column-title
240,50,240		column-album-artist
```

```text
240,50,50		column+codec
50,240,50		column+comment
50,50,240		column+title
240,50,240		column+album-artist
```

--------------------------------

### Initialize Git Submodules

Source: https://github.com/taiko2k/tauon/wiki/Building

Initializes and updates all git submodules required by the Tauon project. This command should be run after cloning the repository.

```bash
git submodule update --init --recursive
```

--------------------------------

### Command Line Arguments

Source: https://context7.com/taiko2k/tauon/llms.txt

Control Tauon Music Box behavior at launch or interact with a running instance using command-line arguments.

```APIDOC
## Command Line Arguments

Tauon supports command-line arguments to control a running instance or configure startup behavior. Arguments are processed and forwarded to the running instance via internal API on port 7813.

### Usage Examples

- **Launch normally:**
  ```bash
  tauonmb
  ```

- **Start in system tray (hidden window):**
  ```bash
  tauonmb --tray
  ```

- **Control running instance without launching a new window:**
  ```bash
  tauonmb --no-start --play
  tauonmb --no-start --pause
  tauonmb --no-start --play-pause
  tauonmb --no-start --stop
  tauonmb --no-start --next
  tauonmb --no-start --previous
  tauonmb --no-start --shuffle
  tauonmb --no-start --repeat
  ```

- **Open a file in the running instance:**
  ```bash
  tauonmb /path/to/music/file.mp3
  tauonmb "file:///path/to/music/file.mp3"
  ```

- **Running from source:**
  ```bash
  python src/tauon/__main__.py
  ```
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/taiko2k/tauon/wiki/Building

Creates a Python virtual environment named 'venv' and then activates it. This isolates project dependencies.

```bash
python -m venv venv
source venv/bin/activate
```

--------------------------------

### Compile Phazor Audio Backend and Translations (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Compiles the Phazor audio backend, optionally with PipeWire support, using the provided 'run.sh' script. It also includes a command to compile translation files, which is an optional step for localization.

```bash
# Compile Phazor audio backend (run.sh provides interactive menu)
./run.sh  # Select "Compile Phazor with PipeWire support"

# Compile translations (optional)
python compile_translations.py
```

--------------------------------

### Spotify Integration

Source: https://context7.com/taiko2k/tauon/llms.txt

Import and play your Spotify library using the Tekore library and optional librespot for local playback.

```APIDOC
## Spotify Integration

Import and play your Spotify library using the Tekore library and optional librespot for local playback. Requires a Spotify Developer application for API access.

### Configuration

Configure in Settings > Accounts > Spotify.

### Requirements

- Spotify Developer application for API access.
```

--------------------------------

### Tauon Music Box Command Line Arguments

Source: https://context7.com/taiko2k/tauon/llms.txt

Control Tauon's behavior at startup or manage a running instance using command-line arguments. Arguments are forwarded to the running instance via an internal API on port 7813.

```bash
# Launch Tauon normally
tauonmb

# Start in system tray (hidden window)
tauonmb --tray

# Control running instance without launching new window
tauonmb --no-start --play
tauonmb --no-start --pause
tauonmb --no-start --play-pause
tauonmb --no-start --stop
tauonmb --no-start --next
tauonmb --no-start --previous
tauonmb --no-start --shuffle
tauonmb --no-start --repeat

# Open a file in the running instance
tauonmb /path/to/music/file.mp3
tauonmb "file:///path/to/music/file.mp3"

# Running from source
python src/tauon/__main__.py
```

--------------------------------

### Theme File Format

Source: https://context7.com/taiko2k/tauon/llms.txt

Create custom themes using `.ttheme` files with RGB or hex color values. Place theme files in the `theme` folder.

```APIDOC
## Theme File Format

Create custom themes using `.ttheme` files with RGB or hex color values. Place theme files in the `theme` folder inside Tauon's user data folder.

### Example `custom.ttheme` format:

```text
# Example custom.ttheme file
# Format: R,G,B or R,G,B,A or #RRGGBB or #RRGGBBAA followed by element name

#-Backgrounds-----
42,32,69        top panel
38,28,61        tracklist panel
34,24,54        side panel
31,22,49        bottom panel
38,28,61        gallery background

#-Playlist-------
242,239,255     track line
242,239,255     track time
59,209,138      track index
65,200,229      track artist
249,154,221     track album

150,200,57      track playing
150,200,57      index playing
150,200,57      artist playing

249,159,177     track missing
210,184,58      fav line

65,200,229,30   playing highlight
210,190,255,15  select highlight

#-Bottom panel------
78,58,125       buttons off
59,209,138      buttons over
65,200,229      buttons active
65,200,229      seek bar
65,200,229      volume bar

#-Menu-------------
31,23,49        menu background
60,40,100       menu highlight
242,239,255     menu text

#-Column colors (optional)
240,50,50       column-codec
50,240,50       column-comment
50,50,240       column-title

# Add light-mode on its own line for light themes
# light-mode
```
```

--------------------------------

### Stream Audio File via Listen Along (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Retrieves the audio data for a specific track using its unique hash via the 'Listen Along' web interface. This allows clients to stream the music being played by the host. The track ID hash is used to identify the audio file.

```bash
# Audio file streaming (verified by track ID hash)
curl http://localhost:7590/llapi/audiofile/{track_id_hash}
```

--------------------------------

### Retrieve Album Art and Lyrics via Listen Along (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Fetches album art and lyrics associated with a track using its hash via the 'Listen Along' web interface. The response contains base64 encoded image data and HTML-escaped lyrics, enabling clients to display rich media information.

```bash
# Album art and lyrics
curl http://localhost:7590/llapi/picture/{track_id_hash}
```

--------------------------------

### IPC Protocol: Helper -> Tauon (JSON)

Source: https://github.com/taiko2k/tauon/blob/master/src/nowplaying/README.md

Defines the JSON messages sent from the macOS helper app to the Tauon music player. These messages include status updates like 'ready', media key commands ('PlayPause', 'Play', etc.), and seek commands ('seek', 'seek_relative').

```json
{ "type": "ready", "protocol": 1 }
```

```json
{ "type": "media_key", "name": "PlayPause" }
```

```json
{ "type": "seek", "position": 123.45 }
```

```json
{ "type": "seek_relative", "delta": 15 }
```

--------------------------------

### Compile Phazor and Run Translations

Source: https://github.com/taiko2k/tauon/wiki/Building

Executes the build script to compile Phazor with PipeWire support and then compiles translation files. These are steps before running the main application.

```bash
./run.sh
python compile_translations.py
```

--------------------------------

### Helper -> Tauon Communication

Source: https://github.com/taiko2k/tauon/blob/master/src/nowplaying/README.md

This section describes the JSON messages sent from the TauonNowPlaying helper application to the Tauon music player.

```APIDOC
## Helper -> Tauon Communication

This section describes the JSON messages sent from the TauonNowPlaying helper application to the Tauon music player.

### Method

N/A (IPC over stdout)

### Endpoint

N/A (IPC over stdout)

### Parameters

#### Request Body

- **type** (string) - Required - The type of message being sent. Possible values: `ready`, `media_key`, `seek`, `seek_relative`.
- **protocol** (integer) - Optional - The protocol version (e.g., `1`). Only applicable for `ready` type.
- **name** (string) - Optional - The name of the media key. Applicable for `media_key` type. Possible values: `PlayPause`, `Play`, `Pause`, `Next`, `Previous`, `Stop`.
- **position** (number) - Optional - The absolute seek position in seconds. Applicable for `seek` type.
- **delta** (number) - Optional - The relative seek delta in seconds (positive for forward, negative for rewind). Applicable for `seek_relative` type.

### Request Example

```json
{
  "type": "ready",
  "protocol": 1
}
```

```json
{
  "type": "media_key",
  "name": "PlayPause"
}
```

```json
{
  "type": "seek",
  "position": 123.45
}
```

```json
{
  "type": "seek_relative",
  "delta": -15
}
```

### Response

N/A (This is a client-to-server communication)

### Error Handling

N/A
```

--------------------------------

### Clone Tauon Repository

Source: https://github.com/taiko2k/tauon/wiki/Building

Clones the Tauon Music Box repository from GitHub and navigates into the project directory.

```bash
git clone https://github.com/Taiko2k/TauonMusicBox.git
cd TauonMusicBox
```

--------------------------------

### Volume and Seek Controls with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Illustrates how to adjust the player's volume both absolutely and relatively, and how to seek to specific positions within the current track using milliseconds or a 0-1000 range. These are crucial for fine-grained playback control.

```bash
# Set volume (0-100)
curl http://localhost:7814/api1/setvolume/75

# Relative volume adjustment (-100 to 100)
curl http://localhost:7814/api1/setvolumerel/-10

# Seek to position in milliseconds
curl http://localhost:7814/api1/seek/60000

# Seek using 0-1000 range (seek1k)
curl http://localhost:7814/api1/seek1k/500
```

--------------------------------

### Tauon -> Helper Communication

Source: https://github.com/taiko2k/tauon/blob/master/src/nowplaying/README.md

This section describes the JSON messages sent from the Tauon music player to the TauonNowPlaying helper application.

```APIDOC
## Tauon -> Helper Communication

This section describes the JSON messages sent from the Tauon music player to the TauonNowPlaying helper application.

### Method

N/A (IPC over stdin)

### Endpoint

N/A (IPC over stdin)

### Parameters

#### Request Body

- **type** (string) - Required - The type of message being sent. Possible values: `update`, `clear`, `quit`, `ping`.
- **title** (string) - Optional - The title of the track.
- **artist** (string) - Optional - The artist of the track.
- **album** (string) - Optional - The album of the track.
- **state** (integer) - Optional - The playback state. `0` for stopped, `1` for playing, `2` for paused.
- **duration** (number) - Optional - The total duration of the track in seconds.
- **elapsed** (number) - Optional - The current elapsed playback time in seconds.
- **playing** (boolean) - Optional - A boolean indicating if the track is currently playing.
- **art_path** (string) - Optional - The absolute path to the track's artwork file.

### Request Example

```json
{
  "type": "update",
  "title": "Example Song",
  "artist": "Example Artist",
  "album": "Example Album",
  "state": 1,
  "duration": 240,
  "elapsed": 120,
  "playing": true,
  "art_path": "/Users/user/Music/Artwork/album.png"
}
```

```json
{
  "type": "clear"
}
```

```json
{
  "type": "quit"
}
```

```json
{
  "type": "ping"
}
```

### Response

#### Success Response (200)

- **type** (string) - The type of response. For `ping`, the response is `pong`.

#### Response Example

```json
{
  "type": "pong"
}
```

### Error Handling

N/A
```

--------------------------------

### Keyboard Shortcuts Configuration

Source: https://context7.com/taiko2k/tauon/llms.txt

Customize keyboard shortcuts by editing the `input.txt` file. The format is `FUNCTIONNAME KEYNAME MODIFIERS`.

```APIDOC
## Keyboard Shortcuts Configuration

Customize keyboard shortcuts by editing the `input.txt` file in the user data folder. The format is `FUNCTIONNAME KEYNAME MODIFIERS` where modifiers can be Shift, Ctrl, or Alt.

### Example `input.txt` format:

```text
# Example input.txt keybind configuration

# Playback controls
playpause Space
stop
seek-forward =
seek-back -

# Navigation
previous Left Shift
advance Right Shift
start Home

# Volume control
vol-up Up Ctrl
vol-down Down Ctrl
toggle-mute M Ctrl

# Playback modes
toggle-shuffle .
toggle-repeat ,
random-track ;
random-album ; Alt

# Playlist navigation
cycle-playlist-left Left
cycle-playlist-right Right
goto-playing '
goto-top Home Shift
goto-bottom End Shift

# Playlist management
new-playlist T Ctrl
delete-playlist W Ctrl
rename-playlist R Ctrl

# Search and display
quick-find F Ctrl
global-search G Ctrl
toggle-showcase F5
toggle-minimode F8
toggle-fullscreen F11

# Track actions
love-selected L Ctrl
add-to-queue Q Alt

# Jump to specific playlist (1-9)
jump-playlist-1 1 Ctrl
jump-playlist-2 2 Ctrl
```
```

--------------------------------

### Clone Tauon Music Box Repository (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Clones the Tauon Music Box source code repository from GitHub and initializes submodules. This is the first step in building the application from source.

```bash
# Clone repository
git clone https://github.com/Taiko2k/TauonMusicBox.git
cd TauonMusicBox
git submodule update --init --recursive
```

--------------------------------

### Jellyfin Integration

Source: https://context7.com/taiko2k/tauon/llms.txt

Connect to a Jellyfin media server for streaming your music library. Authentication is handled automatically.

```APIDOC
## Jellyfin Integration

Connect to a Jellyfin media server to stream your music library. Authentication is handled automatically and streams are resolved on-demand.

### Configuration

Configure in Settings > Accounts > Jellyfin.

- `jelly_server_url`: Server URL (e.g., "http://192.168.1.100:8096")
- `jelly_username`: Username
- `jelly_password`: Password

### Authentication

- **Endpoint:** `POST {server}/Users/AuthenticateByName`
- **Headers:** `X-Application: TauonMusicBox/{version}`
- **Body:** `{"username": "user", "Pw": "password"}`

### Stream Resolution

- **Endpoint:** `GET {server}/Audio/{stream_id}/stream?UserId={userId}&static=true`

### Optional Bitrate Limiting

- Add `MaxStreamingBitrate` parameter to stream resolution request if needed.
  ```python
  params["MaxStreamingBitrate"] = network_stream_bitrate  # if > 0
  ```
```

--------------------------------

### Access Album Art with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Demonstrates how to fetch album artwork in different sizes (small thumbnail and medium) using the track ID. This allows applications to display cover art effectively.

```bash
# Get small thumbnail (max 75x75 pixels)
curl http://localhost:7814/api1/pic/small/789 --output thumb.jpg

# Get medium artwork (max 1000x1000 pixels)
curl http://localhost:7814/api1/pic/medium/789 --output cover.jpg
```

--------------------------------

### Tauon Theme File Format

Source: https://context7.com/taiko2k/tauon/llms.txt

Create custom themes using `.ttheme` files with RGB or hex color values. Place these files in the `theme` folder within Tauon's user data directory. The format specifies colors for various UI elements.

```text
# Example custom.ttheme file
# Format: R,G,B or R,G,B,A or #RRGGBB or #RRGGBBAA followed by element name

#-Backgrounds-----
42,32,69        top panel
38,28,61        tracklist panel
34,24,54        side panel
31,22,49        bottom panel
38,28,61        gallery background

#-Playlist-------
242,239,255     track line
242,239,255     track time
59,209,138      track index
65,200,229      track artist
249,154,221     track album

150,200,57      track playing
150,200,57      index playing
150,200,57      artist playing

249,159,177     track missing
210,184,58      fav line

65,200,229,30   playing highlight
210,190,255,15  select highlight

#-Bottom panel------
78,58,125       buttons off
59,209,138      buttons over
65,200,229      buttons active
65,200,229      seek bar
65,200,229      volume bar

#-Menu-------------
31,23,49        menu background
60,40,100       menu highlight
242,239,255     menu text

#-Column colors (optional)
240,50,50       column-codec
50,240,50       column-comment
50,50,240       column-title

# Add light-mode on its own line for light themes
# light-mode
```

--------------------------------

### Basic Playback Controls with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Provides curl commands for fundamental playback controls such as play, pause, stop, skipping to the next or previous track. These are essential for integrating basic music control into other applications.

```bash
# Basic playback controls
curl http://localhost:7814/api1/play
curl http://localhost:7814/api1/pause
curl http://localhost:7814/api1/stop
curl http://localhost:7814/api1/next
curl http://localhost:7814/api1/back
```

--------------------------------

### Tauon Jellyfin Integration Configuration

Source: https://context7.com/taiko2k/tauon/llms.txt

Connect to a Jellyfin media server for streaming music. Authentication is automatic, and streams are resolved on-demand. Configuration is done within Tauon's settings under Accounts > Jellyfin.

```python
# Internal Jellyfin client configuration (from t_jellyfin.py)
# Configure in Settings > Accounts > Jellyfin

# Connection settings stored in prefs:
# - jelly_server_url: Server URL (e.g., "http://192.168.1.100:8096")
# - jelly_username: Username
# - jelly_password: Password

# The client authenticates via:
# POST {server}/Users/AuthenticateByName
# Headers: X-Application: TauonMusicBox/{version}
# Body: {"username": "user", "Pw": "password"}

# Stream resolution returns URL with params:
# GET {server}/Audio/{stream_id}?UserId={userId}&static=true

# Optional bitrate limiting:
# params["MaxStreamingBitrate"] = network_stream_bitrate  # if > 0
```

--------------------------------

### Poll Listen Along Status and Track Info (Bash)

Source: https://context7.com/taiko2k/tauon/llms.txt

Polls the 'Listen Along' web interface for synchronization status, current track information, and playback position. This endpoint is used by clients to stay in sync with the host. The response includes status, track ID, position, duration, title, and artist.

```bash
# Poll endpoint for client synchronization
curl http://localhost:7590/llapi/poll
```

--------------------------------

### Tauon Keyboard Shortcuts Configuration

Source: https://context7.com/taiko2k/tauon/llms.txt

Customize keyboard shortcuts by editing the `input.txt` file. The format is `FUNCTIONNAME KEYNAME MODIFIERS`, where modifiers can include Shift, Ctrl, or Alt. This allows for personalized control over playback, navigation, and playlist management.

```text
# Example input.txt keybind configuration

# Playback controls
playpause Space
stop
seek-forward =
seek-back -

# Navigation
previous Left Shift
advance Right Shift
start Home

# Volume control
vol-up Up Ctrl
vol-down Down Ctrl
toggle-mute M Ctrl

# Playback modes
toggle-shuffle .
toggle-repeat ,
random-track ;
random-album ; Alt

# Playlist navigation
cycle-playlist-left Left
cycle-playlist-right Right
goto-playing '
goto-top Home Shift
goto-bottom End Shift

# Playlist management
new-playlist T Ctrl
delete-playlist W Ctrl
rename-playlist R Ctrl

# Search and display
quick-find F Ctrl
global-search G Ctrl
toggle-showcase F5
toggle-minimode F8
toggle-fullscreen F11

# Track actions
love-selected L Ctrl
add-to-queue Q Alt

# Jump to specific playlist (1-9)
jump-playlist-1 1 Ctrl
jump-playlist-2 2 Ctrl
```

--------------------------------

### Retrieve Playlist and Album Data with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Explains how to fetch the complete list of tracks within a playlist, as well as how to retrieve album groupings and the tracks belonging to a specific album. This enables comprehensive library browsing and management.

```bash
# Get all tracks in a playlist
curl http://localhost:7814/api1/tracklist/12345
# Response: {"tracks": [...]} 

# Get albums in a playlist (first track of each album block)
curl http://localhost:7814/api1/albums/12345
# Response: {"albums": [...]} 

# Get tracks within a specific album
# Format: /albumtracks/<Playlist ID>/<Album ID>
curl http://localhost:7814/api1/albumtracks/12345/2
# Response: {"tracks": [...]}
```

--------------------------------

### Playback Mode Toggles with Curl

Source: https://context7.com/taiko2k/tauon/llms.txt

Demonstrates how to toggle various playback modes including shuffle, album shuffle, repeat, and auto-stop using simple curl requests. These commands allow for dynamic adjustment of the playback behavior.

```bash
# Toggle playback modes
curl http://localhost:7814/api1/shuffle
curl http://localhost:7814/api1/album-shuffle
curl http://localhost:7814/api1/repeat
curl http://localhost:7814/api1/auto-stop
```

--------------------------------

### IPC Protocol: Tauon -> Helper (JSON)

Source: https://github.com/taiko2k/tauon/blob/master/src/nowplaying/README.md

Defines the JSON messages sent from the Tauon music player to the macOS helper app. These messages include track updates ('update' with metadata like title, artist, album, state, and optional duration/elapsed time/artwork path), clear notifications ('clear'), quit signals ('quit'), and keep-alive pings ('ping'/'pong').

```json
{ "type": "update", "title": "...", "artist": "...", "album": "...", "state": 1, "art_path": "/path/to/image.png" }
```

```json
{ "type": "clear" }
```

```json
{ "type": "quit" }
```

```json
{ "type": "ping" }
```

```json
{ "type": "pong" }
```

--------------------------------

### Grant File Access via Flatpak Override (Terminal)

Source: https://github.com/taiko2k/tauon/wiki/Flatpak-Extra-Steps

This command grants Tauon Music Box access to a specific directory on your system. Replace '/mnt/mymusic/' with the actual path to your music collection. This is necessary if your music is not in the default location. Ensure Tauon is closed before running the command.

```bash
flatpak override --user com.github.taiko2k.tauonmb --filesystem=/mnt/mymusic/
```

--------------------------------

### Run Tauon Music Box from Source (Python)

Source: https://context7.com/taiko2k/tauon/llms.txt

Executes the Tauon Music Box application directly from its source code using the Python interpreter. This command is typically used after setting up the development environment and dependencies.

```python
# Run from source
python src/tauon/__main__.py
```

--------------------------------

### Subsonic/Airsonic Integration

Source: https://context7.com/taiko2k/tauon/llms.txt

Connect to Subsonic-compatible servers (Subsonic, Airsonic, Navidrome, etc.) for streaming music.

```APIDOC
## Subsonic/Airsonic Integration

Connect to Subsonic-compatible servers (Subsonic, Airsonic, Navidrome, etc.) for streaming music from your personal server.

### Configuration

Configure in Settings > Accounts > Subsonic.

### API Request Format

- **Endpoint:** `GET {server}/rest/{endpoint}?u={user}&v=1.13.0&c=Tauon&f=json&t={token}&s={salt}`

### Authentication Modes

- **Token Auth:** `MD5(password + salt)`
- **Plain Password:** `p={password}` (if `subsonic_password_plain` enabled)

### Streaming Endpoint

- **Endpoint:** `GET {server}/rest/stream?id={track_id}`
- **Optional:** `maxBitRate={bitrate}` for transcoding.

### Cover Art

- **Endpoint:** `GET {server}/rest/getCoverArt?id={art_key}`

### Scrobbling

- **Endpoint:** `GET {server}/rest/scrobble?id={track_id}&submission={true/false}`
```

--------------------------------

### Album Art and Streaming API

Source: https://context7.com/taiko2k/tauon/llms.txt

Endpoints for accessing album artwork and streaming audio files directly.

```APIDOC
## Album Art and Streaming Endpoints

### Description
These endpoints provide access to album artwork and allow direct streaming of audio files.

### Method
GET

### Endpoints
- **/api1/pic/small/{track_id}**: Retrieves a small thumbnail (max 75x75 pixels) of the album art for a given track. `{track_id}` is a path parameter.
- **/api1/pic/medium/{track_id}**: Retrieves medium-sized album artwork (max 1000x1000 pixels) for a given track. `{track_id}` is a path parameter.
- **/api1/file/{track_id}**: Streams the audio file directly for a given track, if `can_download` is true. `{track_id}` is a path parameter.
- **/api1/fileopus/{track_id}**: Streams the audio file for a given track, transcoded to Opus format. `{track_id}` is a path parameter.
- **/api1/playinghit/{track_id}**: Reports the current playback time for scrobbling purposes. This endpoint should be hit periodically while a track is playing. `{track_id}` is a path parameter.

### Response
#### Success Response (200)
- Image data for artwork endpoints.
- Audio data for file streaming endpoints.
- "OK" for the `playinghit` endpoint.

#### Response Example (for /api1/pic)
*(Returns binary image data)*

#### Response Example (for /api1/file or /api1/fileopus)
*(Returns binary audio data)*

#### Response Example (for /api1/playinghit)
```
OK
```
```

--------------------------------

### Fetch Synced and Plain Lyrics from LRCLIB API (Python)

Source: https://context7.com/taiko2k/tauon/llms.txt

Retrieves synced (LRC format) and plain text lyrics for a given track from the LRCLIB API. It requires the 'requests' library and sets a User-Agent header for the request. Returns empty strings if lyrics are not found or an error occurs.

```python
# Lyrics sources (from t_lyrics.py)

# LRCLIB - Primary source for synced lyrics
import requests
def get_lrclib_lyrics(artist: str, title: str):
    params = {"track_name": title, "artist_name": artist}
    headers = {"User-Agent": "TauonMusicBox/9.1.0"}
    r = requests.get("https://lrclib.net/api/get", headers=headers, params=params, timeout=10)
    if r.status_code == 200:
        data = r.json()
        plain_lyrics = data.get("plainLyrics", "")
        synced_lyrics = data.get("syncedLyrics", "")  # LRC format
        return plain_lyrics, synced_lyrics
    return "", ""
```

--------------------------------

### Configure Phazor Library Build with CMake

Source: https://github.com/taiko2k/tauon/blob/master/CMakeLists.txt

This CMake script configures the build for the Phazor shared library. It specifies the minimum CMake version, project name, and adds the source files. It also finds and links necessary dependencies like PkgConfig, various audio codecs, and kissfft.

```cmake
cmake_minimum_required(VERSION 3.10)
project(phazor)

add_library(phazor SHARED src/phazor/phazor.c)

find_package(PkgConfig REQUIRED)

pkg_check_modules(phazor REQUIRED flac libopenmpt libmpg123 opus opusfile wavpack samplerate)

find_package(kissfft CONFIG COMPONENTS float)
if(NOT kissfft_FOUND)
	add_subdirectory(src/phazor/kissfft)
endif()

target_include_directories(phazor PRIVATE ${phazor_INCLUDE_DIRS})
target_link_libraries(phazor kissfft::kissfft ${phazor_LIBRARIES})


install(TARGETS phazor DESTINATION ${CMAKE_SOURCE_DIR}/lib)
```

--------------------------------

### Tauon Subsonic/Airsonic Integration Configuration

Source: https://context7.com/taiko2k/tauon/llms.txt

Connect to Subsonic-compatible servers like Subsonic, Airsonic, or Navidrome for streaming music. The API request format includes user, version, client, and token parameters. Supports token-based or plain password authentication.

```python
# Internal Subsonic client (from t_subsonic.py)
# Configure in Settings > Accounts > Subsonic

# API request format:
# GET {server}/rest/{endpoint}?u={user}&v=1.13.0&c=Tauon&f=json&t={token}&s={salt}

# Authentication modes:
# - Token auth: MD5(password + salt)
# - Plain password: p={password} (if subsonic_password_plain enabled)

# Streaming endpoint:
# GET {server}/rest/stream?id={track_id}
# Optional: maxBitRate={bitrate} for transcoding

# Cover art:
# GET {server}/rest/getCoverArt?id={art_key}

# Scrobbling:
# GET {server}/rest/scrobble?id={track_id}&submission={true/false}
```
Tokens:
Raw