Create custom catalogs at scale with ShazamKit
System & Services 进阶 20m

大规模构建 ShazamKit 自定义目录

Create custom catalogs at scale with ShazamKit

2022年6月6日

在 Apple 官方观看视频

一句话判断

ShazamKit 新增的命令行工具和 signatureFromAsset API，让批量生成音频签名和自定义目录从手动编程变成了脚本自动化，特别适合内容规模大的场景。

这场 Session 讲了什么

WWDC 2021 引入了 ShazamKit 的自定义目录功能，允许开发者匹配自己的音频内容并提供同步体验。但手动处理大量音频文件（比如 10 季电视剧）的工作流非常痛苦：需要手动处理采样率、音频缓冲区、元数据关联等底层细节。

今年的更新直击痛点。首先，mac 13 内置了 Shazam CLI 命令行工具，支持签名生成、目录创建/更新/展示等全流程操作。配合 CSV 文件描述媒体元数据，可以用脚本批量处理整个内容库。其次，SHSignatureGenerator 新增了 signatureFromAsset 方法，直接接受 AVAsset，无需手动处理音频缓冲区。第三，匹配结果现在通过 AsyncSequence 返回，代码结构大幅简化。

Session 用 FoodMath 教学视频 App 做完整演示，展示了如何用 CLI 工具和简单脚本，在几分钟内为多集内容创建完整的同步体验。

值得深挖的点

  • Shazam CLI 的完整命令集：signature（从媒体文件生成签名）、create（组合签名和 CSV 元数据创建目录）、update（向已有目录追加内容）、display（查看目录内容）、add/remove/export（管理签名和媒体条目）。这些命令可以轻松串联成自动化脚本。
  • CSV 元数据映射：CSV 的列名直接映射到 MediaItem 的属性。运行 create 命令加 --help 可以查看完整的映射关系。还支持自定义 JSON 字段，灵活性很高。
  • AsyncSequence 匹配接口：新接口用 for await 循环处理匹配结果，返回值是枚举类型（match/noMatch/error），比老版的 delegate 回调清晰得多。只关心匹配结果时，用 case .match 过滤即可。
  • signatureFromAsset 的跨平台支持：这个 API 在所有平台上都可用。如果你的资产包含多个音轨，ShazamKit 会自动混音，确保签名捕捉到所有音频内容。

代码片段

// 使用新的 AsyncSequence 接口处理匹配结果
let session = SHSession()
// ... 配置 session

for await result in session.results {
    switch result {
    case .match(let match):
        // 从媒体条目中提取自定义数据
        let items = match.mediaItems.map { item in
            // item.fields 包含你在 CSV 中定义的所有字段
            return MatchResult(
                title: item.title ?? "",
                equation: item.fields["equation"] as? String ?? ""
            )
        }
    case .noMatch:
        break
    case .error:
        break
    }
}

// 从 AVAsset 直接生成签名，无需手动处理音频缓冲区
let asset = AVAsset(url: videoURL)
let signature = try await SHSignatureGenerator.signatureFromAsset(asset)
# CLI 批量处理脚本示例
for dir in episodes/*/; do
    shazam signature "$dir/video.mp4" -o "$dir/signature.shazamsig"
    shazam create "$dir/signature.shazamsig" "$dir/media.csv" \
        -o "catalog.shazamcatalog"
done
shazam display catalog.shazamcatalog

最佳实践

  • 用脚本自动化目录生成流程，内容更新时只需重新运行脚本
  • CSV 中的自定义 JSON 字段可以存储任意同步数据（比如时间点、显示文本、题目内容），匹配后直接从 MediaItem 的 fields 字典中读取
  • 目录文件支持增量更新——用 update 命令向已有目录追加新内容，无需重建
  • 同步体验的关键在于目录的质量：媒体条目的时间范围要精确，内容要丰富
  • 部署时把目录文件打包进 App Bundle 或放在服务器上按需下载

还有什么值得关注

  • “Explore ShazamKit”（WWDC 2021）介绍了基础概念：签名、目录、媒体条目
  • “Create custom audio experiences with ShazamKit”（WWDC 2021）演示了同步体验的完整实现
  • ShazamKit 的自定义目录也适用于实时音频流匹配，不限于预录制内容
  • 如果你在做教育类或娱乐类 App 的第二屏体验，这套工具链值得深入研究
WWDC 2022