企业官网建设流程全解析

Sonora 是一款用 Rust 和 GPUI 构建的原生音乐串流客户端，内置 Scrobble（听歌数据上报）功能，只需一次简单设置，就能把你的每次收听自动同步到 Last.fm 和 ListenBrainz——听歌历史一键同步，无需任何插件或手动操作。

本指南将带你用 3 分钟完成 Last.fm 连接，再用 1 分钟打通 ListenBrainz，并解释 Sonora 判定"一次有效收听"的规则，让你的听歌数据从此不再丢失 🎧

什么是 Scrobble？Sonora 内置了什么

Scrobble 是指把你"正在听什么"和"刚刚听完什么"自动上报给第三方音乐数据服务的机制。Sonora 原生支持4 个 Scrobble 服务，全部在设置页面内完成绑定：

4 个服务的注册顺序与定义见 crates/music/src/scrobble/mod.rs。

Sonora 如何判定"这一次真的听了"

不是按下播放就算数。Sonora 遵循业界通用的收听规则（源自 Last.fm，其余服务也沿用）：

• ⏱️ 歌曲总长不足 30 秒：无论播放多久都不计入
• ⏱️ 连续播放满 4 分钟：一定计入
• ⏱️ 播放超过歌曲总时长的一半：计入

规则实现见 crates/music/src/scrobble/mod.rs#L15-L16 和 earned() 方法。

3分钟连接Last.fm：API key获取与授权步骤

Last.fm 采用经典的 AudioScrobbler 协议，是 Sonora 中唯一一个需要你自己创建 API 凭据的服务（源码：crates/music/src/scrobble/audioscrobbler.rs）。

操作步骤：

1. 登录你的 Last.fm 账号，进入 Last.fm 开发者后台，创建一个 API 项目，记下API key和API secret
2. 打开 Sonora 的设置 → Scrobbling分组，找到 Last.fm 一行，点击Connect（连接）
3. 在弹出的对话框中粘贴 API key 和 API secret，提交
4. Sonora 会自动打开浏览器跳转到 Last.fm 授权页——点击同意即可
5. 浏览器显示 "Sonora is connected. You can close this window." 时，设置页状态变为Connected

💡 小贴士：Sonora 在本地监听回调，浏览器授权最长等待5 分钟（audioscrobbler.rs#L18），如果浏览器没有自动打开，手动在浏览器中完成授权也行。

1分钟连接ListenBrainz：User Token获取方法

ListenBrainz 的连接最简单——只需要一个 Token：

1. 登录 ListenBrainz 官网，进入个人设置页，找到User Token并复制
2. 回到 Sonora 设置页，点击 ListenBrainz 一行的Connect，粘贴 Token
3. Sonora 会调用validate-token接口验证（crates/music/src/scrobble/listenbrainz.rs#L41-L54），通过后即显示Scrobbling as 你的用户名

整个过程不到 1 分钟。此外，ListenBrainz 还兼容自托管实例：在账户设置中填入服务器地址即可切换到自建服务，无需第二个字段。

在Sonora设置中打开Scrobble开关

所有 Scrobble 服务集中在设置页面底部的 Scrobbling 分组，每个服务一行，界面逻辑见 crates/views/src/screens/settings.rs#L3192-L3260。每行有三种交互：

• Connect / Disconnect：绑定或解绑账号
• 开关（Toggle）：临时暂停某个服务的同步，账号绑定不会丢失
• 状态文案：Not connected（未连接）/ Scrobbling as xxx（以 xxx 身份同步中）/ Waiting for your browser…（等待浏览器授权）

对应文案定义在 assets/i18n/en-US/main.ftl#L715-L736。

听歌数据去哪了？Sonora自动同步机制详解

绑定完成后一切全自动，无需干预。整个调度由一个中心实体驱动（crates/state/src/scrobble.rs）：

• 🎵开始播放：立即向支持的服务上报Now Playing（Maloja 没有此概念，自动跳过）
• ⏸️暂停 / 拖动进度：恢复播放同一首歌时保留最初开始时间，收听时长始终从真正开始那一刻计算
• ✅满足收听规则：自动提交 Scrobble，批量发送（Last.fm 和 ListenBrainz 单次最多携带 50 条）
• 🔄双份记账：除了第三方服务，Song 的来源服务器（如 Subsonic/Navidrome）也会同步更新它的播放计数和正在播放列表
• 🛡️故障隔离：每个服务独立发送，某个服务挂了不会连累其他服务丢失收听记录

常见问题FAQ

Q1：为什么某首歌没有同步？歌曲时长不足 30 秒，或你播放时长未过半、也未满 4 分钟——这是正常的防刷机制。

Q2：浏览器授权页一直没反应？等待上限为 5 分钟，超时后状态回到未连接；也可以直接点Cancel取消，随时重新发起。

Q3：同步失败会有提示吗？界面上失败状态显示为 "Could not connect"，具体错误写入运行日志，可据此排查（如 token 过期、API key 错误）。

Q4：可以同时开多个服务吗？可以。Last.fm、ListenBrainz 等可以同时启用，一次收听会扇出到所有已启用的服务。

小结

Sonora 把 Scrobble 做成了"设置页里的一行开关"：Last.fm 用 API key + 浏览器授权 3 分钟搞定，ListenBrainz 粘贴一个 Token 即连即用，Maloja 支持自托管服务器。连接一次，之后的每次收听都会按行业标准规则自动同步，听歌历史从此完整可查 📈