Skip to content

Instantly share code, notes, and snippets.

@dir

dir/spotify-player-app-schema.json

Last active May 27, 2025 17:56
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save dir/be969fe548c52bedf7345aa99dfa41d3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save dir/be969fe548c52bedf7345aa99dfa41d3 to your computer and use it in GitHub Desktop.
Download ZIP
JSON Schemas for spotify-player TOML configuration files
Raw
spotify-player-app-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Spotify Player Configuration",
"description": "JSON schema for spotify-player app.toml configuration file",
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "The Spotify client's ID",
"default": "65b708073fc0480ea92a077233ca87bd"
},
"client_id_command": {
"type": "object",
"description": "A shell command that prints the Spotify client ID to stdout (overrides client_id)",
"properties": {
"command": {
"type": "string",
"description": "The command to execute"
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arguments to pass to the command"
}
},
"required": ["command"],
"additionalProperties": false
},
"login_redirect_uri": {
"type": "string",
"description": "The redirect URI for authenticating the application",
"default": "http://127.0.0.1:8989/login"
},
"client_port": {
"type": "integer",
"description": "The port that the application's client is running on to handle CLI commands",
"minimum": 1,
"maximum": 65535,
"default": 8080
},
"tracks_playback_limit": {
"type": "integer",
"description": "The limit for the number of tracks played in a tracks playback",
"minimum": 1,
"default": 50
},
"playback_format": {
"type": "string",
"description": "The format of the text in the playback's window",
"default": "{status} {track} • {artists}\\n{album}\\n{metadata}"
},
"notify_format": {
"type": "object",
"description": "The format of a notification (notify feature only)",
"properties": {
"summary": {
"type": "string",
"description": "Notification summary format"
},
"body": {
"type": "string",
"description": "Notification body format"
}
},
"additionalProperties": false,
"default": {
"summary": "{track} • {artists}",
"body": "{album}"
}
},
"notify_timeout_in_secs": {
"type": "integer",
"description": "The timeout (in seconds) of a notification (notify feature only)",
"minimum": 0,
"default": 0
},
"player_event_hook_command": {
"type": "object",
"description": "The hook command executed when there is a new player event",
"properties": {
"command": {
"type": "string",
"description": "The command to execute"
},
"args": {
"type": "array",
"items": {
"type": "string"
},
"description": "Arguments to pass to the command"
}
},
"required": ["command"],
"additionalProperties": false
},
"ap_port": {
"type": "integer",
"description": "The application's Spotify session connection port",
"minimum": 1,
"maximum": 65535
},
"proxy": {
"type": "string",
"description": "The application's Spotify session connection proxy"
},
"theme": {
"type": "string",
"description": "The application's theme",
"default": "default"
},
"app_refresh_duration_in_ms": {
"type": "integer",
"description": "The duration (in ms) between two consecutive application refreshes",
"minimum": 0,
"default": 32
},
"playback_refresh_duration_in_ms": {
"type": "integer",
"description": "The duration (in ms) between two consecutive playback refreshes",
"minimum": 0,
"default": 0
},
"page_size_in_rows": {
"type": "integer",
"description": "A page's size expressed as a number of rows (for page-navigation commands)",
"minimum": 1,
"default": 20
},
"enable_media_control": {
"type": "boolean",
"description": "Enable application media control support (media-control feature only)",
"default": true
},
"enable_streaming": {
"oneOf": [
{
"type": "string",
"enum": ["Always", "Never", "DaemonOnly"]
},
{
"type": "boolean"
}
],
"description": "Enable streaming (streaming feature only). Can be 'Always', 'Never', 'DaemonOnly', or boolean for backwards compatibility",
"default": "Always"
},
"enable_notify": {
"type": "boolean",
"description": "Enable notification (notify feature only)",
"default": true
},
"enable_cover_image_cache": {
"type": "boolean",
"description": "Store album's cover images in the cache folder",
"default": true
},
"notify_streaming_only": {
"type": "boolean",
"description": "Only send notification when streaming is enabled (streaming and notify feature only)",
"default": false
},
"default_device": {
"type": "string",
"description": "The default device to connect to on startup if no playing device found",
"default": "spotify-player"
},
"play_icon": {
"type": "string",
"description": "The icon to indicate playing state of a Spotify item",
"default": "▶"
},
"pause_icon": {
"type": "string",
"description": "The icon to indicate pause state of a Spotify item",
"default": "▌▌"
},
"liked_icon": {
"type": "string",
"description": "The icon to indicate the liked state of a song",
"default": "♥"
},
"border_type": {
"type": "string",
"enum": ["Hidden", "Plain", "Rounded", "Double", "Thick"],
"description": "The type of the application's borders",
"default": "Plain"
},
"progress_bar_type": {
"type": "string",
"enum": ["Rectangle", "Line"],
"description": "The type of the playback progress bar",
"default": "Rectangle"
},
"cover_img_width": {
"type": "integer",
"description": "The width of the cover image (image feature only)",
"minimum": 1,
"default": 5
},
"cover_img_length": {
"type": "integer",
"description": "The length of the cover image (image feature only)",
"minimum": 1,
"default": 9
},
"cover_img_scale": {
"type": "number",
"description": "The scale of the cover image (image feature only)",
"minimum": 0,
"default": 1.0
},
"seek_duration_secs": {
"type": "integer",
"description": "The duration (in seconds) to seek when using SeekForward and SeekBackward commands",
"minimum": 1,
"default": 5
},
"sort_artist_albums_by_type": {
"type": "boolean",
"description": "Sort albums on artist's pages by type, i.e. album or single",
"default": false
},
"device": {
"type": "object",
"description": "Device configurations for the Librespot integrated device",
"properties": {
"name": {
"type": "string",
"description": "The librespot device's name",
"default": "spotify-player"
},
"device_type": {
"type": "string",
"description": "The librespot device's type",
"default": "speaker"
},
"volume": {
"type": "integer",
"description": "Initial volume (in percentage) of the device",
"minimum": 0,
"maximum": 100,
"default": 70
},
"bitrate": {
"type": "integer",
"enum": [96, 160, 320],
"description": "Bitrate in kbps (96, 160, or 320)",
"default": 320
},
"audio_cache": {
"type": "boolean",
"description": "Enable caching audio files (store in $APP_CACHE_FOLDER/audio/ folder)",
"default": false
},
"normalization": {
"type": "boolean",
"description": "Enable audio normalization",
"default": false
},
"autoplay": {
"type": "boolean",
"description": "Enable autoplay similar songs",
"default": false
}
},
"additionalProperties": false
},
"layout": {
"type": "object",
"description": "Layout configurations for the application",
"properties": {
"library": {
"type": "object",
"description": "Library layout configuration",
"properties": {
"album_percent": {
"type": "integer",
"description": "The percentage of the album window in the library",
"minimum": 0,
"maximum": 100,
"default": 40
},
"playlist_percent": {
"type": "integer",
"description": "The percentage of the playlist window in the library",
"minimum": 0,
"maximum": 100,
"default": 40
}
},
"additionalProperties": false
},
"playback_window_position": {
"type": "string",
"enum": ["Top", "Bottom"],
"description": "The position of the playback window",
"default": "Top"
},
"playback_window_height": {
"type": "integer",
"description": "The height of the playback window",
"minimum": 1,
"default": 6
}
},
"additionalProperties": false
},
"component_style": {
"type": "object",
"description": "Component styles for application UI elements",
"properties": {
"block_title": {
"$ref": "#/$defs/componentStyle"
},
"border": {
"$ref": "#/$defs/componentStyle"
},
"playback_status": {
"$ref": "#/$defs/componentStyle"
},
"playback_track": {
"$ref": "#/$defs/componentStyle"
},
"playback_artists": {
"$ref": "#/$defs/componentStyle"
},
"playback_album": {
"$ref": "#/$defs/componentStyle"
},
"playback_metadata": {
"$ref": "#/$defs/componentStyle"
},
"playback_progress_bar": {
"$ref": "#/$defs/componentStyle"
},
"playback_progress_bar_unfilled": {
"$ref": "#/$defs/componentStyle",
"description": "Specific to progress_bar_type as Line"
},
"current_playing": {
"$ref": "#/$defs/componentStyle"
},
"page_desc": {
"$ref": "#/$defs/componentStyle"
},
"table_header": {
"$ref": "#/$defs/componentStyle"
},
"selection": {
"$ref": "#/$defs/componentStyle"
},
"secondary_row": {
"$ref": "#/$defs/componentStyle"
},
"like": {
"$ref": "#/$defs/componentStyle"
},
"lyrics_played": {
"$ref": "#/$defs/componentStyle"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"$defs": {
"componentStyle": {
"type": "object",
"description": "Style configuration for a UI component",
"properties": {
"fg": {
"oneOf": [
{
"type": "string",
"enum": [
"Black", "Blue", "Cyan", "Green", "Magenta", "Red", "White", "Yellow",
"BrightBlack", "BrightBlue", "BrightCyan", "BrightGreen",
"BrightMagenta", "BrightRed", "BrightWhite", "BrightYellow"
]
},
{
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Hex color code (e.g., #1e1f29)"
}
],
"description": "Foreground color - can be a palette color name or hex color"
},
"bg": {
"oneOf": [
{
"type": "string",
"enum": [
"Black", "Blue", "Cyan", "Green", "Magenta", "Red", "White", "Yellow",
"BrightBlack", "BrightBlue", "BrightCyan", "BrightGreen",
"BrightMagenta", "BrightRed", "BrightWhite", "BrightYellow"
]
},
{
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$",
"description": "Hex color code (e.g., #1e1f29)"
}
],
"description": "Background color - can be a palette color name or hex color"
},
"modifiers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Bold", "Dim", "Italic", "Underlined", "SlowBlink",
"Reversed", "RapidBlink", "Hidden", "CrossedOut"
]
},
"description": "Terminal text modifiers/effects",
"uniqueItems": true,
"default": []
}
},
"additionalProperties": false
}
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment