数据模型

API 请求和响应中使用的数据结构定义。

模型索引

模型	说明
database.LibraryStats	包含 9 个字段
audioTracksResponse	包含 1 个字段
AutoScanSetting	包含 2 个字段
dirValidateRequest	包含 1 个字段
dirValidateResponse	包含 5 个字段
equalizerSetting	包含 3 个字段
FingerprintStatus	包含 6 个字段
githubDiscoveryTokenSetting	包含 1 个字段
githubProxySetting	包含 1 个字段
hlsProxySettingRequest	包含 1 个字段
httpProxySetting	包含 1 个字段
jsPluginBatchUpdateResponse	包含 6 个字段
jsPluginBatchUpdateResult	包含 8 个字段
jsPluginUploadResponse	包含 5 个字段
jsPluginUploadResult	包含 4 个字段
libraryBrowseSetting	包含 1 个字段
libraryBrowseView	包含 2 个字段
logLevelSettingRequest	包含 1 个字段
MusicPathSetting	包含 4 个字段
pluginAutoUpdateSetting	包含 1 个字段
pluginHealthResponse	包含 1 个字段
pluginKeepAliveSetting	包含 1 个字段
pluginOrderSetting	包含 1 个字段
pluginRegistriesSetting	包含 1 个字段
pluginTabEntry	包含 3 个字段
proxyAllowlistSettingRequest	包含 1 个字段
registryInstallRequest	包含 5 个字段
registryPluginEntry	包含 16 个字段
registryRefreshRequest	包含 8 个字段
registryRefreshResponse	包含 5 个字段
remoteTitleSourceRequest	包含 1 个字段
scanAutoCreatePlaylistsRequest	包含 1 个字段
scanAutoFingerprintRequest	包含 1 个字段
scanPlaylistModeRequest	包含 1 个字段
scanPlaylistModeResponse	包含 1 个字段
ScanRequest	包含 2 个字段
scanTitleSourceRequest	包含 1 个字段
songArtistsRequest	包含 1 个字段
songArtistsResponse	包含 1 个字段
startFingerprintRequest	包含 2 个字段
tabConfigSetting	包含 3 个字段
trackItem	包含 4 个字段
userPreferencesSetting	包含 6 个字段
volumeNormalizeRequest	包含 2 个字段
WriteSongTagsRequest	包含 13 个字段
JSPlugin	包含 24 个字段
RegistryConfig	包含 4 个字段
Artist	包含 3 个字段
ArtistInput	包含 3 个字段
BatchDeletePlaylistsRequest	包含 2 个字段
BatchDeletePlaylistsResponse	包含 2 个字段
BatchDeleteSongsRequest	包含 2 个字段
BatchDeleteSongsResponse	包含 1 个字段
Config	包含 4 个字段
CreateConfigRequest	包含 2 个字段
ErrorResponse	包含 2 个字段
ImportResult	包含 5 个字段
JSPluginStatus	string
LoginRequest	包含 2 个字段
LoginResponse	包含 4 个字段
PlayHistoryEntry	包含 3 个字段
PlayHistoryListResponse	包含 2 个字段
Playlist	包含 13 个字段
RefreshTokenRequest	包含 1 个字段
RevokeTokenRequest	包含 1 个字段
SetPlaylistPinnedRequest	包含 1 个字段
SetPlaylistVisibilityRequest	包含 1 个字段
Song	包含 35 个字段
SongArtist	包含 3 个字段
SongTag	包含 6 个字段
SuccessResponse	包含 1 个字段
ThemePackColors	包含 4 个字段
ThemePackData	包含 13 个字段
UpdateConfigRequest	包含 1 个字段
UpdatePlaylistRequest	包含 5 个字段
UpgradeProgress	包含 4 个字段
UploadedBinaryInfo	包含 7 个字段
AudioTrackInfo	包含 5 个字段
CacheConfig	包含 4 个字段
CacheConfigResponse	包含 5 个字段
CacheStats	包含 3 个字段
FingerprintProgress	包含 4 个字段
MetadataRefreshProgress	包含 4 个字段
OrganizeItem	包含 2 个字段
OrganizePreviewResult	包含 5 个字段
OrganizeResult	包含 4 个字段
RefreshResponse	包含 4 个字段
ScanProgress	包含 14 个字段
ScanStatus	string
ThemePackListItem	包含 9 个字段
ThemePackResponse	包含 10 个字段
HealthClass	string
Outcome	包含 6 个字段
OutcomeResult	string
PluginHealthSnapshot	包含 5 个字段

database.LibraryStats {#database-librarystats}

完整名称：database.LibraryStats

类型： object

字段	类型	必填	说明
album_count	integer	否
artist_count	integer	否
genre_count	integer	否
local_songs	integer	否
radio_songs	integer	否
remote_songs	integer	否
total_duration	number	否
total_file_size	integer	否
total_songs	integer	否

---

audioTracksResponse {#handlers-audiotracksresponse}

完整名称：handlers.audioTracksResponse

类型： object

字段	类型	必填	说明
tracks	AudioTrackInfo[]	否

---

AutoScanSetting {#handlers-autoscansetting}

完整名称：handlers.AutoScanSetting

类型： object

字段	类型	必填	说明
enabled	boolean	否
interval_seconds	integer	否

---

dirValidateRequest {#handlers-dirvalidaterequest}

完整名称：handlers.dirValidateRequest

类型： object

字段	类型	必填	说明
path	string	否

---

dirValidateResponse {#handlers-dirvalidateresponse}

完整名称：handlers.dirValidateResponse

类型： object

字段	类型	必填	说明
created	boolean	否
error	string	否
free_size	integer	否
total_size	integer	否
valid	boolean	否

---

equalizerSetting {#handlers-equalizersetting}

完整名称：handlers.equalizerSetting

类型： object

字段	类型	必填	说明
bands	number[]	否
enabled	boolean	否
preset	string	否

---

FingerprintStatus {#handlers-fingerprintstatus}

完整名称：handlers.FingerprintStatus

类型： object

字段	类型	必填	说明
auto_enabled	boolean	否	AutoEnabled 扫描后是否自动计算指纹（config scan_auto_fingerprint）
chromaprint_available	boolean	否	ChromaprintAvailable ffmpeg 是否带 chromaprint muxer，false 时无法计算指纹
computed	integer	否	Computed 已有指纹的数量
failed	integer	否	Failed 尝试过但失败的数量（无音轨 / 文件损坏 / 超时），不会自动重试，
需要「重新计算全部」才会再试
missing	integer	否	Missing 尚未尝试过计算的数量（= total - computed - failed）
total	integer	否	Total 本地歌曲总数

---

githubDiscoveryTokenSetting {#handlers-githubdiscoverytokensetting}

完整名称：handlers.githubDiscoveryTokenSetting

类型： object

字段	类型	必填	说明
token	string	否

---

githubProxySetting {#handlers-githubproxysetting}

完整名称：handlers.githubProxySetting

类型： object

字段	类型	必填	说明
proxy	string	否

---

hlsProxySettingRequest {#handlers-hlsproxysettingrequest}

完整名称：handlers.hlsProxySettingRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

httpProxySetting {#handlers-httpproxysetting}

完整名称：handlers.httpProxySetting

类型： object

字段	类型	必填	说明
proxy	string	否

---

jsPluginBatchUpdateResponse {#handlers-jspluginbatchupdateresponse}

完整名称：handlers.jsPluginBatchUpdateResponse

类型： object

字段	类型	必填	说明
failed	integer	否
message	string	否
results	jsPluginBatchUpdateResult[]	否
skipped	integer	否
total	integer	否
updated	integer	否

---

jsPluginBatchUpdateResult {#handlers-jspluginbatchupdateresult}

完整名称：handlers.jsPluginBatchUpdateResult

类型： object

字段	类型	必填	说明
current_version	string	否
entry_path	string	否
error	string	否
has_update	boolean	否
new_version	string	否
plugin_id	integer	否
plugin_name	string	否
success	boolean	否

---

jsPluginUploadResponse {#handlers-jspluginuploadresponse}

完整名称：handlers.jsPluginUploadResponse

类型： object

字段	类型	必填	说明
failed	integer	否
message	string	否
results	jsPluginUploadResult[]	否
success	integer	否
total	integer	否

---

jsPluginUploadResult {#handlers-jspluginuploadresult}

完整名称：handlers.jsPluginUploadResult

类型： object

字段	类型	必填	说明
error	string	否
file_name	string	否
plugin	JSPlugin	否
success	boolean	否

---

libraryBrowseSetting {#handlers-librarybrowsesetting}

完整名称：handlers.libraryBrowseSetting

类型： object

字段	类型	必填	说明
views	libraryBrowseView[]	否

---

libraryBrowseView {#handlers-librarybrowseview}

完整名称：handlers.libraryBrowseView

类型： object

字段	类型	必填	说明
key	string	否
visible	boolean	否

---

logLevelSettingRequest {#handlers-loglevelsettingrequest}

完整名称：handlers.logLevelSettingRequest

类型： object

字段	类型	必填	说明
level	string	否

---

MusicPathSetting {#handlers-musicpathsetting}

完整名称：handlers.MusicPathSetting

类型： object

字段	类型	必填	说明
auto_create_exclude_dirs	string[]	否
exclude_dirs	string[]	否
exclude_paths	string[]	否
path	string	否

---

pluginAutoUpdateSetting {#handlers-pluginautoupdatesetting}

完整名称：handlers.pluginAutoUpdateSetting

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

pluginHealthResponse {#handlers-pluginhealthresponse}

完整名称：handlers.pluginHealthResponse

类型： object

字段	类型	必填	说明
plugins	PluginHealthSnapshot[]	否

---

pluginKeepAliveSetting {#handlers-pluginkeepalivesetting}

完整名称：handlers.pluginKeepAliveSetting

类型： object

字段	类型	必填	说明
plugins	string[]	否

---

pluginOrderSetting {#handlers-pluginordersetting}

完整名称：handlers.pluginOrderSetting

类型： object

字段	类型	必填	说明
order	string[]	否

---

pluginRegistriesSetting {#handlers-pluginregistriessetting}

完整名称：handlers.pluginRegistriesSetting

类型： object

字段	类型	必填	说明
registries	RegistryConfig[]	否

---

pluginTabEntry {#handlers-plugintabentry}

完整名称：handlers.pluginTabEntry

类型： object

字段	类型	必填	说明
entry_path	string	否
name	string	否
plugin_id	integer	否

---

proxyAllowlistSettingRequest {#handlers-proxyallowlistsettingrequest}

完整名称：handlers.proxyAllowlistSettingRequest

类型： object

字段	类型	必填	说明
allowlist	string[]	否

---

registryInstallRequest {#handlers-registryinstallrequest}

完整名称：handlers.registryInstallRequest

类型： object

字段	类型	必填	说明
download_url	string	否
github_proxy	string	否
overwrite	boolean	否	Overwrite 为 true 时允许覆盖掉本地已装的同 entry_path 但不同作者的插件。
默认 false：这种情况返回 409，由前端二次确认后带该字段重发。
source_url	string	否	SourceURL 插件所属订阅源 URL。「全部」聚合模式安装时回传：
当未显式提供 token 时，后端据此从 plugin_registries 配置解析该源的 token。
token	string	否

---

registryPluginEntry {#handlers-registrypluginentry}

完整名称：handlers.registryPluginEntry

类型： object

字段	类型	必填	说明
author	string	否
conflict	boolean	否	Conflict 为 true 表示本地已装了同 entry_path 但不同身份的插件。
此时 installed=false（这不是同一个插件），安装它会覆盖掉本地那个。
conflict_with	string	否	ConflictWith 描述占用该 entry_path 的本地插件，可直接展示给用户。
description	string	否
download_url	string	否
entry_path	string	否
has_update	boolean	否
homepage	string	否
icon	string	否
identity	string	否	Identity 是 entry_path 之外的身份维度（规范化 author，或 GitHub 仓库兜底）。
entry_path 撞名时前端据 (entry_path, identity) 做稳定行标识与就地状态更新。
为空表示无法判定身份（此时仅按 entry_path 判定）。
installed	boolean	否
installed_version	string	否
name	string	否
source_name	string	否	SourceName 该插件所属订阅源名称（仅「全部」聚合模式返回），
供 UI 区分 entry_path 相同的两个条目。
source_url	string	否	SourceURL 该插件所属订阅源 URL（仅「全部」聚合模式返回），
安装时回传给后端以按源解析私有源 token。
version	string	否

---

registryRefreshRequest {#handlers-registryrefreshrequest}

完整名称：handlers.registryRefreshRequest

类型： object

字段	类型	必填	说明
all_sources	boolean	否
force	boolean	否	Force 为 true 时绕过服务端缓存强制重新拉取。供「刷新」按钮使用；
翻页与搜索不应设置它，否则每翻一页都会重拉整棵注册表树。
github_proxy	string	否
page	integer	否
page_size	integer	否
registry_url	string	否
search	string	否
token	string	否

---

registryRefreshResponse {#handlers-registryrefreshresponse}

完整名称：handlers.registryRefreshResponse

类型： object

字段	类型	必填	说明
page	integer	否
page_size	integer	否
plugins	registryPluginEntry[]	否
total	integer	否
warnings	string[]	否

---

remoteTitleSourceRequest {#handlers-remotetitlesourcerequest}

完整名称：handlers.remoteTitleSourceRequest

类型： object

字段	类型	必填	说明
title_source	string	否	可选值: tag, filename 示例: "filename"

---

scanAutoCreatePlaylistsRequest {#handlers-scanautocreateplaylistsrequest}

完整名称：handlers.scanAutoCreatePlaylistsRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

scanAutoFingerprintRequest {#handlers-scanautofingerprintrequest}

完整名称：handlers.scanAutoFingerprintRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否

---

scanPlaylistModeRequest {#handlers-scanplaylistmoderequest}

完整名称：handlers.scanPlaylistModeRequest

类型： object

字段	类型	必填	说明
mode	string	否	可选值: directory, top_level, bubble_up 示例: "directory"

---

scanPlaylistModeResponse {#handlers-scanplaylistmoderesponse}

完整名称：handlers.scanPlaylistModeResponse

类型： object

字段	类型	必填	说明
mode	string	否	示例: "directory"

---

ScanRequest {#handlers-scanrequest}

完整名称：handlers.ScanRequest

类型： object

字段	类型	必填	说明
paths	string[]	否	Paths 为目录级定向扫描（Issue #262）：为空时扫描整个音乐根目录（默认行为）；
非空时只扫描给定目录（含子目录），过期记录清理也仅收敛到这些目录之内。
每个目录必须位于音乐根目录之下，否则返回 400。
reimport	boolean	否

---

scanTitleSourceRequest {#handlers-scantitlesourcerequest}

完整名称：handlers.scanTitleSourceRequest

类型： object

字段	类型	必填	说明
title_source	string	否	可选值: tag, filename 示例: "tag"

---

songArtistsRequest {#handlers-songartistsrequest}

完整名称：handlers.songArtistsRequest

类型： object

字段	类型	必填	说明
artists	ArtistInput[]	否

---

songArtistsResponse {#handlers-songartistsresponse}

完整名称：handlers.songArtistsResponse

类型： object

字段	类型	必填	说明
artists	SongArtist[]	否

---

startFingerprintRequest {#handlers-startfingerprintrequest}

完整名称：handlers.startFingerprintRequest

类型： object

字段	类型	必填	说明
recompute_all	boolean	否
retry_failed	boolean	否	RetryFailed 仅重置失败项的「已尝试」标记后重试，已算好的指纹保留。

---

tabConfigSetting {#handlers-tabconfigsetting}

完整名称：handlers.tabConfigSetting

类型： object

字段	类型	必填	说明
plugin_tabs	pluginTabEntry[]	否
show_library	boolean	否
show_playlists	boolean	否

---

trackItem {#handlers-trackitem}

完整名称：handlers.trackItem

类型： object

字段	类型	必填	说明
codec	string	否
index	integer	否
language	string	否
title	string	否

---

userPreferencesSetting {#handlers-userpreferencessetting}

完整名称：handlers.userPreferencesSetting

类型： object

字段	类型	必填	说明
audio_quality	string	否
local_cache_max_size	integer	否
play_mode	string	否
playlist_view_mode	string	否
theme_mode	string	否
volume	number	否

---

volumeNormalizeRequest {#handlers-volumenormalizerequest}

完整名称：handlers.volumeNormalizeRequest

类型： object

字段	类型	必填	说明
enabled	boolean	否	示例: false
loudness	number	否	示例: -16

---

WriteSongTagsRequest {#handlers-writesongtagsrequest}

完整名称：handlers.WriteSongTagsRequest

类型： object

字段	类型	必填	说明
album	string	否
artist	string	否
clear_cover	boolean	否
cover_data	string	否
cover_url	string	否
genre	string	否
language	string	否
lyrics	string	否
rename_file	boolean	否	RenameFile 为 true 时按新标题重命名本地音频文件（保留原目录与扩展名），仅对本地非 CUE 歌曲生效。
style	string	否
title	string	否
track	string	否
year	integer	否

---

JSPlugin {#jsplugin-jsplugin}

完整名称：jsplugin.JSPlugin

类型： object

字段	类型	必填	说明
author	string	否
created_at	string	否
description	string	否
download_url	string	否
entry_hash	string	否	main.js/main.jsc 内容 SHA256
entry_path	string	否	路由前缀（如 "myplugin"）
external_paths	string[]	否	可访问的外部绝对路径目录
file_mod_time	string	否
file_path	string	否	ZIP 文件相对路径
homepage	string	否
icon	string	否
id	integer	否
license	string	否
main	string	否	入口文件路径（如 "main.js"）
min_host_version	string	否
name	string	否
permissions	string[]	否	权限列表
public_paths	string[]	否	无需 JWT 认证的路径前缀
render_engine	string	否	RenderEngine 插件页渲染引擎："webview" / "lynx"；空串 = 跟随宿主默认（当前 webview）。
刻意不加 omitempty：客户端需要能稳定读到该字段并自行把空串映射为默认引擎。
status	JSPluginStatus	否
update_url	string	否
updated_at	string	否
version	string	否
zip_hash	string	否	ZIP 文件 SHA256

---

RegistryConfig {#jsplugin-registryconfig}

完整名称：jsplugin.RegistryConfig

类型： object

字段	类型	必填	说明
enabled	boolean	否
name	string	否
token	string	否
url	string	否

---

Artist {#models-artist}

完整名称：models.Artist

类型： object

字段	类型	必填	说明
created_at	string	否
id	integer	否
name	string	否

---

ArtistInput {#models-artistinput}

完整名称：models.ArtistInput

类型： object

字段	类型	必填	说明
name	string	否	示例: "周杰伦"
position	integer	否	示例: 0
role	string	否	artist | album_artist，缺省 artist 示例: "artist"

---

BatchDeletePlaylistsRequest {#models-batchdeleteplaylistsrequest}

完整名称：models.BatchDeletePlaylistsRequest

类型： object

字段	类型	必填	说明
delete_songs	boolean	否	为 true 时，一并删除仅属于被删歌单的孤儿歌曲（含本地歌曲及其磁盘文件） 示例: false
ids	integer[]	否	要删除的歌单 ID 列表 示例: [1]

---

BatchDeletePlaylistsResponse {#models-batchdeleteplaylistsresponse}

完整名称：models.BatchDeletePlaylistsResponse

类型： object

字段	类型	必填	说明
deleted	integer	否	实际删除的歌单数量 示例: 3
deleted_songs	integer	否	连带清理的孤儿歌曲数量 示例: 12

---

BatchDeleteSongsRequest {#models-batchdeletesongsrequest}

完整名称：models.BatchDeleteSongsRequest

类型： object

字段	类型	必填	说明
delete_files	boolean	否	是否同步删除本地音频文件 示例: false
ids	integer[]	否	要删除的歌曲 ID 列表 示例: [1]

---

BatchDeleteSongsResponse {#models-batchdeletesongsresponse}

完整名称：models.BatchDeleteSongsResponse

类型： object

字段	类型	必填	说明
deleted	integer	否	实际删除的数量 示例: 3

---

Config {#models-config}

完整名称：models.Config

类型： object

字段	类型	必填	说明
id	integer	否	配置ID 示例: 1
key	string	否	配置键 示例: "music_path"
updated_at	string	否	更新时间 示例: "2024-01-01T12:00:00Z"
value	string	否	配置值（JSON格式） 示例: "{\"path\":\"/music\"}"

---

CreateConfigRequest {#models-createconfigrequest}

完整名称：models.CreateConfigRequest

类型： object

字段	类型	必填	说明
key	string	是	配置键 示例: "music_path"
value	string	是	配置值（JSON 格式） 示例: "{\"path\":\"/music\"}"

---

ErrorResponse {#models-errorresponse}

完整名称：models.ErrorResponse

类型： object

字段	类型	必填	说明
detail	string	否	详细错误信息（可选） 示例: "详细错误信息"
error	string	否	错误信息 示例: "操作失败"

---

ImportResult {#models-importresult}

完整名称：models.ImportResult

类型： object

字段	类型	必填	说明
playlists_created	integer	否
playlists_merged	integer	否
songs_created	integer	否
songs_matched	integer	否
songs_skipped	integer	否

---

JSPluginStatus {#models-jspluginstatus}

完整名称：models.JSPluginStatus

类型： string

可选值：

• active
• inactive
• error

---

LoginRequest {#models-loginrequest}

完整名称：models.LoginRequest

类型： object

字段	类型	必填	说明
password	string	是	密码 示例: "admin"
username	string	是	用户名 示例: "admin"

---

LoginResponse {#models-loginresponse}

完整名称：models.LoginResponse

类型： object

字段	类型	必填	说明
access_token	string	否	Access Token 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
expires_in	integer	否	Access Token 过期时间（秒） 示例: 604800
refresh_token	string	否	Refresh Token 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
token_type	string	否	Token 类型 示例: "Bearer"

---

PlayHistoryEntry {#models-playhistoryentry}

完整名称：models.PlayHistoryEntry

类型： object

字段	类型	必填	说明
play_count	integer	否	在该上下文内的累计播放次数 示例: 3
played_at	string	否	最后一次播放时间 示例: "2024-01-01T12:00:00Z"
song	any	否	歌曲详情

---

PlayHistoryListResponse {#models-playhistorylistresponse}

完整名称：models.PlayHistoryListResponse

类型： object

字段	类型	必填	说明
items	PlayHistoryEntry[]	否	播放记录，按最后播放时间倒序
total	integer	否	本次返回的条数（上限 50，故与 items 长度一致） 示例: 12

---

Playlist {#models-playlist}

完整名称：models.Playlist

类型： object

字段	类型	必填	说明
cover_url	string	否	封面图片 URL 示例: "https://example.com/playlist.jpg"
created_at	string	否	创建时间 示例: "2024-01-01T12:00:00Z"
description	string	否	歌单描述 示例: "收藏的经典歌曲"
id	integer	否	歌单 ID 示例: 1
labels	string[]	否	歌单标签，如 ["built_in"] 示例: ["[\"built_in\"]"]
name	string	否	歌单名称 示例: "我的最爱"
pinned_at	string	否	置顶时间，nil 表示未置顶；多个置顶歌单按此字段倒序排列 示例: "2024-01-01T12:00:00Z"
remote_count	integer	否	歌单内网络歌曲（songs.type=remote）数量，>0 即为「网络歌单」；仅列表接口填充，详情接口恒为 0 示例: 3
song_count	integer	否	歌曲数量 示例: 10
sort_by	string	否	视图排序字段：position/added_at/file_modified_at/title/artist/duration 示例: "position"
sort_order	string	否	视图排序方向：asc/desc 示例: "asc"
type	string	否	歌单类型：normal/radio 可选值: normal, radio 示例: "normal"
updated_at	string	否	最后更新时间 示例: "2024-01-01T12:00:00Z"

---

RefreshTokenRequest {#models-refreshtokenrequest}

完整名称：models.RefreshTokenRequest

类型： object

字段	类型	必填	说明
refresh_token	string	是	刷新令牌 示例: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

RevokeTokenRequest {#models-revoketokenrequest}

完整名称：models.RevokeTokenRequest

类型： object

字段	类型	必填	说明
reason	string	否	撤销原因 示例: "用户主动登出"

---

SetPlaylistPinnedRequest {#models-setplaylistpinnedrequest}

完整名称：models.SetPlaylistPinnedRequest

类型： object

字段	类型	必填	说明
pinned	boolean	否	是否置顶歌单 示例: true

---

SetPlaylistVisibilityRequest {#models-setplaylistvisibilityrequest}

完整名称：models.SetPlaylistVisibilityRequest

类型： object

字段	类型	必填	说明
hidden	boolean	否	是否隐藏歌单 示例: true

---

Song {#models-song}

完整名称：models.Song

类型： object

字段	类型	必填	说明
added_at	string	否	添加时间 示例: "2024-01-01T12:00:00Z"
album	string	否	专辑名称 示例: "十一月的萧邦"
artist	string	否	艺术家/歌手 示例: "周杰伦"
bit_rate	integer	否	比特率（kbps） 示例: 320
cover_url	string	否	封面图片URL 示例: "https://example.com/cover.jpg"
cue_source_path	string	否	CUE 来源路径（非空表示 CUE 拆分歌曲）
cue_track_index	integer	否	CUE track 序号 (1-99)
dedup_key	string	否	去重 key(由插件定义,典型形态 "<platform>:<platform_id>");与 PluginEntryPath 组成 UNIQUE
duration	number	否	播放时长（秒） 示例: 253.5
file_modified_at	string	否	文件修改时间(mtime，本地歌曲扫描时记录；未知为 nil)
file_path	string	否	本地文件路径 示例: "/music/周杰伦/夜曲.mp3"
file_size	integer	否	文件大小（字节） 示例: 10485760
fingerprint	string	否	音频指纹(Chromaprint)
fingerprint_duration	number	否	指纹对应音频时长
format	string	否	音频格式 示例: "mp3"
genre	string	否	流派 示例: "Pop"
id	integer	否	歌曲ID 示例: 1
is_live	boolean	否	是否为直播流 示例: false
is_video	boolean	否	是否含真实视频轨(扫描时 ffprobe 探测,排除封面);客户端据此渲染画面/选择投屏 mime 示例: false
isrc	string	否	ISRC(国际标准录音编码)
language	string	否	语种 示例: "国语"
lyric_remote_url	string	否	lyric_source=url 时的原始 URL(运行时由 LyricFetcher 拉取)
lyric_url	string	否	歌词端点 URL(客户端唯一可见字段,指向 /api/v1/songs/{id}/lyric)
plugin_entry_path	string	否	音源插件 entryPath(网络歌曲) 示例: "my-source"
sample_rate	integer	否	采样率（Hz） 示例: 44100
source_cover_url	string	否	原始封面 URL(仅 JSON 输出,CoverURL 非空时保留原始值供编辑使用)
source_data	string	否	音源元数据 JSON(给插件 music/url 接口用,opaque)
source_url	string	否	原始音源 URL(仅 JSON 输出,radio/remote 类型返回原始流地址供编辑使用)
style	string	否	风格 示例: "抒情"
title	string	否	标题 示例: "夜曲"
track	string	否	音轨号，可为 "3" 或 "3/12"（轨号/总数） 示例: "3/12"
type	string	否	歌曲类型：local/remote/radio 可选值: local, remote, radio 示例: "local"
updated_at	string	否	最后更新时间 示例: "2024-01-01T12:00:00Z"
url	string	否	网络地址 示例: "https://example.com/song.mp3"
year	integer	否	发行年份 示例: 2005

---

SongArtist {#models-songartist}

完整名称：models.SongArtist

类型： object

字段	类型	必填	说明
artist	Artist	否
position	integer	否	同角色内的展示顺序
role	string	否	artist | album_artist

---

SongTag {#models-songtag}

完整名称：models.SongTag

类型： object

字段	类型	必填	说明
color	string	否
cover_url	string	否
created_at	string	否
id	integer	否
name	string	否
song_count	integer	否

---

SuccessResponse {#models-successresponse}

完整名称：models.SuccessResponse

类型： object

字段	类型	必填	说明
message	string	否	成功信息 示例: "操作成功"

---

ThemePackColors {#models-themepackcolors}

完整名称：models.ThemePackColors

类型： object

字段	类型	必填	说明
backgroundColor	string	否
glassColor	string	否	GlassColor independently drives the Liquid Glass decorative tint
(--glass-glow / --glass-glow-faint / --glass-sheen in the Lynx client),
separate from SeedColor which drives the button/accent channel. Optional:
when absent the client falls back to its star-blue glass baseline, so
glass stays a different colour from buttons (true dual-channel). Existing
packs without this field still validate.
seedColor	string	否
surfaceColor	string	否

---

ThemePackData {#models-themepackdata}

完整名称：models.ThemePackData

类型： object

字段	类型	必填	说明
author	string	否
cardRadius	number	否
controlRadius	number	否
dark	ThemePackColors	否
description	string	否
id	string	否
light	ThemePackColors	否
name	string	否
navigationRadius	number	否
navigationStyle	string	否
playerGradient	string[]	否
schemaVersion	integer	否
version	string	否

---

UpdateConfigRequest {#models-updateconfigrequest}

完整名称：models.UpdateConfigRequest

类型： object

字段	类型	必填	说明
value	string	是	配置值（JSON 格式） 示例: "{\"path\":\"/new_music\"}"

---

UpdatePlaylistRequest {#models-updateplaylistrequest}

完整名称：models.UpdatePlaylistRequest

类型： object

字段	类型	必填	说明
cover_path	string	否	封面图片本地路径（传空字符串清除） 示例: ""
cover_song_id	integer	否	从指定歌曲复制封面（与 cover_path/cover_url 互斥，优先级更高） 示例: 42
cover_url	string	否	封面图片 URL（传空字符串清除） 示例: ""
description	string	否	歌单描述 示例: "收藏的经典歌曲"
name	string	否	歌单名称 示例: "我的最爱"

---

UpgradeProgress {#models-upgradeprogress}

完整名称：models.UpgradeProgress

类型： object

字段	类型	必填	说明
current_step	string	否	当前步骤描述 示例: "正在下载新版本..."
error	string	否	错误信息（如有） 示例: "下载失败"
progress	integer	否	进度百分比 (0-100) 示例: 50
status	string	否	状态 可选值: idle, downloading, testing, replacing, restarting, completed, failed 示例: "downloading"

---

UploadedBinaryInfo {#models-uploadedbinaryinfo}

完整名称：models.UploadedBinaryInfo

类型： object

字段	类型	必填	说明
build_time	string	否	上传文件的构建时间 示例: "2026-08-01"
build_type	string	否	上传文件的构建类型（full/lite） 示例: "full"
channel	string	否	上传文件的通道（stable/dev） 示例: "stable"
channel_mismatch	boolean	否	通道是否不匹配（需前端二次确认） 示例: true
current_channel	string	否	当前运行通道 示例: "dev"
current_version	string	否	当前运行版本 示例: "v2.10.0"
version	string	否	上传文件的版本号 示例: "v2.11.0"

---

AudioTrackInfo {#services-audiotrackinfo}

完整名称：services.AudioTrackInfo

类型： object

字段	类型	必填	说明
codec	string	否
default	boolean	否
index	integer	否
language	string	否
title	string	否

---

CacheConfig {#services-cacheconfig}

完整名称：services.CacheConfig

类型： object

字段	类型	必填	说明
cache_dir	string	否	自定义缓存目录，空字符串表示使用默认目录
max_size	integer	否	最大缓存大小（字节），0 表示无限制
transcode_format	string	否	TranscodeFormat 缓存网络歌曲落盘时统一转码的目标格式（mp3/m4a/ogg/flac/wav）。
空字符串表示不转码、按上游原格式落盘（默认）。缺 ffmpeg 或转码失败时优雅降级保留原格式。
transcode_quality	string	否	TranscodeQuality 转码目标码率（128/192/320），空或非法值表示最高质量。仅对有损格式生效。

---

CacheConfigResponse {#services-cacheconfigresponse}

完整名称：services.CacheConfigResponse

类型： object

字段	类型	必填	说明
cache_dir	string	否
default_cache_dir	string	否
max_size	integer	否
transcode_format	string	否
transcode_quality	string	否

---

CacheStats {#services-cachestats}

完整名称：services.CacheStats

类型： object

字段	类型	必填	说明
file_count	integer	否	文件数量
max_size	integer	否	最大缓存大小（字节），0 表示无限制
total_size	integer	否	总大小（字节）

---

FingerprintProgress {#services-fingerprintprogress}

完整名称：services.FingerprintProgress

类型： object

字段	类型	必填	说明
computed	integer	否
failed	integer	否
status	string	否	idle, running, done, cancelled
total	integer	否

---

MetadataRefreshProgress {#services-metadatarefreshprogress}

完整名称：services.MetadataRefreshProgress

类型： object

字段	类型	必填	说明
failed	integer	否
processed	integer	否
status	string	否
total	integer	否

---

OrganizeItem {#services-organizeitem}

完整名称：services.OrganizeItem

类型： object

字段	类型	必填	说明
id	integer	否
target_path	string	否

---

OrganizePreviewResult {#services-organizepreviewresult}

完整名称：services.OrganizePreviewResult

类型： object

字段	类型	必填	说明
error	string	否
id	integer	否
new_path	string	否
old_path	string	否
status	string	否

---

OrganizeResult {#services-organizeresult}

完整名称：services.OrganizeResult

类型： object

字段	类型	必填	说明
error	string	否
file_path	string	否
id	integer	否
status	string	否

---

RefreshResponse {#services-refreshresponse}

完整名称：services.RefreshResponse

类型： object

字段	类型	必填	说明
access_token	string	否
expires_in	integer	否
refresh_token	string	否
token_type	string	否

---

ScanProgress {#services-scanprogress}

完整名称：services.ScanProgress

类型： object

字段	类型	必填	说明
cleaned_files	integer	否	清理的过期文件数
cue_split_sources	integer	否	splitting_cue 阶段已处理的 CUE 来源数
current_file	string	否	当前处理的文件
discovered_files	integer	否	scanning 阶段已发现的音频文件数
end_time	string	否	结束时间
error	string	否	错误信息
failed_files	integer	否	失败的文件数
imported_files	integer	否	已导入文件数
local_song_count	integer	否	扫描完成后数据库中本地歌曲总数
scanned_files	integer	否	已扫描文件数
skipped_files	integer	否	跳过的文件数（已存在）
start_time	string	否	开始时间
status	any	否	当前状态
total_files	integer	否	总文件数

---

ScanStatus {#services-scanstatus}

完整名称：services.ScanStatus

类型： string

可选值：

• idle
• scanning
• importing
• splitting_cue
• creating_playlists
• completed
• failed
• cancelling
• cancelled

---

ThemePackListItem {#services-themepacklistitem}

完整名称：services.ThemePackListItem

类型： object

字段	类型	必填	说明
author	string	否
created_at	string	否
description	string	否
id	integer	否
name	string	否
schema_version	integer	否
theme_id	string	否
updated_at	string	否
version	string	否

---

ThemePackResponse {#services-themepackresponse}

完整名称：services.ThemePackResponse

类型： object

字段	类型	必填	说明
author	string	否
created_at	string	否
data	ThemePackData	否
description	string	否
id	integer	否
name	string	否
schema_version	integer	否
theme_id	string	否
updated_at	string	否
version	string	否

---

HealthClass {#source-healthclass}

完整名称：source.HealthClass

类型： string

可选值：

• green
• yellow
• red

---

Outcome {#source-outcome}

完整名称：source.Outcome

类型： object

字段	类型	必填	说明
latency_ns	integer	否	纳秒;swagger 显式声明避免 time.Duration 解析失败
plugin_entry_path	string	否
reason	string	否
result	OutcomeResult	否
size_bytes	integer	否
timestamp	string	否

---

OutcomeResult {#source-outcomeresult}

完整名称：source.OutcomeResult

类型： string

可选值：

• success
• network_fail
• probe_fail
• validation_fail
• plugin_invocation_fail

---

PluginHealthSnapshot {#source-pluginhealthsnapshot}

完整名称：source.PluginHealthSnapshot

类型： object

字段	类型	必填	说明
class	HealthClass	否
last_failures	Outcome[]	否	最近 N 次失败,便于排查
plugin_entry_path	string	否
samples	integer	否
success_rate	number	否

---