Repository navigation
Releases
v0.3.3
v0.3.2 — 进度页 + 数据库修复
新增
-
★ 「进度」页:同步/下载全程看得见在干什么**。
以前同步 147 首到 iPod,界面在最长的那一段(无损档要把每首 FLAC 转成
ALAC,加上往设备里拷 3.3 GB,实测 6 分钟)什么都不显示——进度条停在
0% 一动不动,看起来就是卡死了。现在:- 进度条上方显示当前阶段:读取歌单 → 下载到本地 → 读取本地文件 →
写入 iPod → 把 N MB 刷到设备 → 重建数据库并签名 - 每一段按自己的总数算百分比;不会拿「下载了 3/3」去比「要写 147 个文件」
- 切不出等份的步骤(刷盘、整库重写)显示一直在滚的条,并写明
「它在滚就说明没卡住」——以前这里画的是停在 0% 的死条 - 显示已用时间;剩余时间按当前这一步的速度算
左侧导航的「下载」改名「进度」,因为它现在同时管下载和同步。
- 进度条上方显示当前阶段:读取歌单 → 下载到本地 → 读取本地文件 →
-
★ 「数据库修复」:扫出数据库和磁盘对不上的地方,勾选后清掉。
「iPod 音乐管理」页新增一个按钮。扫完会列出三类,每一项都写明后果:
类别 现象 处理 孤儿文件 磁盘上有、数据库不认 删文件。iPod 上看不见它们,但白占空间 残留临时文件 写入被打断留下的中间文件 删文件 断链记录 数据库有记录、磁盘没文件 删记录。iPod 上显示得出来但播不了 孤儿文件是怎么来的:同步是「先拷文件、再写数据库」两步。第二步失败
(异常、或者进程被杀),文件已经在设备上了,而 iPod 的界面只认数据库 ——
于是它们既看不见、又占着空间,下次同步还会重新分配文件名再拷一遍,
失败一次多一份。实测在一台设备上堆到过 294 个文件、6.4 GB。几处刻意的设计:
- 断链记录默认不勾。它要重写整个数据库,风险最高,必须用户自己勾
(界面上也会写明"其他歌不会丢")。 - 清理时重新扫一遍,不用界面上那份清单。从扫到点确认可能过了几分钟,
设备也许被外部改过;重扫最多多花几秒,但保证删的每一刀看的是当前状态。 - 路径比对折叠大小写。iPod 是 FAT32,大小写回显不一致;按敏感去比
会把正常文件判成孤儿然后删掉。 - 数据库读不出来时给中文原因和下一步("先在电脑上用 iTunes / Finder 看一眼
……必要时用备份恢复"),而不是甩一个InsufficientDataError。
- 断链记录默认不勾。它要重写整个数据库,风险最高,必须用户自己勾
变更
-
★ 删掉界面上的「健康检查」(「iPod 音乐管理」页那个按钮)。
它只诊断不动手,而结论写在一个看不到的地方:点完只弹一句"已开始
健康检查,到「下载」页看结果",可那页根本不显示这类作业 —— 于是它唯一
的用途就是让人以为"检查过了,没问题"。更糟的是它那句总结:找到 6 个孤儿文件时,报告里写的是**「检查完成:
全部通过」**("警告"不算"失败")。同一台设备上,「数据库修复」一扫就报
出 7 个问题。从外面看,这就是个假功能。现在这一步由「数据库修复」接手:它会扫、会说出来、也能直接清掉。
- 命令行那条
ipod verify保留 —— 它是排查设备用的诊断工具
(查签名、封面、播放列表、备份),跟界面上的按钮不是一回事。 - 设备验收脚本(
tools/verify_device_flow.py)里那一步也换成了
数据库修复扫描。
- 命令行那条
修复
-
★ 「下载好了无法同步」——确认对话框上的按钮写着「开始同步 0 首」。
先下载到本地、再点同步,
需要下载必然是 0(都已经下好了)。而那个按钮
显示的是"需要下载几首",于是恒显示 「开始同步 0 首」——看起来像没东西
可同步,或者像坏了,用户就不会点它。同步作业因此从来没提交过。按钮现在显示"要同步几首",并且把两个数字分开写清楚:
要同步 147 首/本地已有(不用再下)147 首/ 有需要下载时才写
其中需要先下载 N 首。 -
★ 写数据库失败时不再在设备上留垃圾文件。
同步是"先拷文件、再写数据库"两步。以前第二步失败(异常,或者进程被关掉),
已经拷进去的文件就留在设备上了——而 iPod 的界面只认数据库,于是这些文件
既看不见、又白占空间,下次同步还会重新分配文件名再拷一遍,失败一次多
一份。实测一台机器上就这样堆到 294 个孤儿文件、6.4 GB。现在写库失败会把这次拷进去的文件撤掉。已经堆出来的可以用新加的
tools/find_orphans.py清理(默认只列不删):uv run python tools/find_orphans.py --ipod D:\ # 只看 uv run python tools/find_orphans.py --ipod D:\ --delete # 真删
-
★ 网络请求没有"总时长"上限,能把同步拖死(这就是"同步 147 首时应用
卡到未响应"的原因)。urllib.request.urlopen(url, timeout=N)里的timeout是每次 recv 的超时,
不是"这个请求总共最多花多久"。服务器只要慢慢吐数据(响应头分几次发、
或者每几十秒给一点),每次 recv 都算"没超时",于是这个 timeout
永远不会触发。实测抓到的调用栈(同步 147 首时):
ssl.py in read ← 一直在等网络 http/client.py in _read_status ncm/client.py in cover_bytes ncm/downloader.py in download_song它就在等一个迟迟不来的响应,而 socket 超时救不了它。表现是整个应用
无响应(界面每个请求都跟着排队),Windows 最后判定"未响应"。现在读响应时自己掐墙钟:音频下载 5 分钟、封面 1 分钟、接口 1 分钟。
超时就报错跳过,不会无限等。补充说明:这一次同步最终是成功的(147 首全部写入、封面齐全、
播放列表也建好了),只是它爬了 9 分半钟,期间界面完全没反应——
所以看起来像"卡死了"。现在这种长时间静默会变成明确的超时错误。 -
作业卡住时会自动把现场写进日志(应用不再"无声无息地卡死")。
以前作业一旦卡在某个阻塞调用里,日志就停在那儿,完全看不出卡在哪一行。
现在有看门狗盯着:60 秒没有任何进展就把所有线程的调用栈打进日志
文件(并在界面上提示"把日志发给开发者")。这条是给"同步大量无损文件时应用卡到未响应"那次加的——当时翻遍日志只知道
它停在某一步之前,具体位置查不出来。下次再出现,日志里会直接有答案。
v0.3.1 — 状态维护修好了
v0.3.1 — 状态维护修好了
这一版全是修 bug。三个都是静默的:不报错,只是"用着觉得不对"。
1. 装了新版本之后,歌单页全部显示「未下载」
下载记录里存的是相对路径,而相对路径按当前工作目录解析——从解压出来的
发行版目录启动时,那条路径指向了不存在的地方。
接着是更要命的一步:判定"文件找不到"之后,代码把记录删掉了(当成脏数据
自愈)。判据错了就删数据,是不可逆的:实测那 7 条记录全被判成脏的,而文件
好好地躺在缓存目录里。
现在:相对路径一律按数据目录解析,找不到文件只停止计数、不删记录。
2. 设备状态是从状态库"回忆"出来的,不是扫描 iPod 数据库
判断"这首歌在不在 iPod 上"时,代码遍历的是状态库里的同步记录——方向反了:
设备上有多少歌,取决于我们记过多少条。
实测:iPod 里 130 首,状态库里只有 10 条记录 → 另外 120 首在界面上全显示
"iPod 上没有",而它们明明在设备里。
现在改成拿歌去问设备库。同一份数据从"认到 1 首"变成"认到 39 首"。
顺带修掉两个同病根的问题:
- 设备上的曲目改成按歌名 + 艺人认(不再只认文件名位置)。iPod 上的文件名
是随机的,数据库被重建过之后位置就变了,明明在设备上的歌会被判成"没同步过"
→ 下次同步再导一遍,歌就重复。 - 同步时算歌单成员以前也只认状态库里有的记录 → 从命令行、旧版本、别的数据
目录导进去的歌永远进不了 iPod 上的歌单。
只按歌名认是不够的:同名常常是不同录音——歌单里"普通朋友"是宋雨琦、
设备上是陶喆,"天天"是刘大拿对陶喆的。只比歌名会把翻唱当成同一首。
3. 状态显示分成两个维度
每行两个徽章:本地已有 / 本地没有 + iPod 上已有 / iPod 上没有 / 未插 iPod。
- 「未下载」现在只看本地。以前先看设备,于是"设备上有、本地没留"的歌被归进
「已同步」,「一键选中所有未下载的」永远选不到它,右键菜单的「下载到本地」
也跟着置灰——这就是"未下载已同步却下不了"。 - 没插设备时明说「未插设备(状态未知)」,不再假装"设备上一首都没有"。
- 每个动作有各自的判据和理由。
4. 发行包里不再有 启动.bat
它早期有实际用途(旧版要用户自己装 node,脚本负责检查并提示),node 打进包里
之后只剩两句 shell,都不必要。直接双击 ipod_manager.exe 就是完整用法——
程序是 GUI 程序(双击不弹黑窗),启动不依赖工作目录,数据在 %APPDATA%。
5. 新增更新日志
见 CHANGELOG.md。
README 另加「常见问题」:音质三档为什么只有三档、低音失真的排查方法
(量真峰值,超 0 dBTP 就是音源本身削波——实测 8 首里 6 首如此)、
以及本工具不动音频的说明(原生格式原样拷贝,flac 转无损 ALAC)。
安装
下载下面的 zip,解压到任意位置,双击 ipod_manager.exe。不需要 Python / node / uv。
⚠️ 仅供个人学习与自用。不内置、不分发任何音乐内容。详见仓库 README 的免责声明。
v0.3.0 — 歌单管理
v0.3.0 — 歌单管理
新功能
- iPod 播放列表管理:「iPod 音乐管理」页顶部加了「全部歌曲 / 歌单」切换,
可以新建、改名、删除播放列表,把歌加进去 / 移出来。 - 同步时按在线歌单在 iPod 上建同名播放列表(这条本来就有,这版把它和手动管理接上了)。
修掉两个真 bug(都影响同步路径,不只是新功能)
- 普通歌单被克隆进播客数据集:每写一次库就多一份重复歌单,界面上同一个歌单显示两条,
删了像没删掉。 - 改歌单会换掉它的身份(playlist_id):刚拿到的 id 立刻失效(下一步操作 404);
更麻烦的是同步每跑一次,同名播放列表就换一个 id,设备上按 id 引用它的东西就断了。
其他
- 自带 node 运行时和网易云 API(上一版就打了),解压即用,不用装任何东西。
- 日志转发时脱敏:不再把网易云的登录 cookie 写进日志文件。
- 版本号统一到 0.3.0(此前代码里是 0.1.0、包名是 0.2.0,对不上)。
安装
下载下面的 zip,解压到任意位置,双击 启动.bat。不需要 Python / node / uv,也不需要联网初始化。
数据在 %APPDATA%\com.example\ipod_manager\data\.ncm\;出问题先看那里的 logs/。
⚠️ 仅供个人学习与自用。不内置、不分发任何音乐内容。详见仓库 README 的免责声明。
v0.1.0 — 首个发行版(Windows x64)
把网易云音乐的歌单和「喜欢的歌」下载到电脑,再自动同步进 iPod Classic。
命令行 + 中文 Flutter 桌面端。
⚠️ 免责声明:本软件仅供学习与个人技术研究使用;禁止用于任何商业用途;
严禁用于盗版传播。本工具不提供、不内置、不分发任何音乐内容,也不绕过任何付费
机制——所有音乐均来自使用者自己的账号,仅供个人在自有设备上收听。
这个版本能做什么
- 扫码登录网易云 → 浏览歌单(含「喜欢的歌」,顺序与 App 一致)
- 每首歌标出状态:未下载 / 已下载 / 已同步,可搜索、可多选
- 下载(严格串行 + 限速,不碰风控),或一步到位:下载 + 写进 iPod
- 封面(ArtworkDB / .ithmb)、播放列表、播放次数都正确写入
- 写库前自动备份整个
iPod_Control,写后读回校验
下载后怎么用
- 解压到一个固定位置(别放桌面再挪走)
- 双击
启动.bat(不要直接开 exe——bat 会先检查依赖) - 需要预装 uv(必需):
winget install astral-sh.uv - 首次启动会自动装 Python 依赖,约 1 分钟,只需一次
- 想用「从网易云下载」还需要 node + 本地跑起
api-enhanced(端口改成 4000)。
只把本地已有的音乐导进 iPod 的话不需要。
详细说明见包里的 使用说明.txt,以及
README。
实测状态
在 Windows 10.0.26100 + iPod Classic 6th Gen 80GB(A1238)上完整跑通:
同步、封面写入、删除、备份还原、播放列表重建。测试 555 项(Python)+ 71 项(Flutter)全绿。
没有在其它 iPod 型号上验证过——代码是按 Classic 全代(HASH58 签名)写的,
Nano/Shuffle 等请自行判断风险,写入前务必先备份。
许可
MIT。src/iopenpod/ 裁剪自 iOpenPod(MIT),
另见 THIRD_PARTY_NOTICES.md。