API 凭据配置教程

ECHO 的 开发者 / API 配置 页面是给进阶用户准备的。它主要用于账号授权、在线元数据、专辑评分、艺人资料和演出信息查询；不影响本地音乐播放，也不会提供任何绕过平台规则的下载能力。

如果你只是扫描本地曲库、播放本地音频、调 EQ/DSP，这一页可以完全不填。需要 Spotify 登录、TIDAL catalog 元数据、Discogs 评分，或者想让在线歌手信息更完整时，再按本教程逐项配置。

新手最短路线

不想一次性研究所有字段，可以按这个顺序来：

1. 只用 Spotify：只填 Spotify Client ID，并把 Spotify 后台的 Redirect URI 配好。
2. 只查 TIDAL 元数据：填 TIDAL Client ID、TIDAL Client Secret、TIDAL Country Code。
3. 只想补 Discogs 专辑评分：只填 Discogs personal access token。
4. 只想补演出/艺人信息：按你能申请到的来源填写 Bandsintown app_id、Ticketmaster apikey、SeatGeek client_id，没有就留空。
5. 不确定某个字段：先留空。ECHO 会跳过对应来源，不会让本地播放坏掉。

字段总览

ECHO 字段	要填的值	获取位置	留空影响
Spotify Client ID	Spotify Developer App 的 Client ID	Spotify Developer Dashboard	无法完成 Spotify 登录
Spotify Redirect URI	ECHO 页面显示的完整回调地址	ECHO 自动显示，默认 http://127.0.0.1:43879/spotify/callback	地址不一致会导致登录失败
TIDAL Client ID	TIDAL Developer App 的 Client ID	TIDAL Developer Portal	TIDAL 元数据来源不可用
TIDAL Client Secret	TIDAL Developer App 的 Client Secret	TIDAL App 详情页	TIDAL 元数据来源不可用
TIDAL Redirect URI	ECHO 页面显示的完整回调地址	ECHO 自动显示，默认 http://127.0.0.1:43880/tidal/callback	做 OAuth 时必须一致
TIDAL Country Code	两位国家/地区代码，例如 US、HK、JP	自己按账号地区或目标曲库地区填写	可能查不到部分地区 catalog
Discogs personal access token	Discogs 个人访问 token	Discogs Developers 设置页	Discogs 评分/版本资料不可用或受限
Bandsintown app_id	Bandsintown API 的 app_id / app 标识	Bandsintown API 或开发者/合作方入口	跳过 Bandsintown 来源
Ticketmaster apikey	Ticketmaster API Key，后台常叫 Consumer Key	Ticketmaster Developer Portal	跳过 Ticketmaster 来源
SeatGeek client_id	SeatGeek API 的公开 key / client_id	SeatGeek Developer Portal	跳过 SeatGeek 来源
地区过滤	地区关键词，例如 HK, Tokyo, US	自己按常看的演出地区填写	留空表示尽量查全球结果

填写前先确认

哪些是敏感信息

这些不要截图公开，也不要发到群聊、论坛、issue 或公开仓库：

• TIDAL Client Secret
• Discogs personal access token
• Ticketmaster apikey
• 任何服务后台显示的 secret、token、private key

Client ID 通常没有 Client Secret 那么敏感，但也不建议随便公开。尤其不要使用网上流传的别人 TIDAL/Spotify 凭据，可能失效，也可能违反平台规则。

为什么回调地址是 127.0.0.1

127.0.0.1 是本机地址。OAuth 登录完成后，浏览器会把授权结果发回你电脑上正在监听的 ECHO，不会发到互联网上。

回调地址必须逐字一致，包括：

• http 或 https
• 127.0.0.1
• 端口号，例如 43879
• 路径，例如 /spotify/callback
• 结尾是否有斜杠

如果 ECHO 显示的是：

http://127.0.0.1:43879/spotify/callback

就不要在后台填成：

http://localhost:43879/spotify/callback
http://127.0.0.1:43879/spotify/callback/
https://127.0.0.1:43879/spotify/callback

这些看起来差不多，但对 OAuth 来说都不是同一个地址。

Spotify OAuth 配置

Spotify 用于 Spotify 账号登录、Spotify 相关资料读取、播放控制或 Spotify Connect/Web Playback 相关能力。ECHO 只需要你自己的 Client ID，不要填写 Spotify 的 Client Secret。

你需要准备

• 一个 Spotify 账号。
• 可以打开 Spotify Developer Dashboard 的浏览器环境。
• ECHO 设置页显示的 Spotify Redirect URI。
• 如果要播放 Spotify 内容，账号和地区权限仍然要符合 Spotify 自己的要求。

创建 Spotify App

1. 打开 Spotify Developer Dashboard。
2. 登录你的 Spotify 账号。
3. 点击 Create app。
4. App name 可以填 ECHO Next Local。
5. App description 可以填 Personal local music client。
6. Website 如果必填，可以填 ECHO 项目主页或留一个你自己的说明页；如果后台允许留空，可以不填。
7. Redirect URI 填 ECHO 页面显示的地址，默认是：

http://127.0.0.1:43879/spotify/callback

8. 勾选开发者条款并创建 App。
9. 进入 App 详情页，找到 Client ID。
10. 复制 Client ID，回到 ECHO 粘贴到 Spotify Client ID。
11. 点击 保存 Spotify 配置。
12. 回到 Spotify 账号登录入口，重新登录。

Spotify 后台应该填哪里

在 Spotify App 页面里找 Settings 或 Edit Settings：

• Redirect URIs：添加 ECHO 显示的回调地址。
• Client ID：复制到 ECHO。
• Client Secret：ECHO 不需要，不要填到 ECHO，也不要分享。

Spotify 官方对 Redirect URI 有更严格的校验。本地地址应使用明确的 loopback IP，例如 127.0.0.1；不要为了好看改成 localhost。

Spotify Development Mode

新建 Spotify App 可能处于 Development Mode。这个模式下：

• App 默认只能给开发/测试用户使用。
• 未加入测试用户列表的账号可能登录失败，或登录后 API 请求失败。
• 如果你只是自己使用自己的 Spotify App，一般不需要额外处理。
• 如果要让别人使用你的 Client ID，需要在 Spotify Dashboard 的 Users Management 里添加对方 Spotify 邮箱。
• 如果要公开给大量用户，需要按 Spotify 的流程申请更高额度或公开访问。

Spotify 常见错误

INVALID_CLIENT: Invalid redirect URI
回调地址不匹配。复制 ECHO 页面里的 Redirect URI，完整粘贴到 Spotify App 的 Redirect URIs，保存后再试。

The user is not registered for this application
当前 Spotify 账号没有被加入这个 Developer App 的测试用户。用自己的 App 登录，或让 App 拥有者把你的 Spotify 邮箱加入 Users Management。

登录后仍然不能播放
这通常不是 Client ID 填错，而是 Spotify Premium、地区版权、设备可用性、Spotify Connect/Web Playback 限制等问题。

TIDAL Developer 配置

TIDAL 配置用于 catalog 元数据搜索。这里说的 catalog 是专辑、曲目、艺人等元数据，不代表 ECHO 会接入或下载 TIDAL 播放流。

你需要准备

• 一个 TIDAL 账号。
• 可以访问 TIDAL Developer Portal。
• ECHO 设置页显示的 TIDAL Redirect URI。
• 目标 catalog 的国家/地区代码。

创建 TIDAL App

1. 打开 TIDAL Developer Portal。
2. 使用 TIDAL 账号登录。
3. 如果首次进入，按页面提示接受开发者指南/条款。
4. 进入 Dashboard。
5. 创建一个 App。名称可以填 ECHO Next Local。
6. 创建后进入 App 详情页。
7. 找到 Client ID，复制到 ECHO 的 TIDAL Client ID。
8. 找到 Client Secret，复制到 ECHO 的 TIDAL Client Secret。
9. 在 App 设置或 Redirect URI 设置里添加 ECHO 显示的回调地址，默认是：

http://127.0.0.1:43880/tidal/callback

10. 回到 ECHO，确认 TIDAL Redirect URI 和后台完全一致。
11. Country Code 填两位国家/地区代码。
12. 点击 保存 TIDAL 配置。

TIDAL Country Code 怎么选

Country Code 影响 TIDAL catalog 查询结果。常见示例：

US
HK
JP
GB
DE
FR
CN

建议这样选：

• 你的 TIDAL 账号主要在哪个地区使用，就先填哪个地区。
• 想查国际曲库，先用 US。
• 想查香港常见内容，填 HK。
• 想查日本内容，填 JP。
• 查不到某些专辑时，可以换一个地区再试，因为不同地区 catalog 可用性不同。

TIDAL 常见错误

保存后搜索没有结果
先检查 Client ID 和 Client Secret 是否来自同一个 TIDAL App，再检查 Country Code 是否是两位大写代码。

提示认证失败或 unauthorized
通常是 Client Secret 复制错、凭据被重置、App 没保存成功，或者复制时多了空格。

找不到 Client Secret
TIDAL 后台可能会隐藏 Secret。通常需要点击显示按钮，或输入 TIDAL 账号密码确认后才能查看。

Discogs 专辑评分

Discogs token 用于查询 Discogs 的专辑、版本、评分等辅助资料。没有 token 时，ECHO 仍然可以播放和管理本地音乐，只是 Discogs 来源不可用或更容易被限流。

获取 Personal Access Token

1. 登录 Discogs。
2. 打开 Discogs Developers 设置页。
3. 找到 Personal access token。
4. 如果页面提供生成按钮，生成一个新的 token。
5. 复制 token。
6. 回到 ECHO，粘贴到 Discogs personal access token。
7. 点击 保存 Discogs Token。

Discogs 这里不要填什么

不要填这些：

• Consumer Key
• Consumer Secret
• OAuth 回调地址
• Discogs 密码

ECHO 这个字段要的是 Personal access token。它适合个人本地使用，不需要你额外实现完整 OAuth 流程。

Discogs 常见错误

查不到评分
可能是专辑名、艺人名、版本信息不够准确；也可能 Discogs 没有对应条目。

401 或认证失败
token 复制错、token 被撤销，或者粘贴时多了空格。重新生成 token 再保存。

结果很慢或偶尔失败
Discogs 有接口限制。等待一会儿再查，或者减少批量查询频率。

在线歌手/演出信息

这一组用于补充艺人资料、巡演和演出信息。全部是可选项。一个来源不可用时，ECHO 可以跳过它继续尝试其它来源。

Bandsintown app_id

Bandsintown app_id 是 Bandsintown API 用来识别调用方的 app 标识。不同入口显示的名字可能不完全一样，可能叫：

• app_id
• App ID
• API key
• 合作方提供的 app 标识

如果你有 Bandsintown API 权限：

1. 登录 Bandsintown 的开发者、合作方或 API 管理入口。
2. 找到你的应用或 API 凭据。
3. 复制 app_id。
4. 回到 ECHO，填入 Bandsintown app_id。
5. 保存配置。

如果你没有 Bandsintown API 权限，直接留空即可。ECHO 会跳过 Bandsintown，不影响 Spotify、TIDAL、Discogs 或其它演出来源。

Ticketmaster apikey

Ticketmaster Discovery API 使用 apikey 查询参数。Ticketmaster Developer Portal 里常见的字段名是 Consumer Key，它就是 ECHO 这里要填的 Ticketmaster apikey。

1. 打开 Ticketmaster Developer Portal。
2. 注册或登录开发者账号。
3. 进入 My Apps、Applications 或类似页面。
4. 创建一个 Application，或打开默认生成的 Application。
5. 找到 Consumer Key。
6. 复制 Consumer Key。
7. 回到 ECHO，粘贴到 Ticketmaster apikey。
8. 点击保存。

不要把 Consumer Secret 填到 Ticketmaster apikey。如果 Ticketmaster 页面同时显示多个 key，优先找用于 Discovery API 请求的 Consumer Key。

SeatGeek client_id

SeatGeek API 请求可以通过 client_id 查询参数携带公开 key。ECHO 这里只需要公开 client_id，不要求填写 client_secret。

1. 打开 SeatGeek Developer Portal。
2. 注册或登录账号。
3. 按页面要求申请 API access 或创建应用。
4. 找到公开 key、public key 或 client_id。
5. 复制到 ECHO 的 SeatGeek client_id。
6. 保存配置。

如果 SeatGeek 页面只给了申请入口，说明你的账号可能还没有开通 API access。先提交申请；没申请到之前保持留空。

地区过滤怎么填

地区过滤 用于减少在线演出/艺人资料的噪音。它和 TIDAL Country Code 不是同一个东西：

• TIDAL Country Code：影响 TIDAL catalog 元数据查询。
• 地区过滤：影响在线歌手/演出信息的筛选。

可以填国家代码、城市名或常用地区关键词，多个值用英文逗号分隔：

HK, Tokyo, US

常见填法：

想看的范围	推荐填写
香港附近	HK
东京/日本	Tokyo, JP
美国	US
欧美都想看	US, GB, DE, FR
尽量查全	留空

不要填太多太散的关键词。地区过滤越宽，结果越多，也越容易混入无关演出；过滤越窄，结果更干净，但可能漏掉数据。

填完以后怎么验证

Spotify

1. 保存 Spotify 配置。
2. 重新点击 Spotify 登录。
3. 浏览器打开授权页。
4. 授权后能回到 ECHO，说明 Redirect URI 基本正确。
5. 如果登录页直接报错，优先检查 Redirect URI。

TIDAL

1. 保存 TIDAL 配置。
2. 找一首常见歌曲或专辑重新触发在线元数据查询。
3. 如果完全没有结果，先换 Country Code 为 US 再试。
4. 如果提示认证失败，重新复制 Client Secret。

Discogs

1. 保存 Discogs Token。
2. 找一张 Discogs 上肯定存在的专辑。
3. 重新触发元数据/评分查询。
4. 如果失败，重新生成 Personal access token。

在线歌手信息

1. 至少填一个来源，例如 Ticketmaster 或 SeatGeek。
2. 地区过滤先填一个简单值，例如 HK 或 US。
3. 清理艺人资料缓存后重新查询。
4. 如果没有结果，先留空地区过滤，确认是不是过滤太窄。

常见填错对照表

现象	最可能原因	处理方式
Spotify 报 Invalid redirect URI	回调地址不完全一致	复制 ECHO 的 Redirect URI 到 Spotify 后台
Spotify 报用户未注册	Development Mode 用户限制	在 Spotify Users Management 添加账号
TIDAL unauthorized	Secret 错、凭据不是同一个 App、复制多了空格	重新复制 Client ID/Secret
TIDAL 查不到内容	Country Code 地区无此 catalog	换 US、HK、JP 试
Discogs 401	token 错或失效	重新生成 Personal access token
Ticketmaster 401	apikey 填错	填后台的 Consumer Key
SeatGeek 没结果	client_id 无效或未开通 API	检查 API access，或先留空
演出结果太乱	地区过滤太宽	填更具体的城市/国家代码
演出结果为空	地区过滤太窄	清空地区过滤再试

建议的最终配置

自己本地使用，比较稳妥的配置方式是：

Spotify Client ID: 只填自己的 Spotify App Client ID
Spotify Redirect URI: 保持 ECHO 默认值
TIDAL Client ID: 填自己的 TIDAL App Client ID
TIDAL Client Secret: 填自己的 TIDAL App Client Secret
TIDAL Country Code: US 或自己的账号地区
Discogs personal access token: 填自己的 personal access token
Bandsintown app_id: 没有就留空
Ticketmaster apikey: 有 Developer Portal Consumer Key 就填
SeatGeek client_id: 有 API access 就填
地区过滤: 先填一个最常用地区，例如 HK

遇到问题时，先把可选的在线歌手来源留空，只保留你正在验证的那个来源。这样最容易判断到底是哪一项配置有问题。

官方参考

• Spotify Apps
• Spotify Redirect URIs
• TIDAL Manage apps
• TIDAL Authorization
• Discogs Developers 设置页
• Ticketmaster Discovery API
• SeatGeek API 文档