rockerlabs/podflick

# PodFlick 将视频拖放至你的经典 iPod (5G/5.5G) —— 无需 iTunes。 PodFlick 通过 ffmpeg 将任何视频转换为 iPod Video 规格（H.264 baseline ≤640×480 ≤1.5 Mbps + AAC），并经过在实际硬件上验证过的精准原地编辑操作， 直接将其写入设备的 `iTunesDB` 中。同时兼容 Mac 格式 (HFS+) 和 Windows 格式 （FAT32，包括 Rockbox 双启动）的 iPod。 ## 安装说明 **[⬇ 下载 PodFlick.dmg](https://github.com/rockerlabs/podflick/releases/latest/download/PodFlick.dmg)** （始终为最新版本）—— 打开它并将 **PodFlick** 拖入 **应用程序 (Applications)**。 这就是全部的安装过程：该 App 已经过签名和 **公证**（打开时不会出现 “身份不明的开发者”警告），且 **内置 ffmpeg**，因此不需要执行 `brew install`。 系统要求：**Apple Silicon (arm64)，macOS 14+**，以及一个作为磁盘挂载的 iPod Video 5G/5.5G 。（将本 App 移至 `/Applications` 还会注册 Finder 的 **传输到 iPod** 服务 —— 见下文。） 特定版本或普通的 `.zip` 文件可以在 [发布页面](https://github.com/rockerlabs/podflick/releases) 找到。 ## 状态 **PodFlick 1.0 已发布** —— 请参阅 [更新日志](CHANGELOG.md)。iTunesDB 引擎已在真实硬件上完成了端到端的验证；Python 参考实现及标准测试数据位于 [`reference/`](reference/)，格式规范说明位于 [docs/itunesdb-format.md](docs/itunesdb-format.md)。 ## 从源码构建 ``` brew install xcodegen ffmpeg cp Signing.xcconfig.template Signing.local.xcconfig # set DEVELOPMENT_TEAM xcodegen generate xcodebuild -project PodFlick.xcodeproj -scheme PodFlick build ``` 构建要求：macOS 14+, Xcode 15+, 以及位于 `PATH` 中的 `ffmpeg`。 ## 后台传输（Finder 服务 + URL scheme） 除了主窗口外，PodFlick 可以在你无需先打开 App 的情况下接收视频： - **Finder** —— 右键点击视频 → **服务 → 传输到 iPod**。 - **Shortcuts / Automator** —— 打开 `podflick://transfer?path=/abs/clip.mp4` URL（通过重复 `&path=` 来传输多个文件）。 无论哪种方式，App 都会在后台进行转换和写入：没有窗口，只有一个 显示进度的菜单栏项目以及 **弹出** 操作，外加一个完成通知。 完整的硬件冒烟测试步骤：[docs/smoke-service-transfer.md](docs/smoke-service-transfer.md)。 ## 已知问题与限制 这些是 PodFlick 无法改变的设备与平台级别的行为，以及一些故障排查提示。 它们本身都不是传输过程中的 Bug。 - **全新转换的视频在首次打开时可能会黑屏。** 刚传输完的视频 在*首次*启动时可能会显示黑屏 —— 按键无响应大约 10–15 秒，随后退回到菜单。 第二次播放时即可正常观看（320×240 和 640×480 均如此）。这是 iPod 固件中早已存在的 小问题（首次打开时的索引/缩略图生成），在 5G 和 5.5G 上均会出现 —— 使用其他工具制作的视频也会遇到这种情况，并非 PodFlick 独有。 - **App 中的型号 / 固件 / 序列号可能会显示为空白。** 曾经恢复过或 为 Rockbox 设置过的 iPod 通常会有一个空（0 字节）的 `Device/SysInfo`， 因此这些信息字段会保持空白。格式和容量仍然可以正常显示。 这反映的是设备本身的状态，而不是 PodFlick 的问题。 - **请在原厂 Apple 固件下播放 PodFlick 的视频。** 视频片段是为 经典固件的硬件解码器编码的。在 Rockbox 双启动的 iPod 上，浏览和 听音乐可以在 Rockbox 下进行，但观看传输好的视频需要启动回原始的 Apple 固件。 - **平台支持范围较窄。** 仅限 Apple Silicon (arm64) 和 macOS 14+ —— 不支持 Intel Mac —— 目标设备也仅限于 iPod Video 5G/5.5G。 - **如果 iPod 不断挂载和卸载（反复横跳），** 请优先尝试更换 USB 线。如果设备挂载一秒后就断开，并不断 重复，这几乎总是因为线材损坏或接触不良，而不是 PodFlick 的问题。 - **找不到 Finder 的“传输到 iPod”选项？** 只有当 `PodFlick.app` 位于 `/Applications` 时它才会出现 —— 请参阅 [后台传输](#background-transfer-finder-service--url-scheme)。 ## 许可证 PodFlick 自身的代码基于 [MIT License](LICENSE) 发布。 **ffmpeg。** PodFlick 将 `ffmpeg`/`ffprobe` 作为独立的子进程 调用 —— 它从不对它们进行链接，因此其自身的源码无论如何都保持 MIT 许可： - **源码检出 / Homebrew 开发构建** 不包含 ffmpeg；它们使用的是 你自行安装的 ffmpeg（`brew install ffmpeg`），其许可证随 你的副本保留。 - **已公证的发布版本** 内置了基于 **LGPL v2.1** 的 ffmpeg/ffprobe（构建时 未包含任何 GPL 或非自由组件）。合规包 —— 包含许可证文本、 精确的源码版本号、构建/配置命令，以及提供对应 源码的书面声明 —— 位于 [`licenses/ffmpeg/`](licenses/ffmpeg/)。 iTunesDB 读写层是对设备端格式的独立、字节级别的逆向工程 （参见 [docs/itunesdb-format.md](docs/itunesdb-format.md)）； 没有使用或派生自任何第三方数据库库。 ### 商标 “iPod” 和 “iTunes” 是 Apple Inc. 的商标。PodFlick 提及它们仅 用于描述其适用的硬件（合理使用），并且不附带任何 Apple 的艺术作品或图标。PodFlick 是一个独立的开源项目 —— 不附属于 Apple Inc.，也未获得其认可或赞助。App 的“关于”面板中也会显示相同的声明。

标签：ffmpeg, iPod, macOS应用, Swift, 媒体同步, 音视频转换