### Manual Post-Install Setup for mprisence

Source: https://context7.com/lazykern/mprisence/llms.txt

Steps to set up the configuration directory, copy the example configuration, and install/enable the systemd user service for mprisence. This is for non-package-manager installations.

```bash
# 1. Create config directory and copy example config
mkdir -p ~/.config/mprisence
curl -o ~/.config/mprisence/config.toml \
  https://raw.githubusercontent.com/lazykern/mprisence/main/config/config.example.toml

# 2. Install and enable the systemd user service
mkdir -p ~/.config/systemd/user
curl -o ~/.config/systemd/user/mprisence.service \
  https://raw.githubusercontent.com/lazykern/mprisence/main/mprisence.service
systemctl --user enable --now mprisence
```

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

### Install mprisence from Source

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Clone the repository, navigate to the directory, and install using `cargo install --path .`. This installs the binary to `~/.cargo/bin/`.

```bash
# Clone the repository
git clone https://github.com/lazykern/mprisence.git
cd mprisence

# Install from local source
cargo install --path .
```

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

### Install mprisence on Debian/Ubuntu

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Download the `.deb` package from the GitHub Releases page and install it using `dpkg`.

```bash
sudo dpkg -i /path/to/mprisence_*.deb
```

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

### Install mprisence from Crates.io

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Install the `mprisence` binary using `cargo`. Ensure `~/.cargo/bin/` is in your `$PATH`.

```bash
cargo install mprisence
```

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

### Set up mprisence Configuration

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Create the configuration directory and download the example configuration file. Edit `config.toml` to customize mprisence.

```bash
mkdir -p ~/.config/mprisence
curl -o ~/.config/mprisence/config.toml https://raw.githubusercontent.com/lazykern/mprisence/main/config/config.example.toml
```

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

### Enable and start mprisence systemd service

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Enables the mprisence service to start automatically on login and starts it immediately. This command should be run after the service file has been downloaded and configured.

```bash
systemctl --user enable --now mprisence
```

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

### Get mprisence Help

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Displays all available commands and options for the mprisence CLI.

```bash
mprisence --help
```

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

### Install mprisence on Arch Linux

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Use `yay` to install the stable or development version of mprisence, or a pre-compiled binary.

```bash
# Install the stable version
yay -S mprisence

# Or, install the latest development version
yay -S mprisence-git

# Or without building from source
yay -S mprisence-bin
```

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

### Install mprisence with Nix

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Install mprisence using `nix-env` for non-NixOS systems or `nix profile` with flakes. For NixOS, add it to your system packages.

```bash
# without flakes:
nix-env -iA nixpkgs.mprisence

# with flakes:
nix profile install nixpkgs#mprisence
```

```nix
environment.systemPackages = [ pkgs.mprisence ];
```

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

### Install mprisence via Package Managers or Cargo

Source: https://context7.com/lazykern/mprisence/llms.txt

Instructions for installing mprisence using various package managers like AUR, Nix, dpkg, or directly via cargo. Requires Rust for cargo installation.

```bash
# Arch Linux (AUR)
yay -S mprisence          # stable release
yay -S mprisence-git      # latest git build
yay -S mprisence-bin      # pre-compiled binary

# NixOS / Nix
nix profile install nixpkgs#mprisence

# Debian / Ubuntu — download .deb from GitHub Releases, then:
sudo dpkg -i /path/to/mprisence_*.deb

# From crates.io (requires Rust)
cargo install mprisence

# From source
git clone https://github.com/lazykern/mprisence.git
cargo install --path mprisence
```

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

### Show mprisence Version

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Displays the currently installed version of the mprisence application.

```bash
mprisence version
```

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

### Wildcard Player Configuration Example

Source: https://github.com/lazykern/mprisence/blob/main/CHANGELOG.md

Demonstrates how to use wildcard characters in player configuration to match multiple players. Useful for applying settings to a group of similar players.

```toml
[player."*youtube_music*"]
show_icon = true
allow_streaming = true
```

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

### Basic mprisence Configuration Settings

Source: https://context7.com/lazykern/mprisence/llms.txt

Example TOML configuration for mprisence, showing top-level settings like clearing activity on pause, polling interval, and player allowlist.

```toml
# Clear Discord activity when media is paused (default: true)
clear_on_pause = true

# Polling interval in milliseconds (default: 2000)
interval = 2000

# Restrict to specific players; empty = allow all (supports exact, wildcard, regex)
# allowed_players = ["vlc_media_player", "*mpd*", "re:.*youtube_music.*"]
allowed_players = []
```

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

### Basic mprisence configuration example

Source: https://github.com/lazykern/mprisence/blob/main/README.md

A basic TOML configuration for mprisence, including settings for clearing Discord activity on pause, update interval, and restricting player discovery. Note the use of triple braces for preventing HTML escaping in Discord presence fields.

```toml
# Basic settings
# Whether to clear Discord activity when media is paused
clear_on_pause = true

# How often to update Discord presence (in milliseconds)
interval = 2000

# Restrict discovery to specific players (identities, wildcards, or regex).
# Matches against player identity or the bus-name "player" part (e.g., "vlc"),
# not the full D-Bus name. Leave empty to allow all players.
allowed_players = []

# Note: Triple braces `{{{variable}}}` are used to prevent HTML escaping,
# which is generally desired for Discord presence fields.
# See: https://handlebarsjs.com/guide/#html-escaping

```

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

### Handlebars Template Configuration for Discord Presence

Source: https://context7.com/lazykern/mprisence/llms.txt

Example TOML configuration for mprisence's Handlebars templating. Shows how to define the 'details' and 'state' fields for the Discord presence card using template variables.

```toml
[template]
# Line 1 of the Discord presence card
details = "{{{title}}}"

# Line 2 — iterate the artists array manually or use the pre-joined display var
state = "{{#each artists}}{{this}}{{#unless @last}} & {{/unless}}{{/each}}"
# or simply:
# state = "{{{artist_display}}}"
```

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

### Conditional Helper: regex_is_match

Source: https://context7.com/lazykern/mprisence/llms.txt

Example of using the 'regex_is_match' helper to test the player bus name against a regex pattern. Displays 'Video' for mpv/vlc, otherwise 'Audio'.

```handlebars
small_text = "{{#if (regex_is_match pattern=\"^(mpv|vlc)$\" on=player_bus_name)}}Video{{else}}Audio{{/if}}"
```

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

### Conditional Helper: eq

Source: https://context7.com/lazykern/mprisence/llms.txt

Example of using the 'eq' helper for exact string equality to conditionally display track title based on player status.

```handlebars
details = "{{#if (eq status \"Playing\")}}▶ {{{title}}}{{else}}{{{title}}}{{/if}}"
```

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

### Stop and Disable mprisence Service

Source: https://context7.com/lazykern/mprisence/llms.txt

Stops the mprisence systemd user service and disables it from starting automatically on login.

```bash
# Stop and disable autostart
systemctl --user disable --now mprisence
```

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

### Conditional Helper: regex_captures

Source: https://context7.com/lazykern/mprisence/llms.txt

Example of using the 'regex_captures' helper to extract a named group 'name' from the player variable, assuming a 'Desktop' suffix.

```handlebars
details = "{{#with (regex_captures pattern=\"^(?<name>.+) Desktop$\" on=player)}}{{name}}{{/with}}"
```

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

### Conditional Helper: contains

Source: https://context7.com/lazykern/mprisence/llms.txt

Example of using the 'contains' helper for substring matching to display track title if the player is Spotify, otherwise display the player name.

```handlebars
details = "{{#if (contains player \"Spotify\")}}{{{title}}}{{else}}{{{player}}}{{/if}}"
```

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

### Handlebars Helper: regex_captures

Source: https://context7.com/lazykern/mprisence/llms.txt

Illustrates 'regex_captures' for extracting named capture groups from a string using a regex, used to get the player name from a string like 'Spotify Desktop'.

```toml
# regex_captures — extract named capture groups
# details = "{{#with (regex_captures pattern=\"^(?<name>.+) Desktop$\" on=player)}}{{name}}{{/with}}"
# → "Spotify"  (from "Spotify Desktop")
```

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

### Conditional Helper: icontains

Source: https://context7.com/lazykern/mprisence/llms.txt

Example of using the 'icontains' helper for case-insensitive substring matching to display track title if the player name contains 'spotify', otherwise display the player name.

```handlebars
details = "{{#if (icontains player \"spotify\")}}{{{title}}}{{else}}{{{player}}}{{/if}}"
```

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

### Show Current Configuration

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Displays the active configuration settings for mprisence.

```bash
mprisence config
```

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

### Cover Art Configuration

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Set up cover art fetching by specifying local file names, search depth, and preferred providers like MusicBrainz or Catbox.

```toml
[cover]
file_names = ["cover", "folder", "front", "album", "art"]
local_search_depth = 2

[cover.provider]
provider = ["musicbrainz", "catbox"]

[cover.provider.musicbrainz]
min_score = 100

[cover.provider.catbox]
# user_hash = "your_user_hash" # optional: lets you delete uploads later
use_litter = false            # true -> upload to Litterbox instead of permanent Catbox storage
litter_hours = 24             # valid values: 1, 12, 24, 72

[cover.provider.imgbb]
# Your ImgBB API key (get one at: https://api.imgbb.com/)
api_key = "YOUR_API_KEY_HERE"
# How long to keep uploaded images (in seconds, default: 1 day)
expiration = 86400
```

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

### Print mprisence Version

Source: https://context7.com/lazykern/mprisence/llms.txt

Prints the current version of the mprisence application.

```bash
# Print version
mprisence version
```

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

### Display Effective mprisence Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Shows the currently loaded and effective configuration for mprisence, including general settings, activity, time display, cover art, templates, and overrides.

```bash
# Show effective configuration loaded from config.toml
mprisence config
# Output sections: General, Activity, Time Display, Cover Art, Templates, Overrides Detail
```

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

### Troubleshooting: Vesktop Flatpak

Source: https://context7.com/lazykern/mprisence/llms.txt

Note regarding Vesktop Flatpak users needing to set up an IPC socket symlink for mprisence to function correctly.

```text
# Vesktop Flatpak — requires IPC socket symlink
# See: https://github.com/flathub/dev.vencord.Vesktop?tab=readme-ov-file#native-applications
```

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

### Download mprisence systemd service file

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Downloads the systemd service file for mprisence. If the binary is not in ~/.cargo/bin/, the ExecStart path in the downloaded file must be updated.

```bash
curl -o ~/.config/systemd/user/mprisence.service https://raw.githubusercontent.com/lazykern/mprisence/main/mprisence.service
```

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

### Troubleshooting: List Players

Source: https://context7.com/lazykern/mprisence/llms.txt

Command to list all players currently detected by mprisence, useful for verifying player visibility.

```bash
# Confirm your player is visible to mprisence
mprisence players list
```

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

### Follow mprisence Service Logs

Source: https://context7.com/lazykern/mprisence/llms.txt

Follows the live logs of the mprisence systemd user service in real-time using journalctl. Useful for monitoring and debugging.

```bash
# Follow live logs
journalctl --user -u mprisence -f
```

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

### CLI Commands

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Basic command-line interface commands for MPRISence, such as listing players.

```bash
mprisence players list
```

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

### Create systemd user directory

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Ensures the directory for systemd user services exists. Run this command before downloading the service file.

```bash
mkdir -p ~/.config/systemd/user
```

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

### Configure local album covers with Catbox

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Sets the cover art provider to Catbox, with options for using Litterbox for temporary storage and specifying its duration. An optional user_hash can be provided to manage uploads.

```toml
[cover.provider]
provider = ["catbox"]

[cover.provider.catbox]
# user_hash = "your_user_hash" # optional: lets you delete uploads later
use_litter = false            # true -> upload to Litterbox instead of permanent Catbox storage
litter_hours = 24             # valid values: 1, 12, 24, 72
```

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

### View mprisence Service Logs

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Follows the logs of the mprisence systemd user service in real-time, useful for debugging.

```bash
journalctl --user -u mprisence -f
```

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

### Troubleshooting: Validate Config

Source: https://context7.com/lazykern/mprisence/llms.txt

Command to validate the syntax of the TOML configuration file before restarting the mprisence service.

```bash
# Validate TOML config syntax before restarting

```

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

### Troubleshooting: Debug Logging

Source: https://context7.com/lazykern/mprisence/llms.txt

Command to run mprisence with debug logging enabled by setting the RUST_LOG environment variable.

```bash
# Run with full debug output
RUST_LOG=debug mprisence
```

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

### Player Allowlist Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Specifies a list of players to be tracked by mprisence, using exact matches, wildcards, and regular expressions.

```toml
# Only track VLC, MPD variants, and YouTube Music
allowed_players = [
  "vlc_media_player",     # exact match
  "*mpd*",                # wildcard: any identity containing "mpd"
  "re:.*youtube_music.*", # regex match
]

# Equivalent: using /regex/ syntax
# allowed_players = ["/^vlc.*/", "*mpd*"]
```

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

### Configure local album covers with ImgBB

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Sets the cover art provider to ImgBB, requiring an API key for re-hosting local cover art. Ensure your API key is correctly entered.

```toml
[cover.provider]
provider = ["imgbb"]

[cover.provider.imgbb]
api_key = "YOUR_API_KEY_HERE"
```

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

### Time Display Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Configuration for how time is displayed in Discord. 'show' enables time display, and 'as_elapsed' toggles between showing elapsed time (up) or remaining time (down).

```toml
[time]
# Show elapsed/remaining time progress in Discord (default: true)
show = true

# true  = show elapsed time  (counts up from 0:00)
# false = show remaining time (counts down to 0:00) — requires track length metadata
as_elapsed = false
```

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

### Show Detailed Player Information

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Provides in-depth details for each detected MPRIS player, including metadata and configuration.

```bash
mprisence players list --detailed
```

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

### Enable Verbose Logging

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Runs mprisence with increased logging verbosity (debug or trace level) to aid in troubleshooting. This is useful for diagnosing issues with presence updates or cover art.

```bash
RUST_LOG=debug mprisence # or RUST_LOG=trace mprisence
```

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

### Cover Art File Names Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Configuration for local cover art search. 'file_names' specifies the base names of files to look for, and 'local_search_depth' controls how many parent directories to search.

```toml
[cover]
# File stem names searched for local cover art (extensions .jpg/.jpeg/.png/.gif are tried)
file_names = ["cover", "folder", "front", "album", "art"]

# How many parent directories to walk upward searching for local art (0 = same dir only)
local_search_depth = 2
```

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

### Run mprisence Without System Service

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Executes mprisence in the foreground without relying on a systemd user service.

```bash
mprisence
```

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

### Activity Type and Time Display Settings

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Configure the activity type (listening, watching, playing, competing) and time display (elapsed or remaining) for your Discord presence.

```toml
[activity_type]
use_content_type = true
default = "listening"

[time]
show = true
as_elapsed = true
```

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

### Troubleshooting: Clear Cache

Source: https://context7.com/lazykern/mprisence/llms.txt

Command to clear the mprisence cover art cache, which can resolve issues with missing or stale artwork.

```bash
# Cover art missing — clear stale cache
rm -rf ~/.cache/mprisence/cover_art
```

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

### Validate mprisence Version String

Source: https://context7.com/lazykern/mprisence/llms.txt

An internal utility command to validate a given version string against mprisence's versioning scheme.

```bash
# Validate a version string (internal utility)
mprisence version validate 1.5.2
```

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

### Specific Player Configuration (MPV)

Source: https://context7.com/lazykern/mprisence/llms.txt

Configures MPV to always display the status as 'Watching'.

```toml
# MPV — always show as "Watching"
[player.mpv]
show_icon            = true
override_activity_type = "watching"
```

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

### Activity Type Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Configuration for the Discord activity type. 'use_content_type' enables auto-detection (audio/video), while 'default' sets a fallback activity.

```toml
[activity_type]
# Auto-detect from media URL: audio -> "listening", video -> "watching"
use_content_type = true

# Fallback when detection is off or content type is unrecognised
# Options: "listening" | "watching" | "playing" | "competing"
default = "listening"
```

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

### List Detailed MPRIS Player Information

Source: https://context7.com/lazykern/mprisence/llms.txt

Provides detailed information for each MPRIS player, including metadata, bus name, and effective presence configuration. Use the --detailed flag for this.

```bash
# Full per-player detail: metadata, bus name, effective presence config
mprisence players list --detailed
# Example output:
# ▶ VLC media player  [playing]
#   Title    : Sunset
#   Artists  : Artist Name
#   Album    : Chill Vibes
#   Length   : 03:42
#   Presence : enabled (allow_streaming = true)
#   ID       : vlc_media_player
#   Bus Name : vlc
```

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

### Enable Verbose Logging for mprisence

Source: https://context7.com/lazykern/mprisence/llms.txt

Enables verbose logging for mprisence by setting the RUST_LOG environment variable to 'debug' or 'trace'. Useful for debugging.

```bash
# Enable verbose logging (debug or trace)
RUST_LOG=debug mprisence
RUST_LOG=trace mprisence
```

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

### Manage mprisence systemd service

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Provides commands to check the status, restart, view logs, and disable the mprisence systemd user service.

```bash
# Check service status
systemctl --user status mprisence

# Restart the service after changing the config
systemctl --user restart mprisence

# View detailed logs
journalctl --user -u mprisence -f

# Stop and disable the service
systemctl --user disable --now mprisence
```

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

### Wildcard Player Matching

Source: https://context7.com/lazykern/mprisence/llms.txt

Uses a wildcard to match any player whose identity contains 'youtube_music', enabling icon display and streaming.

```toml
# Wildcard: match any player whose identity contains "youtube_music"
[player."*youtube_music*"]
show_icon       = true
allow_streaming = true
```

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

### Cover Art Provider Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Configuration for cover art providers. 'provider' lists active providers in order of priority after local search. Specific provider settings follow.

```toml
[cover.provider]
# Active providers, tried left-to-right after local file search
provider = ["musicbrainz", "catbox"]   # or ["musicbrainz", "imgbb"], ["catbox"], etc.
```

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

### Default Player Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Sets global defaults for all players, including Discord Application ID, icon, and status display type. These can be overridden by specific player configurations.

```toml
# Global defaults applied to every player
[player.default]
ignore               = false
app_id               = "1121632048155742288"   # Default Discord Application ID
icon                 = "https://raw.githubusercontent.com/lazykern/mprisence/main/assets/icon.png"
show_icon            = false
allow_streaming      = false
status_display_type  = "name"   # "name" | "state" | "details"
```

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

### Check mprisence Service Status

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Verifies if the mprisence systemd user service is currently running.

```bash
systemctl --user status mprisence
```

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

### Player-Specific Configuration

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Customize settings for individual players, overriding default application IDs, icons, and status display types. Supports wildcards for matching player names.

```toml
# Use 'mprisence players list' to get the correct player identity (e.g., vlc_media_player)

[player.default]
ignore = false
app_id = "1121632048155742288"
icon = "https://raw.githubusercontent.com/lazykern/mprisence/main/assets/icon.png"
show_icon = false
allow_streaming = false
status_display_type = "name"

[player.vlc_media_player]
app_id = "YOUR_VLC_APP_ID_HERE"
icon = "https://example.com/vlc-icon.png"
show_icon = true
allow_streaming = true
status_display_type = "details"

# Example: Ignore Spotify
# [player.spotify]
# ignore = true

# Example: Wildcard matches
[player."*youtube_music*"]
show_icon = true
allow_streaming = true
```

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

### MusicBrainz Cover Art Provider Settings

Source: https://context7.com/lazykern/mprisence/llms.txt

Settings for the MusicBrainz cover art provider. 'min_score' sets the minimum confidence score required to accept a result.

```toml
[cover.provider.musicbrainz]
# Minimum confidence score (0–100) to accept a MusicBrainz result; higher = stricter
min_score = 95
```

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

### Specific Player Configuration (VLC)

Source: https://context7.com/lazykern/mprisence/llms.txt

Overrides default settings for VLC Media Player, enabling streaming, showing the icon, and setting the status display type to 'details'.

```toml
# VLC — custom app ID, icon, streaming enabled, show icon
[player.vlc_media_player]
app_id               = "1124968989538402334"
icon                 = "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e6/VLC_Icon.svg/1200px-VLC_Icon.svg.png"
show_icon            = true
allow_streaming      = true
status_display_type  = "details"
# override_activity_type = "watching"   # Force "Watching" regardless of content type
```

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

### Tooltip Text Templates

Source: https://context7.com/lazykern/mprisence/llms.txt

Templates for customizing tooltip text on large and small images. The 'large_text' template includes album and year, while 'small_text' displays the player name or a fallback.

```handlebars
large_text = "{{#if album}}{{{album}}}{{#if year}} ({{{year}}}){{/if}}{{/if}}"
```

```handlebars
small_text = "{{#if player}}{{{player}}}{{else}}MPRIS{{/if}}"
```

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

### Troubleshooting: Service Status

Source: https://context7.com/lazykern/mprisence/llms.txt

Commands to check the status of the mprisence systemd user service and view its logs for debugging.

```bash
# Rich presence not updating — check service and Discord settings
systemctl --user status mprisence
journalctl --user -u mprisence -f
```

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

### Handlebars Helper: eq

Source: https://context7.com/lazykern/mprisence/llms.txt

Demonstrates the 'eq' helper for exact string comparison within Handlebars templates, used here to conditionally display status text.

```toml
# eq — exact string equality
# details = "{{#if (eq status \"Playing\")}}"Now Playing: {{{title}}}"{{else}}"{{{title}}}"{{/if}}"
# → "Now Playing: Blue In Green"  (when Playing)
```

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

### Core Metadata Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

A list of template variables for accessing core track metadata like title, artists, album, year, and track numbers.

```toml
# Core Metadata
# {{{title}}}                  Track title
# {{{artists}}}                Artists array (use with {{#each}})
# {{{artist_display}}}         Artists comma-separated string
# {{{album}}}                  Album name
# {{{album_artists}}}          Album artists array
# {{{album_artist_display}}}   Album artists comma-separated
# {{{track_number}}}           Track number (integer)
# {{{track_total}}}            Total tracks in album
# {{{track_display}}}          "3/12" formatted string
# {{{disc_number}}}            Disc number
# {{{disc_total}}}             Total discs
# {{{disc_display}}}           "1/2" formatted disc string
# {{{genres}}}                 Genres array
# {{{genre_display}}}          Genres comma-separated
# {{{year}}}                   Release year
```

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

### Discord Presence Display Template

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Configure the text displayed in your Discord presence using Handlebars templating. Supports conditional logic and iteration for artists.

```toml
[template]
details = "{{{title}}}"

state = "{{#each artists}}{{this}}{{#unless @last}} & {{/unless}}{{/each}}"
# or just use
# state = "{{{artist_display}}}"

large_text = "{{#if album}}{{{album}}}{{#if year}} ({{{year}}}){{/if}}{{/if}}"

small_text = "{{#if player}}{{{player}}}{{else}}MPRIS{{/if}}"

# Match substrings or regex patterns in helpers
# details = "{{#if (contains player "Spotify")}}{{{title}}}{{else}}{{{player}}}{{/if}}"
# details = "{{#if (icontains player "spotify")}}{{{title}}}{{else}}{{{player}}}{{/if}}"
# small_text = "{{#if (regex_is_match pattern="^(mpv|vlc)$" on=player_bus_name)}}Video{{else}}Audio{{/if}}"
```

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

### List Detected MPRIS Players

Source: https://context7.com/lazykern/mprisence/llms.txt

Lists all detected MPRIS players, showing their status (playing, paused) and whether they are excluded. Useful for a quick overview of active media players.

```bash
# List all detected MPRIS players (identity, status, ignored/allowed state)
mprisence players list
# Example output:
# MPRIS players: 2 (1 playing, 1 paused, 0 excluded)
# ────────────────────────────────────────────────────────
# ▶ VLC media player               Sunset — Chill Vibes  [playing]
# ⏸ Music Player Daemon            Blue In Green — Kind  [paused]
```

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

### Catbox Cover Art Provider Settings

Source: https://context7.com/lazykern/mprisence/llms.txt

Settings for the Catbox cover art provider. Options include using a user hash for deletion, uploading to Litterbox (temporary storage), and setting Litterbox TTL.

```toml
[cover.provider.catbox]
# Optional user hash to allow deleting uploads later
# user_hash = "your_user_hash"
use_litter  = false   # true → upload to temporary Litterbox instead of permanent Catbox
litter_hours = 24     # Litterbox TTL: 1, 12, 24, or 72 hours
```

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

### Validate TOML Configuration

Source: https://context7.com/lazykern/mprisence/llms.txt

Use this Python command to validate your TOML configuration file before applying it.

```python
python3 -c "import tomllib; tomllib.load(open('config.toml','rb'))"
```

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

### ImgBB Cover Art Provider Settings

Source: https://context7.com/lazykern/mprisence/llms.txt

Settings for the ImgBB cover art provider. Requires an API key and allows setting an image expiration time in seconds.

```toml
[cover.provider.imgbb]
# Required for imgbb provider; obtain at https://api.imgbb.com/
api_key    = "YOUR_IMGBB_API_KEY"
expiration = 86400   # Seconds before uploaded image expires (0 = never)
```

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

### Audio Properties Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

Template variables for displaying audio properties such as bitrate, sample rate, bit depth, and channel count, typically sourced from local file tags.

```toml
# Audio Properties (from local file tags via lofty)
# {{{bitrate_display}}}        e.g. "320 kbps"
# {{{sample_rate_display}}}    e.g. "44.1 kHz"
# {{{bit_depth_display}}}      e.g. "16-bit"
# {{{channels_display}}}       e.g. "Stereo"
```

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

### Additional Metadata Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

Template variables for accessing additional metadata like duration, BPM, mood, composer, and comments.

```toml
# Additional Metadata
# {{{duration_secs}}}          Raw duration in seconds
# {{{duration_display}}}       "MM:SS" formatted duration
# {{{initial_key}}}            Musical key
# {{{bpm}}}                    Beats per minute
# {{{mood}}}                   Track mood
# {{{composer}}}               Composer
# {{{lyricist}}}               Lyricist
# {{{comment}}}                Comment tag
```

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

### Restart mprisence Service

Source: https://context7.com/lazykern/mprisence/llms.txt

Restarts the mprisence systemd user service. This is typically done after editing configuration files, although hot-reloading handles most changes automatically.

```bash
# Restart after editing config (hot-reload handles most changes automatically)
systemctl --user restart mprisence
```

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

### Regex Player Matching (MPD)

Source: https://context7.com/lazykern/mprisence/llms.txt

Uses a regular expression to match variants of 'mpdris2', allowing configuration of its App ID and icon.

```toml
# Regex: match mpdris2 variants (prefix re: or wrap in /.../))
[player."re:.*mpdris2.*"]
app_id = "1126153268486213672"
icon   = "https://www.musicpd.org/logo.png"
```

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

### MusicBrainz IDs Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

Template variables for accessing MusicBrainz identifiers for tracks, albums, artists, and release groups.

```toml
# MusicBrainz IDs
# {{{musicbrainz_track_id}}}
# {{{musicbrainz_album_id}}}
# {{{musicbrainz_artist_id}}}
# {{{musicbrainz_release_group_id}}}
```

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

### Player Status Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

Template variables for player-specific information, including player name, D-Bus name, status (Playing, Paused, Stopped), status icon, and volume.

```toml
# Player Status
# {{{player}}}                 Player identity name (e.g. "VLC media player")
# {{{player_bus_name}}}        D-Bus bus name segment (e.g. "vlc")
# {{{status}}}                 "Playing", "Paused", or "Stopped"
# {{{status_icon}}}            ▶, ⏸, or ⏹
# {{{volume}}}                 Player volume (0.0–1.0)
```

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

### Ignoring a Player (Spotify)

Source: https://context7.com/lazykern/mprisence/llms.txt

Configures Spotify to be ignored by mprisence, preventing it from displaying status updates.

```toml
# Ignore Spotify entirely
[player.spotify]
ignore = true
```

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

### Handlebars Helper: regex_is_match

Source: https://context7.com/lazykern/mprisence/llms.txt

Demonstrates 'regex_is_match' for testing a string against a regular expression, used to determine if the player is 'mpv' or 'vlc' for status display.

```toml
# regex_is_match — test against a regex pattern
# small_text = "{{#if (regex_is_match pattern=\"^(mpv|vlc)$\" on=player_bus_name)}}"Video"{{else}}"Audio"{{/if}}"
# → "Video"  (when player_bus_name is "mpv" or "vlc")
```

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

### Set custom status display type

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Configures how the player and track information is displayed in Discord status. Options include 'name', 'state', or 'details'. This can be set globally or overridden per player.

```toml
# Global default for all players
[player.default]
status_display_type = "name" # name | state | details

# Optional per-player override (this one only affects VLC)
[player.vlc_media_player]
status_display_type = "details"
```

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

### Handlebars Helper: icontains

Source: https://context7.com/lazykern/mprisence/llms.txt

Shows the 'icontains' helper for case-insensitive substring checking, appending a saxophone emoji if the genre contains 'jazz'.

```toml
# icontains — case-insensitive substring check
# details = "{{#if (icontains genre_display \"jazz\")}}"{{{title}}} 🎷"{{else}}"{{{title}}}"{{/if}}"
# → "Blue In Green 🎷"
```

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

### Handlebars Helper: contains

Source: https://context7.com/lazykern/mprisence/llms.txt

Illustrates the 'contains' helper for case-sensitive substring checking in Handlebars, used to prefix the title with 'Spotify:' if the player is Spotify.

```toml
# contains — case-sensitive substring check
# details = "{{#if (contains player \"Spotify\")}}"Spotify: {{{title}}}"{{else}}"{{{title}}}"{{/if}}"
# → "Spotify: Ocean Eyes"
```

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

### Clear Cover Art Cache

Source: https://github.com/lazykern/mprisence/blob/main/README.md

Removes cached cover art files, which can help resolve issues with outdated or incorrect cover art display.

```bash
rm -rf ~/.cache/mprisence/cover_art
```

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

### Classical Music Template Variables

Source: https://context7.com/lazykern/mprisence/llms.txt

Template variables specific to classical music, including movement title and formatted movement display.

```toml
# Classical Music
# {{{movement}}}               Movement title
# {{{movement_display}}}       "1/3" formatted movement
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.