spotify-player 配置系统详解app.toml、theme.toml、keymap.toml 全参数参考【免费下载链接】spotify-playerA Spotify player in the terminal with full feature parity项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-playerspotify-player是一款在终端中运行的完整功能 Spotify 播放器其行为几乎全部由位于$HOME/.config/spotify-player下的三个 TOML 配置文件驱动app.toml应用设置、theme.toml主题与keymap.toml按键映射。本文以仓库中的 docs/config.md 为骨架完整覆盖全部配置项、默认值与实操示例并结合 config 模块源码 说明配置如何被加载、校验与覆盖帮助你快速定制属于自己的终端播放器。配置文件的位置与加载机制三个配置文件都位于应用配置目录中默认为$HOME/.config/spotify-player缓存目录为$HOME/.cache/spotify-player文件作用缺失时行为app.toml应用设置主题、设备、布局、刷新、通知等自动生成一份默认配置theme.toml自定义主题调色板 组件样式使用内置主题仅记录警告keymap.toml新增或覆盖按键映射 / Actions使用默认键位仅记录警告这一行为在源码中得到印证。AppConfig::new 中若解析不到配置文件则调用write_config_file把当前默认值序列化为 TOML 写出——这就是首次运行后app.toml会自动出现的原因。而theme.toml/keymap.toml解析失败时只会tracing::warn!并使用默认值见 ThemeConfig::parse_config_file 与 KeymapConfig::parse_config_file。一份完整的示例配置见 examples/app.toml。Generalapp.toml 全选项spotify_player使用app.toml管理应用设置。完整选项表如下与 docs/config.md 中的 General 表格一致选项说明默认值client_id访问 API 的 Spotify client ID。除非确定需要否则保持不设置见 Notes。代码内默认ncspot 的 client IDclient_id_command向 stdout 输出 client ID 的 shell 命令覆盖client_id。Nonelogin_redirect_uri认证时的重定向 URI。http://127.0.0.1:8989/loginclient_port应用用于处理 CLI 命令的客户端端口。8080log_folder日志文件存储路径。Nonetracks_playback_limit一次播放会话中的最大曲目数。50playback_format播放窗口的格式字符串。{status} {track} • {artists} {liked}\n{album} • {genres}\n{metadata}playback_metadata_fields{metadata}占位符中显示的元数据字段顺序。[repeat, shuffle, volume, device]notify_format通知格式需启用notify特性。{ summary {track} • {artists}, body {album} }notify_timeout_in_secs通知超时秒数需启用notify特性。0notify_transient发送瞬态通知仅 Linux需notify特性。falseplayer_event_hook_command播放事件触发时执行的命令。Noneap_portSpotify 会话连接端口。NoneproxySpotify 会话连接代理。Nonetheme要使用的主题名。defaultapp_refresh_duration_in_ms应用刷新间隔毫秒。32playback_refresh_duration_in_ms播放刷新间隔毫秒。0api_rate_limit_retriesSpotify 返回429 Too Many Requests后 GET 请求的重试次数。2page_size_in_rows导航时每页的行数。20enable_media_control启用媒体控制支持需media-control特性。Linux 为truemacOS/Windows 为falseenable_streaming启用流媒体Always、Never或DaemonOnly。Alwaysenable_audio_visualization在播放窗口显示实时频谱柱状图需streaming特性。falseenable_notify启用通知需notify特性。trueenable_cover_image_cache缓存专辑封面图。truenotify_streaming_only仅在流媒体激活时发送通知需streaming与notify特性。falseplay_icon播放状态图标。▶pause_icon暂停状态图标。▌▌liked_icon已收藏歌曲图标。♥explicit_icon强内容explicit歌曲图标。(E)border_type边框样式Hidden、Plain、Rounded、Double或Thick。Plainprogress_bar_type进度条样式Rectangle或Line。Rectangleprogress_bar_position进度条位置Bottom或Right。Bottomlayout布局配置见下文 Layout 小节。见下文genre_num播放文本中显示的最大流派数。2cover_img_length封面图在终端中的列数需image特性。0自动见 Notescover_img_width封面图在终端中的行数需image特性。5cover_img_pixels封面图每侧像素数需pixelate特性。16seek_duration_secsseek 命令的跳转秒数。5sort_artist_albums_by_type艺术家页面按类型排序专辑。falsevolume_scroll_step鼠标滚轮调节音量的步长。5enable_mouse_scroll_volume启用鼠标滚轮音量控制。falsecustom_queue启用应用自管队列以支持自定义播放集成需streaming特性。truepause_on_startup启动时以暂停状态开始而非恢复上次会话需streaming特性。falseenable_relative_line_number为列表与弹窗启用 Vim 风格相对行号。falsedevice设备配置见下文 Device 小节。见下文这些字段在 AppConfig 结构体 中一一对应多数默认值可通过 Default for AppConfig 核对部分字段带#[cfg(feature ...)]只有编译时启用了相应 cargo feature 才真正生效。Notesclient_id、限流与刷新等关键注意事项client_id为什么不建议自定义spotify-player默认使用 ncspot 项目的 client ID它以扩展配额模式注册且早于 Spotify 2024 年 11 月的 Web API 变更因此比新注册的 App 拥有更高的速率限制与更宽的端点访问。今天新注册的客户端会落入受限的默认配额模式常见429 Too Many Requests/403 Forbidden错误。检测到自定义client_id时程序会在启动时打印警告。从源码看两个客户端 ID 定义在 auth.rsSPOTIFY_CLIENT_ID65b708073fc0480ea92a077233ca87bd与NCSPOT_CLIENT_IDd420a117a32841c2b3474932e49fb54b后者被用作client_id的回退值见 Default for AppConfig 的注释。限流重试机制当 Spotify 返回429时spotify-player会将响应中的Retry-After时长全局存储并对 GET 请求最多重试api_rate_limit_retries次新的 GET 请求会等待处于生效中的Retry-After期间而变更类mutation请求永远不会被延迟或重试。该逻辑实现在 SpotifyApiMiddleware并有单元测试验证“全局存储最长 Retry-After”“等待全局 Retry-After”等行为middleware.rs 测试。ap_port与proxy两者都透传给 Librespot 用于会话配置未设置时 Librespot 使用自身默认值。从源码看AppConfig::session_config 会把proxy解析为 URL 后与ap_port一起构造 Librespot 的SessionConfig解析失败只会记录警告并使用无代理。刷新频率设置正的app_refresh_duration_in_ms会增加 API 用量并可能触发限流。默认playback_refresh_duration_in_ms 0表示仅在事件或命令发生时刷新播放状态。enable_streaming取值接受Always、Never、DaemonOnly为向后兼容true/false也可被接受true等价Alwaysfalse等价Never对应源码 StreamingTypeOrBool。枚举型选项border_type、progress_bar_type、progress_bar_position只接受上表列出的值否则解析失败。explicit_icon可设为任意 Unicode 字符或空字符串以禁用 explicit 标记。cover_img_length 0默认值会根据终端字符单元宽高比自动推导封面列数设置非零值则手动指定封面框尺寸源码注释见 cover_img_length 默认值。CLI 覆盖-o / --config-override不必修改文件也可以临时覆盖任意配置项例如spotify_player -o device.volume80 -o themedracula从 cli/mod.rs 看该参数可重复使用main.rs 依次对每个keyvalue调用 apply_config_override。其实现是把当前AppConfig序列化为 TOML按点号路径导航到目标键写入新值再反序列化回结构体——因此键路径必须有效如device.volume值类型不匹配会直接报错。Media controlenable_media_control在 Linux 上默认开启在 macOS 和 Windows 上默认关闭。原因是这两个平台的系统要求有一个打开的窗口才能接收媒体事件启动时可能导致终端失去焦点。源码中的默认值分支 enable_media_control 正是这样实现的unix非 macOS为truemacOS/Windows 为false。Player event hook commandplayer_event_hook_command是带command与args两个字段的对象。每当播放事件发生时程序以事件数据作为参数执行该命令。一个播放事件表现为以下四种参数列表之一Changed NEW_TRACK_IDPlaying TRACK_ID POSITION_MSPaused TRACK_ID POSITION_MSEndOfTrack TRACK_ID注意如果指定了args这些参数会排在事件参数之前。例如配置player_event_hook_command { command a.sh, args [-b, c, -d] }时Changed事件NEW_TRACK_IDid实际执行的命令是a.sh -b c -d Changed id从源码看命令由 Command::execute 执行先把self.args与额外参数事件参数拼接再交给子进程执行失败时把 stderr 作为错误抛出。一个读取事件参数并写入日志的示例脚本#!/bin/bash set -euo pipefail case $1 in Changed) echo command: $1, new_track_id: $2 /tmp/log.txt ;; Playing) echo command: $1, track_id: $2, position_ms: $3 /tmp/log.txt ;; Paused) echo command: $1, track_id: $2, position_ms: $3 /tmp/log.txt ;; EndOfTrack) echo command: $1, track_id: $2 /tmp/log.txt ;; esacClient id command如果不想把client_id明文写进配置文件可用client_id_command以command 可选args的形式动态获取例如client_id_command { command cat, args [/full/path/to/file] }注意必须使用绝对路径~不会被展开。程序最终取得的是该命令的 stdoutAppConfig::get_client_id设置了client_id_command时执行并 trim 其 stdout否则返回client_id。Device configuration[device]段的选项如下选项说明默认值name设备名称。spotify-playerdevice_type设备类型。speakervolume初始音量百分比。70bitrate码率 kbps96、160或320。320audio_cache启用音频文件缓存。falsenormalization启用音频响度标准化。falseautoplay启用相似歌曲自动播放。false这些选项对应 DeviceConfig 结构体默认值在 Default for DeviceConfig 中定义其中autoplay会通过session_config传给 Librespot 的SessionConfig。Layout configuration[layout]段控制 UI 布局选项说明默认值library.album_percent专辑窗口在 library 中占据的百分比。40library.playlist_percent播放列表窗口在 library 中占据的百分比。40playback_window_position播放窗口位置Top或Bottom。Topplayback_window_height播放窗口高度。6示例[layout] library { album_percent 40, playlist_percent 40 } playback_window_position Top从源码看配置加载后会做一次校验LayoutConfig::check_values 要求album_percent playlist_percent 99否则直接报错退出——所以两个百分比之和不能设为 100。Themestheme.toml 主题定制spotify_player使用theme.toml定义自定义主题样例见 examples/theme.toml。主题可通过app.toml的theme项或 CLI 的-t THEME/--theme THEME选择cli/mod.rs 定义了该参数。一个主题由三部分组成name必填主题名。palette可选调色板。component_style可选UI 组件样式。省略的palette值使用终端颜色省略的component_style值使用默认样式。从源码看theme.toml解析出的主题会与内置主题合并同名时保留已存在的内置主题ThemeConfig::parse_config_file这一点在调试“为什么我的主题没生效”时很有用。Component Stylescomponent_style表用于定制各 UI 组件外观所有字段都是可选的字段说明block_title块标题样式border边框样式playback_status播放状态指示器样式playback_track当前曲目名样式playback_artists当前曲目艺术家样式playback_album当前曲目专辑名样式playback_genres当前曲目流派样式playback_metadata播放窗口元数据区样式playback_progress_bar播放进度条已填充部分样式playback_progress_bar_unfilled进度条未填充部分样式仅Line类型current_playing列表中正在播放的条目样式page_desc页面描述样式playlist_desc播放列表描述样式table_header表头样式selection选中项样式secondary_row表/列表中的次级行样式like收藏指示器样式lyrics_played已播放歌词行样式lyrics_playing正在播放的歌词行样式这些字段与源码中 ComponentStyle 结构体 完全一致。每个样式接受三个可选字段fg前景色bg背景色modifiers样式修饰符列表未指定的部分回退到调色板值或保持未设置。示例[[themes]] name my_theme [themes.component_style] block_title { fg Magenta, modifiers [Bold] } border { fg White } selection { modifiers [Reversed, Bold] }默认组件样式block_title { fg Magenta } border {} playback_status { fg Cyan, modifiers [Bold] } playback_track { fg Cyan, modifiers [Bold] } playback_artists { fg Cyan, modifiers [Bold] } playback_album { fg Yellow } playback_genres { fg BrightBlack, modifiers [Italic] } playback_metadata { fg BrightBlack } playback_progress_bar { bg BrightBlack, fg Green } playback_progress_bar_unfilled { bg BrightBlack } current_playing { fg Green, modifiers [Bold] } page_desc { fg Cyan, modifiers [Bold] } playlist_desc { fg BrightBlack, modifiers [Dim] } table_header { fg Blue } selection { modifiers [Reversed, Bold] } secondary_row {} like {} lyrics_played { modifiers [Dim] } lyrics_playing { fg Green, modifiers [Bold] }可接受的颜色颜色可以是基础色Black、Blue、Cyan、Green、Magenta、Red、White、Yellow亮色BrightBlack、BrightWhite、BrightRed、BrightMagenta、BrightGreen、BrightCyan、BrightBlue、BrightYellow十六进制#RRGGBB如#ff0000源码中的 StyleColor 枚举 正是这些命名色加一个Rgb { r, g, b }变体。样式修饰符支持的修饰符Bold、Dim、Italic、Underlined、RapidBlink、Reversed、Hidden、CrossedOut。多个修饰符以列表形式给出modifiers [Bold, Underlined]。对应 StyleModifier 枚举。用脚本批量添加主题仓库提供 Python 脚本 scripts/theme_parse依赖toml与requests用于把 iTerm2/alacritty 社区的配色方案转换为 spotify-player 兼容的主题格式。例如./theme_parse Builtin Solarized Dark solarized_dark ~/.config/spotify-player/theme.toml这会把 Builtin Solarized Dark 配色转成名为solarized_dark的主题。从脚本源码看它按theme_name [theme_saved_name]两个参数工作拉取对应方案的 TOML再按固定模板打印[[themes]][themes.palette]片段到 stdout因此用追加到theme.toml即可一次添加多个主题。Palette主题的palette表可以包含以下字段background、foregroundblack、blue、cyan、green、magenta、red、white、yellowbright_black、bright_blue、bright_cyan、bright_green、bright_magenta、bright_red、bright_white、bright_yellow省略的字段使用终端默认值取值可以是颜色名或十六进制代码。对照源码 Palette 结构体background/foreground是Option默认None即沿用终端背景/前景其余 16 个基础色默认映射到终端 ANSI 颜色——例如white映射为Gray、bright_black映射为DarkGray、bright_white映射为White见 Color 构造函数。仓库自带的 examples/theme.toml 中就包含dracula、gruvbox_dark/light、solarized_dark/light、tokyonight、catppuccin_latte/frappe/macchiato/mocha等完整十六进制主题可以直接抄作业。Keymapskeymap.toml 键位映射spotify_player使用keymap.toml新增或覆盖默认按键映射。添加keymaps条目即可定义新映射把command设为None可以移除某个默认映射。示例[[keymaps]] command NextTrack key_sequence g n [[keymaps]] command PreviousTrack key_sequence g p [[keymaps]] command Search key_sequence C-c C-x / [[keymaps]] command ResumePause key_sequence M-enter [[keymaps]] command None key_sequence q [[keymaps]] command { VolumeChange { offset 1 } } key_sequence - [[keymaps]] command { SeekForward { duration 10 } } key_sequence E [[keymaps]] command { SeekBackward { } } key_sequence Q合并语义值得注意keymap.toml中的条目会覆盖同键序列的默认映射新键序列则被追加KeymapConfig::parse_config_file 中先 swap 再按key_sequence去重合并。默认键位本身定义在 Default for KeymapConfig例如n/p切歌、space暂停/继续、/搜索、z队列、tab/backtab切窗口、g y已收藏、q/C-c退出等。查找映射时优先返回command ! None的键位find_command_from_key_sequence且Command::None的映射不会出现在帮助界面include_in_help_screen。完整的命令actions列表参见 README。Actions按键触发的动作Actions 同样在keymap.toml中定义由未绑定命令的按键序列触发。Action 默认作用于选中项selected item也可以通过target设为PlayingTrack或SelectedItem。可用的 actions 列表见 README 与 docs/config.md 的引用说明。示例[[actions]] action GoToArtist key_sequence g A [[actions]] action GoToAlbum key_sequence g B target PlayingTrack [[actions]] actionToggleLiked key_sequenceC-l源码中对应 ActionMap 结构体target字段带#[serde(default)]即省略时为默认目标按键匹配逻辑见 find_action_from_key_sequence。小结三份配置的分工与常见坑app.toml所有“行为与外观”的总开关首次运行自动生成不确定含义时对照 Default for AppConfig 即可找到每个字段的出厂值。theme.toml只负责“配色”同名主题不覆盖内置主题写好后用theme ...或-t生效。keymap.toml负责“手感”可加键、改键、删键command None也可用[[actions]]绑定针对选中项/当前曲目的动作。临时改配置优先用-o keyvalue覆盖避免污染文件涉及限流的参数api_rate_limit_retries、app_refresh_duration_in_ms、playback_refresh_duration_in_ms要理解其对 API 用量的影响。自定义client_id前务必确认配额模式问题确需保存 ID 时用client_id_command 绝对路径。【免费下载链接】spotify-playerA Spotify player in the terminal with full feature parity项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-player创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
spotify-player 配置系统详解app.toml、theme.toml、keymap.toml 全参数参考【免费下载链接】spotify-playerA Spotify player in the terminal with full feature parity项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-playerspotify-player是一款在终端中运行的完整功能 Spotify 播放器其行为几乎全部由位于$HOME/.config/spotify-player下的三个 TOML 配置文件驱动app.toml应用设置、theme.toml主题与keymap.toml按键映射。本文以仓库中的 docs/config.md 为骨架完整覆盖全部配置项、默认值与实操示例并结合 config 模块源码 说明配置如何被加载、校验与覆盖帮助你快速定制属于自己的终端播放器。配置文件的位置与加载机制三个配置文件都位于应用配置目录中默认为$HOME/.config/spotify-player缓存目录为$HOME/.cache/spotify-player文件作用缺失时行为app.toml应用设置主题、设备、布局、刷新、通知等自动生成一份默认配置theme.toml自定义主题调色板 组件样式使用内置主题仅记录警告keymap.toml新增或覆盖按键映射 / Actions使用默认键位仅记录警告这一行为在源码中得到印证。AppConfig::new 中若解析不到配置文件则调用write_config_file把当前默认值序列化为 TOML 写出——这就是首次运行后app.toml会自动出现的原因。而theme.toml/keymap.toml解析失败时只会tracing::warn!并使用默认值见 ThemeConfig::parse_config_file 与 KeymapConfig::parse_config_file。一份完整的示例配置见 examples/app.toml。Generalapp.toml 全选项spotify_player使用app.toml管理应用设置。完整选项表如下与 docs/config.md 中的 General 表格一致选项说明默认值client_id访问 API 的 Spotify client ID。除非确定需要否则保持不设置见 Notes。代码内默认ncspot 的 client IDclient_id_command向 stdout 输出 client ID 的 shell 命令覆盖client_id。Nonelogin_redirect_uri认证时的重定向 URI。http://127.0.0.1:8989/loginclient_port应用用于处理 CLI 命令的客户端端口。8080log_folder日志文件存储路径。Nonetracks_playback_limit一次播放会话中的最大曲目数。50playback_format播放窗口的格式字符串。{status} {track} • {artists} {liked}\n{album} • {genres}\n{metadata}playback_metadata_fields{metadata}占位符中显示的元数据字段顺序。[repeat, shuffle, volume, device]notify_format通知格式需启用notify特性。{ summary {track} • {artists}, body {album} }notify_timeout_in_secs通知超时秒数需启用notify特性。0notify_transient发送瞬态通知仅 Linux需notify特性。falseplayer_event_hook_command播放事件触发时执行的命令。Noneap_portSpotify 会话连接端口。NoneproxySpotify 会话连接代理。Nonetheme要使用的主题名。defaultapp_refresh_duration_in_ms应用刷新间隔毫秒。32playback_refresh_duration_in_ms播放刷新间隔毫秒。0api_rate_limit_retriesSpotify 返回429 Too Many Requests后 GET 请求的重试次数。2page_size_in_rows导航时每页的行数。20enable_media_control启用媒体控制支持需media-control特性。Linux 为truemacOS/Windows 为falseenable_streaming启用流媒体Always、Never或DaemonOnly。Alwaysenable_audio_visualization在播放窗口显示实时频谱柱状图需streaming特性。falseenable_notify启用通知需notify特性。trueenable_cover_image_cache缓存专辑封面图。truenotify_streaming_only仅在流媒体激活时发送通知需streaming与notify特性。falseplay_icon播放状态图标。▶pause_icon暂停状态图标。▌▌liked_icon已收藏歌曲图标。♥explicit_icon强内容explicit歌曲图标。(E)border_type边框样式Hidden、Plain、Rounded、Double或Thick。Plainprogress_bar_type进度条样式Rectangle或Line。Rectangleprogress_bar_position进度条位置Bottom或Right。Bottomlayout布局配置见下文 Layout 小节。见下文genre_num播放文本中显示的最大流派数。2cover_img_length封面图在终端中的列数需image特性。0自动见 Notescover_img_width封面图在终端中的行数需image特性。5cover_img_pixels封面图每侧像素数需pixelate特性。16seek_duration_secsseek 命令的跳转秒数。5sort_artist_albums_by_type艺术家页面按类型排序专辑。falsevolume_scroll_step鼠标滚轮调节音量的步长。5enable_mouse_scroll_volume启用鼠标滚轮音量控制。falsecustom_queue启用应用自管队列以支持自定义播放集成需streaming特性。truepause_on_startup启动时以暂停状态开始而非恢复上次会话需streaming特性。falseenable_relative_line_number为列表与弹窗启用 Vim 风格相对行号。falsedevice设备配置见下文 Device 小节。见下文这些字段在 AppConfig 结构体 中一一对应多数默认值可通过 Default for AppConfig 核对部分字段带#[cfg(feature ...)]只有编译时启用了相应 cargo feature 才真正生效。Notesclient_id、限流与刷新等关键注意事项client_id为什么不建议自定义spotify-player默认使用 ncspot 项目的 client ID它以扩展配额模式注册且早于 Spotify 2024 年 11 月的 Web API 变更因此比新注册的 App 拥有更高的速率限制与更宽的端点访问。今天新注册的客户端会落入受限的默认配额模式常见429 Too Many Requests/403 Forbidden错误。检测到自定义client_id时程序会在启动时打印警告。从源码看两个客户端 ID 定义在 auth.rsSPOTIFY_CLIENT_ID65b708073fc0480ea92a077233ca87bd与NCSPOT_CLIENT_IDd420a117a32841c2b3474932e49fb54b后者被用作client_id的回退值见 Default for AppConfig 的注释。限流重试机制当 Spotify 返回429时spotify-player会将响应中的Retry-After时长全局存储并对 GET 请求最多重试api_rate_limit_retries次新的 GET 请求会等待处于生效中的Retry-After期间而变更类mutation请求永远不会被延迟或重试。该逻辑实现在 SpotifyApiMiddleware并有单元测试验证“全局存储最长 Retry-After”“等待全局 Retry-After”等行为middleware.rs 测试。ap_port与proxy两者都透传给 Librespot 用于会话配置未设置时 Librespot 使用自身默认值。从源码看AppConfig::session_config 会把proxy解析为 URL 后与ap_port一起构造 Librespot 的SessionConfig解析失败只会记录警告并使用无代理。刷新频率设置正的app_refresh_duration_in_ms会增加 API 用量并可能触发限流。默认playback_refresh_duration_in_ms 0表示仅在事件或命令发生时刷新播放状态。enable_streaming取值接受Always、Never、DaemonOnly为向后兼容true/false也可被接受true等价Alwaysfalse等价Never对应源码 StreamingTypeOrBool。枚举型选项border_type、progress_bar_type、progress_bar_position只接受上表列出的值否则解析失败。explicit_icon可设为任意 Unicode 字符或空字符串以禁用 explicit 标记。cover_img_length 0默认值会根据终端字符单元宽高比自动推导封面列数设置非零值则手动指定封面框尺寸源码注释见 cover_img_length 默认值。CLI 覆盖-o / --config-override不必修改文件也可以临时覆盖任意配置项例如spotify_player -o device.volume80 -o themedracula从 cli/mod.rs 看该参数可重复使用main.rs 依次对每个keyvalue调用 apply_config_override。其实现是把当前AppConfig序列化为 TOML按点号路径导航到目标键写入新值再反序列化回结构体——因此键路径必须有效如device.volume值类型不匹配会直接报错。Media controlenable_media_control在 Linux 上默认开启在 macOS 和 Windows 上默认关闭。原因是这两个平台的系统要求有一个打开的窗口才能接收媒体事件启动时可能导致终端失去焦点。源码中的默认值分支 enable_media_control 正是这样实现的unix非 macOS为truemacOS/Windows 为false。Player event hook commandplayer_event_hook_command是带command与args两个字段的对象。每当播放事件发生时程序以事件数据作为参数执行该命令。一个播放事件表现为以下四种参数列表之一Changed NEW_TRACK_IDPlaying TRACK_ID POSITION_MSPaused TRACK_ID POSITION_MSEndOfTrack TRACK_ID注意如果指定了args这些参数会排在事件参数之前。例如配置player_event_hook_command { command a.sh, args [-b, c, -d] }时Changed事件NEW_TRACK_IDid实际执行的命令是a.sh -b c -d Changed id从源码看命令由 Command::execute 执行先把self.args与额外参数事件参数拼接再交给子进程执行失败时把 stderr 作为错误抛出。一个读取事件参数并写入日志的示例脚本#!/bin/bash set -euo pipefail case $1 in Changed) echo command: $1, new_track_id: $2 /tmp/log.txt ;; Playing) echo command: $1, track_id: $2, position_ms: $3 /tmp/log.txt ;; Paused) echo command: $1, track_id: $2, position_ms: $3 /tmp/log.txt ;; EndOfTrack) echo command: $1, track_id: $2 /tmp/log.txt ;; esacClient id command如果不想把client_id明文写进配置文件可用client_id_command以command 可选args的形式动态获取例如client_id_command { command cat, args [/full/path/to/file] }注意必须使用绝对路径~不会被展开。程序最终取得的是该命令的 stdoutAppConfig::get_client_id设置了client_id_command时执行并 trim 其 stdout否则返回client_id。Device configuration[device]段的选项如下选项说明默认值name设备名称。spotify-playerdevice_type设备类型。speakervolume初始音量百分比。70bitrate码率 kbps96、160或320。320audio_cache启用音频文件缓存。falsenormalization启用音频响度标准化。falseautoplay启用相似歌曲自动播放。false这些选项对应 DeviceConfig 结构体默认值在 Default for DeviceConfig 中定义其中autoplay会通过session_config传给 Librespot 的SessionConfig。Layout configuration[layout]段控制 UI 布局选项说明默认值library.album_percent专辑窗口在 library 中占据的百分比。40library.playlist_percent播放列表窗口在 library 中占据的百分比。40playback_window_position播放窗口位置Top或Bottom。Topplayback_window_height播放窗口高度。6示例[layout] library { album_percent 40, playlist_percent 40 } playback_window_position Top从源码看配置加载后会做一次校验LayoutConfig::check_values 要求album_percent playlist_percent 99否则直接报错退出——所以两个百分比之和不能设为 100。Themestheme.toml 主题定制spotify_player使用theme.toml定义自定义主题样例见 examples/theme.toml。主题可通过app.toml的theme项或 CLI 的-t THEME/--theme THEME选择cli/mod.rs 定义了该参数。一个主题由三部分组成name必填主题名。palette可选调色板。component_style可选UI 组件样式。省略的palette值使用终端颜色省略的component_style值使用默认样式。从源码看theme.toml解析出的主题会与内置主题合并同名时保留已存在的内置主题ThemeConfig::parse_config_file这一点在调试“为什么我的主题没生效”时很有用。Component Stylescomponent_style表用于定制各 UI 组件外观所有字段都是可选的字段说明block_title块标题样式border边框样式playback_status播放状态指示器样式playback_track当前曲目名样式playback_artists当前曲目艺术家样式playback_album当前曲目专辑名样式playback_genres当前曲目流派样式playback_metadata播放窗口元数据区样式playback_progress_bar播放进度条已填充部分样式playback_progress_bar_unfilled进度条未填充部分样式仅Line类型current_playing列表中正在播放的条目样式page_desc页面描述样式playlist_desc播放列表描述样式table_header表头样式selection选中项样式secondary_row表/列表中的次级行样式like收藏指示器样式lyrics_played已播放歌词行样式lyrics_playing正在播放的歌词行样式这些字段与源码中 ComponentStyle 结构体 完全一致。每个样式接受三个可选字段fg前景色bg背景色modifiers样式修饰符列表未指定的部分回退到调色板值或保持未设置。示例[[themes]] name my_theme [themes.component_style] block_title { fg Magenta, modifiers [Bold] } border { fg White } selection { modifiers [Reversed, Bold] }默认组件样式block_title { fg Magenta } border {} playback_status { fg Cyan, modifiers [Bold] } playback_track { fg Cyan, modifiers [Bold] } playback_artists { fg Cyan, modifiers [Bold] } playback_album { fg Yellow } playback_genres { fg BrightBlack, modifiers [Italic] } playback_metadata { fg BrightBlack } playback_progress_bar { bg BrightBlack, fg Green } playback_progress_bar_unfilled { bg BrightBlack } current_playing { fg Green, modifiers [Bold] } page_desc { fg Cyan, modifiers [Bold] } playlist_desc { fg BrightBlack, modifiers [Dim] } table_header { fg Blue } selection { modifiers [Reversed, Bold] } secondary_row {} like {} lyrics_played { modifiers [Dim] } lyrics_playing { fg Green, modifiers [Bold] }可接受的颜色颜色可以是基础色Black、Blue、Cyan、Green、Magenta、Red、White、Yellow亮色BrightBlack、BrightWhite、BrightRed、BrightMagenta、BrightGreen、BrightCyan、BrightBlue、BrightYellow十六进制#RRGGBB如#ff0000源码中的 StyleColor 枚举 正是这些命名色加一个Rgb { r, g, b }变体。样式修饰符支持的修饰符Bold、Dim、Italic、Underlined、RapidBlink、Reversed、Hidden、CrossedOut。多个修饰符以列表形式给出modifiers [Bold, Underlined]。对应 StyleModifier 枚举。用脚本批量添加主题仓库提供 Python 脚本 scripts/theme_parse依赖toml与requests用于把 iTerm2/alacritty 社区的配色方案转换为 spotify-player 兼容的主题格式。例如./theme_parse Builtin Solarized Dark solarized_dark ~/.config/spotify-player/theme.toml这会把 Builtin Solarized Dark 配色转成名为solarized_dark的主题。从脚本源码看它按theme_name [theme_saved_name]两个参数工作拉取对应方案的 TOML再按固定模板打印[[themes]][themes.palette]片段到 stdout因此用追加到theme.toml即可一次添加多个主题。Palette主题的palette表可以包含以下字段background、foregroundblack、blue、cyan、green、magenta、red、white、yellowbright_black、bright_blue、bright_cyan、bright_green、bright_magenta、bright_red、bright_white、bright_yellow省略的字段使用终端默认值取值可以是颜色名或十六进制代码。对照源码 Palette 结构体background/foreground是Option默认None即沿用终端背景/前景其余 16 个基础色默认映射到终端 ANSI 颜色——例如white映射为Gray、bright_black映射为DarkGray、bright_white映射为White见 Color 构造函数。仓库自带的 examples/theme.toml 中就包含dracula、gruvbox_dark/light、solarized_dark/light、tokyonight、catppuccin_latte/frappe/macchiato/mocha等完整十六进制主题可以直接抄作业。Keymapskeymap.toml 键位映射spotify_player使用keymap.toml新增或覆盖默认按键映射。添加keymaps条目即可定义新映射把command设为None可以移除某个默认映射。示例[[keymaps]] command NextTrack key_sequence g n [[keymaps]] command PreviousTrack key_sequence g p [[keymaps]] command Search key_sequence C-c C-x / [[keymaps]] command ResumePause key_sequence M-enter [[keymaps]] command None key_sequence q [[keymaps]] command { VolumeChange { offset 1 } } key_sequence - [[keymaps]] command { SeekForward { duration 10 } } key_sequence E [[keymaps]] command { SeekBackward { } } key_sequence Q合并语义值得注意keymap.toml中的条目会覆盖同键序列的默认映射新键序列则被追加KeymapConfig::parse_config_file 中先 swap 再按key_sequence去重合并。默认键位本身定义在 Default for KeymapConfig例如n/p切歌、space暂停/继续、/搜索、z队列、tab/backtab切窗口、g y已收藏、q/C-c退出等。查找映射时优先返回command ! None的键位find_command_from_key_sequence且Command::None的映射不会出现在帮助界面include_in_help_screen。完整的命令actions列表参见 README。Actions按键触发的动作Actions 同样在keymap.toml中定义由未绑定命令的按键序列触发。Action 默认作用于选中项selected item也可以通过target设为PlayingTrack或SelectedItem。可用的 actions 列表见 README 与 docs/config.md 的引用说明。示例[[actions]] action GoToArtist key_sequence g A [[actions]] action GoToAlbum key_sequence g B target PlayingTrack [[actions]] actionToggleLiked key_sequenceC-l源码中对应 ActionMap 结构体target字段带#[serde(default)]即省略时为默认目标按键匹配逻辑见 find_action_from_key_sequence。小结三份配置的分工与常见坑app.toml所有“行为与外观”的总开关首次运行自动生成不确定含义时对照 Default for AppConfig 即可找到每个字段的出厂值。theme.toml只负责“配色”同名主题不覆盖内置主题写好后用theme ...或-t生效。keymap.toml负责“手感”可加键、改键、删键command None也可用[[actions]]绑定针对选中项/当前曲目的动作。临时改配置优先用-o keyvalue覆盖避免污染文件涉及限流的参数api_rate_limit_retries、app_refresh_duration_in_ms、playback_refresh_duration_in_ms要理解其对 API 用量的影响。自定义client_id前务必确认配额模式问题确需保存 ID 时用client_id_command 绝对路径。【免费下载链接】spotify-playerA Spotify player in the terminal with full feature parity项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-player创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
