aome510/spotify-player
GitHub: aome510/spotify-player
一款基于 Rust 开发的高性能终端 Spotify 播放器，提供与官方客户端功能对等的命令行音乐播放与控制体验。
Stars: 6477 | Forks: 334
# spotify_player
## 目录
- [简介](#introduction)
- [示例](#examples)
- [安装](#installation)
- [功能](#features)
- [Spotify Connect](#spotify-connect)
- [流媒体播放](#streaming)
- [音频可视化](#audio-visualization)
- [媒体控制](#media-control)
- [图像](#image)
- [通知](#notify)
- [鼠标支持](
| 
| 
|
要临时禁用像素化，请将 `cover_img_pixels` 设置为一个较高的值（例如 `512`）。
### 通知
要启用桌面通知，请使用 `notify` 功能进行构建（默认禁用）：
```
cargo install spotify_player --features notify
```
**注意**：与 Linux 相比，macOS 和 Windows 上的通知支持有所限制。
### 鼠标支持
鼠标支持：您可以通过左键单击进度条来定位到播放中的某个位置。
### Daemon
要启用 daemon 模式，请使用 `daemon` 功能进行构建（默认禁用）：
```
cargo install spotify_player --features daemon
```
使用 `-d` 或 `--daemon` 作为 daemon 运行：`spotify_player -d`。
**注意**：
- Windows 不支持 daemon 模式。
- Daemon 模式需要流媒体播放功能和音频后端。
- 在 macOS 上，daemon 模式不兼容媒体控制（默认启用）。要在 macOS 上使用 daemon 模式，请禁用媒体控制：
cargo install spotify_player --no-default-features --features daemon,rodio-backend
### 模糊搜索
要启用[模糊搜索](https://en.wikipedia.org/wiki/Approximate_string_matching)，请使用 `fzf` 功能进行构建（默认禁用）。
### CLI 命令
`spotify_player` 提供了几个用于与 Spotify 交互的 CLI 命令：
- `get`：获取 Spotify 数据（播放列表/专辑/艺术家数据、用户数据等）
- `playback`：与播放交互（开始播放、播放/暂停、下一首等）
- `search`：搜索 spotify
- `connect`：连接到 Spotify 设备
- `like`： liking 当前播放的曲目
- `authenticate`：验证应用程序
- `playlist`：播放列表编辑（新建、删除、导入、派生等）
有关更多详细信息，请运行 `spotify_player -h` 或 `spotify_player {command} -h`。
**注意**
- 首次使用时，请运行 `spotify_player authenticate` 来验证应用程序。
- CLI 命令通过端口 `client_port`（默认：`8080`）上的客户端 socket 进行通信。如果没有实例在运行，则会启动一个新的客户端，这可能会增加延迟。
#### 脚本编写
命令行界面非常易于编写脚本。使用 `search` 子命令以 JSON 格式检索 Spotify 数据，然后可以使用 [jq](https://jqlang.github.io/jq/) 等工具进行处理。
示例：开始播放搜索查询中的第一首曲目：
```
read -p "Search spotify: " query
spotify_player playback start track --id $(spotify_player search "$query" | jq '.tracks.[0].id' | xargs)
```
## 命令
按 `` 或 `C-h` 打开快捷键帮助页面（`OpenCommandHelp` 的默认设置）。
**提示**：
- 使用 `Search` 命令在快捷键帮助页面和其他页面中进行搜索。
- `RefreshPlayback` 手动更新播放状态。
- `RestartIntegratedClient` 可用于切换音频设备而无需重启应用程序。
支持的命令列表：
| Command | Description | Default shortcuts |
| ------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------ |
| `NextTrack` | 下一首曲目 | `n` |
| `PreviousTrack` | 上一首曲目 | `p` |
| `ResumePause` | 根据当前播放状态恢复/暂停 | `space` |
| `PlayRandom` | 在当前上下文中播放随机曲目 | `.` |
| `Repeat` | 循环切换循环模式 | `C-r` |
| `Shuffle` | 切换随机播放模式 | `C-s` |
| `VolumeChange` | 按偏移量更改播放音量（默认快捷键使用 5%） | `+`, `-` |
| `Mute` | 在 0% 和先前音量之间切换播放音量 | `_` |
| `SeekStart` | 跳至当前曲目开头 | `^` |
| `SeekForward` | 按秒数快进（默认为 `seek_duration_secs`） | `>` |
| `SeekBackward` | 按秒数快退（默认为 `seek_duration_secs`） | `<` |
| `Quit` | 退出应用程序 | `C-c`, `q` |
| `ClosePopup` | 关闭弹出窗口 | `esc` |
| `SelectNextOrScrollDown` | 在列表/表中选择下一个项目或向下滚动（支持 vim 风格的计数：5j） | `j`, `C-n`, `down` |
| `SelectPreviousOrScrollUp` | 在列表/表中选择上一个项目或向上滚动（支持 vim 风格的计数：10k） | `k`, `C-p`, `up` |
| `PageSelectNextOrScrollDown` | 在列表/表中选择下一页项目或向下滚动一页（支持 vim 风格的计数：3C-f） | `page_down`, `C-f` |
| `PageSelectPreviousOrScrollUp` | 在列表/表中选择上一页项目或向上滚动一页（支持 vim 风格的计数：2C-b） | `page_up`, `C-b` |
| `SelectFirstOrScrollToTop` | 在列表/表中选择第一个项目或滚动到顶部 | `g g`, `home` |
| `SelectLastOrScrollToBottom` | 在列表/表中选择最后一个项目或滚动到底部 | `G`, `end` |
| `ChooseSelected` | 选择当前高亮的项目 | `enter` |
| `RefreshPlayback` | 手动刷新当前播放状态 | `r` |
| `RestartIntegratedClient` | 重新启动集成客户端（仅限 `streaming` 功能） | `R` |
| `ShowActionsOnSelectedItem` | 打开一个弹出窗口，显示针对所选项目的操作 | `g a`, `C-space` |
| `ShowActionsOnCurrentTrack` | 打开一个弹出窗口，显示针对当前曲目的操作 | `a` |
| `ShowActionsOnCurrentContext` | 打开一个弹出窗口，显示针对当前上下文的操作 | `A` |
| `AddSelectedItemToQueue` | 将所选项目添加到队列 | `Z`, `C-z` |
| `FocusNextWindow` | 聚焦到下一个可聚焦的窗口（如果有的话） | `tab` |
| `FocusPreviousWindow` | 聚焦到上一个可聚焦的窗口（如果有的话） | `backtab` |
| `SwitchTheme` | 打开一个用于切换主题的弹出窗口 | `T` |
| `SwitchDevice` | 打开一个用于切换设备的弹出窗口 | `D` |
| `Search` | 打开一个用于在当前页面中搜索的弹出窗口 | `/` |
| `BrowseUserPlaylists` | 打开一个用于浏览用户播放列表的弹出窗口 | `u p` |
| `BrowseUserFollowedArtists` | 打开一个用于浏览用户关注的艺术家的弹出窗口 | `u a` |
| `BrowseUserSavedAlbums` | 打开一个用于浏览用户保存的专辑的弹出窗口 | `u A` |
| `CurrentlyPlayingContextPage` | 转到当前正在播放的上下文页面 | `g space` |
| `TopTrackPage` | 转到用户热门曲目页面 | `g t` |
| `RecentlyPlayedTrackPage` | 转到用户最近播放的曲目页面 | `g r` |
| `LikedTrackPage` | 转到用户喜欢的曲目页面 | `g y` |
| `LyricsPage` | 转到当前曲目的歌词页面 | `g L`, `l` |
| `LibraryPage` | 转到用户资料库页面 | `g l` |
| `SearchPage` | 转到搜索页面 | `g s` |
| `BrowsePage` | 转到浏览页面 | `g b` |
| `Queue` | 转到队列页面 | `z` |
| `OpenCommandHelp` | 转到命令帮助页面 | `?`, `C-h` |
| `PreviousPage` | 转到上一页 | `backspace`, `C-q` |
| `OpenSpotifyLinkFromClipboard` | 从剪贴板打开 Spotify 链接 | `O` |
| `SortTrackByTitle` | 按曲目标题对曲目表（如果有的话）进行排序 | `s t` |
| `SortTrackByArtists` | 按曲目的艺术家对曲目表（如果有的话）进行排序 | `s a` |
| `SortTrackByAlbum` | 按曲目的专辑对曲目表（如果有的话）进行排序 | `s A` |
| `SortTrackByAddedDate` | 按曲目的添加日期对曲目表（如果有的话）进行排序 | `s D` |
| `SortTrackByDuration` | 按曲目的时长对曲目表（如果有的话）进行排序 | `s d` |
| `SortLibraryAlphabetically` | 按字母顺序对资料库进行排序 | `s l a` |
| `SortLibraryByRecent` | 按最近添加的项目对资料库（播放列表和专辑）进行排序 | `s l r` |
| `ReverseOrder` | 反转曲目表（如果有的话）的顺序 | `s r` |
| `MovePlaylistItemUp` | 将播放列表项目向上移动一个位置 | `C-k` |
| `MovePlaylistItemDown` | 将播放列表项目向下移动一个位置 | `C-j` |
| `CreatePlaylist` | 创建一个新的播放列表 | `N` |
| `JumpToCurrentTrackInContext` | 跳转到上下文中的当前曲目 | `g c` |
| `JumpToHighlightTrackInContext` | 跳转到上下文中当前高亮显示的搜索结果 | `C-g` |
要添加或修改快捷键，请参见 [快捷键映射部分](https://github.com/aome510/spotify-player/blob/master/docs/config.md#keymaps)。
### 操作
并非所有操作都适用于每个 Spotify 项目。要查看可用操作，请使用 `ShowActionsOnCurrentTrack` 或 `ShowActionsOnSelectedItem`，然后按回车键触发操作。某些操作可能不会出现在弹出窗口中，但可以绑定到快捷键。
可用操作列表：
- `GoToArtist`
- `GoToAlbum`
- `GoToRadio`
- `AddToLibrary`
- `AddToPlaylist`
- `AddToQueue`
- `AddToLiked`
- `DeleteFromLiked`
- `DeleteFromLibrary`
- `DeleteFromPlaylist`
- `ShowActionsOnAlbum`
- `ShowActionsOnArtist`
- `ShowActionsOnShow`
- `ToggleLiked`
- `CopyLink`
- `Follow`
- `Unfollow`
操作也可以绑定到快捷键。要添加新的快捷键，请参见 [操作部分](https://github.com/aome510/spotify-player/blob/master/docs/config.md#actions)。
### 搜索页面
进入搜索页面时，焦点位于搜索输入框中。输入文本，使用 `backspace` 删除，按 `enter` 进行搜索。
要将焦点从搜索输入框移动到其他窗口（曲目结果、专辑结果等），请使用 `FocusNextWindow` 或 `FocusPreviousWindow`。
## 配置
默认情况下，配置文件位于 `$HOME/.config/spotify_player`。使用 `-c ` 或 `--config-folder ` 更改此路径。
如果找不到配置文件，将使用默认值创建一个。
有关可用选项的详细信息，请参见 [配置文档](https://github.com/aome510/spotify-player/blob/master/docs/config.md)。
## 缓存
默认情况下，缓存文件存储在 `$HOME/.cache/spotify-player`（日志、凭据、音频缓存等）。使用 `-C ` 或 `--cache-folder ` 更改此路径。
### 日志
日志存储在 `$APP_CACHE_FOLDER/spotify-player-*.log` 中。如需调试或遇到问题，请检查 `$APP_CACHE_FOLDER/spotify-player-*.backtrace` 中的回溯文件。
设置 `RUST_LOG` 环境变量以控制[日志级别](https://docs.rs/log/0.4.14/log/enum.Level.html)。默认为 `spotify_player=INFO`。
## 致谢
`spotify_player` 使用 [Rust](https://www.rust-lang.org) 编写，并基于 [ratatui](https://github.com/ratatui/ratatui)、[rspotify](https://github.com/ramsayleung/rspotify)、[librespot](https://github.com/librespot-org/librespot) 等库构建。它的灵感来源于 [spotify-tui](https://github.com/Rigellute/spotify-tui) 和 [ncspot](https://github.com/hrkfdn/ncspot)。
| | |
要临时禁用像素化，请将 `cover_img_pixels` 设置为一个较高的值（例如 `512`）。
### 通知
要启用桌面通知，请使用 `notify` 功能进行构建（默认禁用）：
```
cargo install spotify_player --features notify
```
**注意**：与 Linux 相比，macOS 和 Windows 上的通知支持有所限制。
### 鼠标支持
鼠标支持：您可以通过左键单击进度条来定位到播放中的某个位置。
### Daemon
要启用 daemon 模式，请使用 `daemon` 功能进行构建（默认禁用）：
```
cargo install spotify_player --features daemon
```
使用 `-d` 或 `--daemon` 作为 daemon 运行：`spotify_player -d`。
**注意**：
- Windows 不支持 daemon 模式。
- Daemon 模式需要流媒体播放功能和音频后端。
- 在 macOS 上，daemon 模式不兼容媒体控制（默认启用）。要在 macOS 上使用 daemon 模式，请禁用媒体控制：
cargo install spotify_player --no-default-features --features daemon,rodio-backend
### 模糊搜索
要启用[模糊搜索](https://en.wikipedia.org/wiki/Approximate_string_matching)，请使用 `fzf` 功能进行构建（默认禁用）。
### CLI 命令
`spotify_player` 提供了几个用于与 Spotify 交互的 CLI 命令：
- `get`：获取 Spotify 数据（播放列表/专辑/艺术家数据、用户数据等）
- `playback`：与播放交互（开始播放、播放/暂停、下一首等）
- `search`：搜索 spotify
- `connect`：连接到 Spotify 设备
- `like`： liking 当前播放的曲目
- `authenticate`：验证应用程序
- `playlist`：播放列表编辑（新建、删除、导入、派生等）
有关更多详细信息，请运行 `spotify_player -h` 或 `spotify_player {command} -h`。
**注意**
- 首次使用时，请运行 `spotify_player authenticate` 来验证应用程序。
- CLI 命令通过端口 `client_port`（默认：`8080`）上的客户端 socket 进行通信。如果没有实例在运行，则会启动一个新的客户端，这可能会增加延迟。
#### 脚本编写
命令行界面非常易于编写脚本。使用 `search` 子命令以 JSON 格式检索 Spotify 数据，然后可以使用 [jq](https://jqlang.github.io/jq/) 等工具进行处理。
示例：开始播放搜索查询中的第一首曲目：
```
read -p "Search spotify: " query
spotify_player playback start track --id $(spotify_player search "$query" | jq '.tracks.[0].id' | xargs)
```
## 命令
按 `` 或 `C-h` 打开快捷键帮助页面（`OpenCommandHelp` 的默认设置）。
**提示**：
- 使用 `Search` 命令在快捷键帮助页面和其他页面中进行搜索。
- `RefreshPlayback` 手动更新播放状态。
- `RestartIntegratedClient` 可用于切换音频设备而无需重启应用程序。
支持的命令列表：
| Command | Description | Default shortcuts |
| ------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------ |
| `NextTrack` | 下一首曲目 | `n` |
| `PreviousTrack` | 上一首曲目 | `p` |
| `ResumePause` | 根据当前播放状态恢复/暂停 | `space` |
| `PlayRandom` | 在当前上下文中播放随机曲目 | `.` |
| `Repeat` | 循环切换循环模式 | `C-r` |
| `Shuffle` | 切换随机播放模式 | `C-s` |
| `VolumeChange` | 按偏移量更改播放音量（默认快捷键使用 5%） | `+`, `-` |
| `Mute` | 在 0% 和先前音量之间切换播放音量 | `_` |
| `SeekStart` | 跳至当前曲目开头 | `^` |
| `SeekForward` | 按秒数快进（默认为 `seek_duration_secs`） | `>` |
| `SeekBackward` | 按秒数快退（默认为 `seek_duration_secs`） | `<` |
| `Quit` | 退出应用程序 | `C-c`, `q` |
| `ClosePopup` | 关闭弹出窗口 | `esc` |
| `SelectNextOrScrollDown` | 在列表/表中选择下一个项目或向下滚动（支持 vim 风格的计数：5j） | `j`, `C-n`, `down` |
| `SelectPreviousOrScrollUp` | 在列表/表中选择上一个项目或向上滚动（支持 vim 风格的计数：10k） | `k`, `C-p`, `up` |
| `PageSelectNextOrScrollDown` | 在列表/表中选择下一页项目或向下滚动一页（支持 vim 风格的计数：3C-f） | `page_down`, `C-f` |
| `PageSelectPreviousOrScrollUp` | 在列表/表中选择上一页项目或向上滚动一页（支持 vim 风格的计数：2C-b） | `page_up`, `C-b` |
| `SelectFirstOrScrollToTop` | 在列表/表中选择第一个项目或滚动到顶部 | `g g`, `home` |
| `SelectLastOrScrollToBottom` | 在列表/表中选择最后一个项目或滚动到底部 | `G`, `end` |
| `ChooseSelected` | 选择当前高亮的项目 | `enter` |
| `RefreshPlayback` | 手动刷新当前播放状态 | `r` |
| `RestartIntegratedClient` | 重新启动集成客户端（仅限 `streaming` 功能） | `R` |
| `ShowActionsOnSelectedItem` | 打开一个弹出窗口，显示针对所选项目的操作 | `g a`, `C-space` |
| `ShowActionsOnCurrentTrack` | 打开一个弹出窗口，显示针对当前曲目的操作 | `a` |
| `ShowActionsOnCurrentContext` | 打开一个弹出窗口，显示针对当前上下文的操作 | `A` |
| `AddSelectedItemToQueue` | 将所选项目添加到队列 | `Z`, `C-z` |
| `FocusNextWindow` | 聚焦到下一个可聚焦的窗口（如果有的话） | `tab` |
| `FocusPreviousWindow` | 聚焦到上一个可聚焦的窗口（如果有的话） | `backtab` |
| `SwitchTheme` | 打开一个用于切换主题的弹出窗口 | `T` |
| `SwitchDevice` | 打开一个用于切换设备的弹出窗口 | `D` |
| `Search` | 打开一个用于在当前页面中搜索的弹出窗口 | `/` |
| `BrowseUserPlaylists` | 打开一个用于浏览用户播放列表的弹出窗口 | `u p` |
| `BrowseUserFollowedArtists` | 打开一个用于浏览用户关注的艺术家的弹出窗口 | `u a` |
| `BrowseUserSavedAlbums` | 打开一个用于浏览用户保存的专辑的弹出窗口 | `u A` |
| `CurrentlyPlayingContextPage` | 转到当前正在播放的上下文页面 | `g space` |
| `TopTrackPage` | 转到用户热门曲目页面 | `g t` |
| `RecentlyPlayedTrackPage` | 转到用户最近播放的曲目页面 | `g r` |
| `LikedTrackPage` | 转到用户喜欢的曲目页面 | `g y` |
| `LyricsPage` | 转到当前曲目的歌词页面 | `g L`, `l` |
| `LibraryPage` | 转到用户资料库页面 | `g l` |
| `SearchPage` | 转到搜索页面 | `g s` |
| `BrowsePage` | 转到浏览页面 | `g b` |
| `Queue` | 转到队列页面 | `z` |
| `OpenCommandHelp` | 转到命令帮助页面 | `?`, `C-h` |
| `PreviousPage` | 转到上一页 | `backspace`, `C-q` |
| `OpenSpotifyLinkFromClipboard` | 从剪贴板打开 Spotify 链接 | `O` |
| `SortTrackByTitle` | 按曲目标题对曲目表（如果有的话）进行排序 | `s t` |
| `SortTrackByArtists` | 按曲目的艺术家对曲目表（如果有的话）进行排序 | `s a` |
| `SortTrackByAlbum` | 按曲目的专辑对曲目表（如果有的话）进行排序 | `s A` |
| `SortTrackByAddedDate` | 按曲目的添加日期对曲目表（如果有的话）进行排序 | `s D` |
| `SortTrackByDuration` | 按曲目的时长对曲目表（如果有的话）进行排序 | `s d` |
| `SortLibraryAlphabetically` | 按字母顺序对资料库进行排序 | `s l a` |
| `SortLibraryByRecent` | 按最近添加的项目对资料库（播放列表和专辑）进行排序 | `s l r` |
| `ReverseOrder` | 反转曲目表（如果有的话）的顺序 | `s r` |
| `MovePlaylistItemUp` | 将播放列表项目向上移动一个位置 | `C-k` |
| `MovePlaylistItemDown` | 将播放列表项目向下移动一个位置 | `C-j` |
| `CreatePlaylist` | 创建一个新的播放列表 | `N` |
| `JumpToCurrentTrackInContext` | 跳转到上下文中的当前曲目 | `g c` |
| `JumpToHighlightTrackInContext` | 跳转到上下文中当前高亮显示的搜索结果 | `C-g` |
要添加或修改快捷键，请参见 [快捷键映射部分](https://github.com/aome510/spotify-player/blob/master/docs/config.md#keymaps)。
### 操作
并非所有操作都适用于每个 Spotify 项目。要查看可用操作，请使用 `ShowActionsOnCurrentTrack` 或 `ShowActionsOnSelectedItem`，然后按回车键触发操作。某些操作可能不会出现在弹出窗口中，但可以绑定到快捷键。
可用操作列表：
- `GoToArtist`
- `GoToAlbum`
- `GoToRadio`
- `AddToLibrary`
- `AddToPlaylist`
- `AddToQueue`
- `AddToLiked`
- `DeleteFromLiked`
- `DeleteFromLibrary`
- `DeleteFromPlaylist`
- `ShowActionsOnAlbum`
- `ShowActionsOnArtist`
- `ShowActionsOnShow`
- `ToggleLiked`
- `CopyLink`
- `Follow`
- `Unfollow`
操作也可以绑定到快捷键。要添加新的快捷键，请参见 [操作部分](https://github.com/aome510/spotify-player/blob/master/docs/config.md#actions)。
### 搜索页面
进入搜索页面时，焦点位于搜索输入框中。输入文本，使用 `backspace` 删除，按 `enter` 进行搜索。
要将焦点从搜索输入框移动到其他窗口（曲目结果、专辑结果等），请使用 `FocusNextWindow` 或 `FocusPreviousWindow`。
## 配置
默认情况下，配置文件位于 `$HOME/.config/spotify_player`。使用 `-c 标签：CLI, Rust, Spotify, Spotify Connect, TUI, WiFi技术, 可视化界面, 媒体控制, 媒体播放器, 媒体流传输, 守护进程, 开源, 桌面歌词, 桌面通知, 模糊搜索, 流媒体, 终端应用, 网络流量审计, 通知系统, 音乐播放器, 音频可视化