ShazamKitで、大規模なカスタムカタログを作成する

ShazamKitで、大規模なカスタムカタログを作成する

ShazamKitを使用して、カスタムカタログを作成したり、あらゆるApp内のオーディオソースとの完全一致をサポートする方法を解説します。新しいShazamKit CLIを活用して、オーディオシグネチャを簡単に生成したり、大規模なカタログを構築したりする方法をご覧ください。また、連続もののテレビ番組やPodcastなど、大量のオーディオコンテンツをすばやくAppに同期する方法をはじめ、ShazamKit APIやSHMediaItemsの最新情報も紹介します。これにより、時間範囲を使用するオーディオソースの重要な瞬間に、Appが正確に応答できるようになります。 ShazamKitの詳細については、WWDC21の「ShazamKitの紹介」と「ShazamKitによるカスタムオーディオエクスペリエンスの構築」をご覧ください。

リソース
- ShazamKit
- - HDビデオ
  - SDビデオ
関連ビデオ

WWDC23
- 優れたShazmKit体験の実現
WWDC21
- ShazamKitによるカスタムオーディオエクスペリエンスの構築
- ShazamKitの詳細
僕はNeil Foley ShazamKitチームのエンジニアです 2021年の ShazamKitの導入で Shazamの膨大な音楽カタログにオーディオをマッチングできるようになりましたまたカスタムカタログマッチングも導入されたことでデベロッパは自分のオーディオをマッチングさせて同期体験が提供できるようになりましたさらに大規模にカスタムカタログとの連携を合理化した重要なアップデートが行われました今回は ShazamKitの既存のコンセプトを使っていきます例えば署名やカタログメディアアイテムなどですこれらに馴染みのない方は画面の下に出ているＷＷDC21に行われた２つのトークの内容をご覧ください簡単に言うとShazamKitはオーディオをマッチングできる特別なフォーマットに変換してくれますこれをシグネチャと呼んでいますメタデータを含むメディアアイテムと組み合わせてできるのが参照シグネチャでカスタムカタログと言うファイルにまとめて保管することができます簡単な概要は以上で今度は大規模なカスタムカタログの構築と素晴らしいカタログにするためのコツについてお話します現在のカスタムカタログワークフローならマッチングしたいコンテンツが少ない場合はカスタムカタログでの作業はいたってシンプルですその手順は次の通りです ShazamKitが使用できる形式でオーディオを録音します
シグネチャジェネレータを使ってそれをシグネチャにします
それにメタデータを付加してカスタムカタログに保存しますそれだけで Shazam体験を提供できるのですですがオーディオプログラミングに詳しくない場合は大変に思えるかも知れませんねサンプルレートやバッファも経験豊富なデベロッパでも手こずることがあります膨大な量のコンテンツを取り扱う場合例えばテレビ番組の10シーズン分ならどうなるでしょう？
このワークフローはかなり困難になり得ます
コンテンツの量が膨大だと管理不能になりやすいものですこのワークフローを自分で改善するにはオーディオをシグネチャに変えるコードを書いてメディアアイテムを取り込んで関連付けるために更にコードを書きコンテンツを変える度にこれを繰り返すことになりますオーディオのマッチングにこれは膨大過ぎる作業ですそしてコンテンツを ShazamKitと同期したければ複雑な論理を使って何をいつどうするか計算することになりますこのワークフローを合理化するために ShazamKitが大幅に機能強化されましたまずは簡単なデモをお見せしますこれは2021年にAlexがお見せした FoodMathAppでオンスクリーンレッスンと算数クイズを同期しています最新の ShazamKit機能でアップデートしてありその同期状況を見るために FoodMathビデオを再生します
26秒までスキップ２個… ３個の青りんごがあります全部でりんごはいくつありますか？それでは皆さん… 始め！ではそこまで！答えは何でしょうか 56秒までスキップ今日は少しひねりますよお店に行った時最初は２個の赤いりんごで… それから２個の青りんごを買いました今度は全部でいくつのりんごをもっていたでしょうか？それでは皆さん… 始め！
ではそこまで！問題なさそうですリッチなコンテンツが動画と同期し僕が“始め！”と言った時ピッタリのタイミングでメニューが表示されましたまたコンテンツの関連性がなくなるとキューに合わせて消えていました一体どうやったのでしょう？コードを見てみましょうシンプルなループだけです以前使っていたデリゲートのコールバックの代わりに非同期のシーケンスを使っていますマッチしたかしていないかエラーかを表す列挙型を戻してくれます必要なのはマッチしたものだけなのでループをそれに限定します結果の表示を作成するためにメディアアイテムを必要なコンテンツだけに減らします
Appの中身はこれぐらいで作成した matchResultの生み出す SwiftUIビューだけです複雑な論理もタイミングコードもなく完璧に同期してくれますなぜそんなに上手く同期できるのかやはり疑問ですね FoodMathsの秘密はリッチなカスタムカタログにあります ShazamKitの補完として作成した簡易ツールでカタログを作りましたが皆さんも同様にApp内にリッチな体験を生み出せます Shazam CLIは macOS 13の一部として登場しコンテンツの同期を簡易化する方法を提供しますカスタムカタログの作成に関連する反復的タスクを自動化するサポートをしてくれます先ほどお見せしたカスタムカタログをアップデートしましょう別のデモをお見せします
このフォルダにあるのは FoodMathのビデオファイルとターミナルも入っています CLIを使って動画をシグネチャに変換しますシグネチャコマンド使用します
ビデオファイルを入力としてパスしシグネチャ出力を特定します
シグネチャができました
これをメディアアイテムと一緒に合わせてカスタムカタログを作ります CLIはメディアアイテムの記述にコンマで分けられたシンプルなファイルを受け付けるのでここにコピーします
コンテンツの同期に必要なものが全て記述されています
特定したタイトルはここに… そして方程式のために定義したカスタム JSONフィールドがここですヘッダーはメディアアイテムプロパティに関連していますマッピングの詳細についてはカスタムカタログ作成コマンドをヘルプのフラグ付きで実行してください
CSVヘッダーとメディアアイテムプロパティの関係性が記述されていますでは両者を合わせてカスタムカタログを作りましょう作成コマンドを実行して…
シグネチャファイルを csvファイルにパスするとカタログを出力します
これでカタログができました僕は最新の FoodMathエピソードに既にアクセスできるのでカタログファイルに追加しますファイルをコピーします
新エピソードのメディアアイテムがここにあります
アップデートコマンド実行して新しいメディアビデオそしてカタログを渡してアップデートします
カタログのアップデート完了ですカタログの作成方法を簡単に見てきましたが僕のようなタイプの人はこれをスクリプトしたいですね
FoodMathAppはかなり新しいエピソードがあってその全てをこのカタログに追加したいと思います全部のエピソードフォルダをループしそれを合わせてカスタムカタログに入れる単純なスクリプトを書きましたでは実行します
できましたこれで１つのカタログに全ての FoodMathエピソードとカタログ内の詳細を示すのにスクリプトの表示コマンドが使用されました全部入っているようです FoodMathプロジェクトは既に新しいカタログを参照していますでは作成および実行して算数を楽しみましょうか
30秒までスキップ全部でりんごはいくつありますか？それでは皆さん… 始め！ではそこまで答えを見てみましょうあの人イイですね素晴らしいエピソードだ新しいエピソードはどうでしょう見てみましょう
15秒までスキップ - 何年もかけて美味しいワカモレの秘密を探ってきた僕がお気に入りのワカモレのレシピを書いてみました４個のアボカドが必要です友人が遊びに来るのですが２人だけなら半分の量のワカモレで充分ですアボカドは何個必要でしょうか？それでは皆さん… 始め！
その通り　アボカド２個です一緒にワカモレを作りましょう
味見してみましょう
うーん　とても美味しい楽しんでいただけたでしょうかそれではまた次回
そうか新しいホストとはなるほどとにかくあっという間にリッチな同期体験が作成できました Shazam CLIはコマンドのリッチなセットをサポートします見ていきましょう
オーディオトラックを含むあらゆるメディアファイルからシグネチャが作成できますシグネチャとメディアアイテムを合わせてカスタムカタログが作成できますカタログのコンテンツを表示できますシグネチャとメディアアイテム両方の追加・削除・エクスポートが可能です次は CLIが FoodMathビデオからシグネチャ作成した方法です
SHSignatureGeneratorには新メソッドの signatureFromAssetがあり全プラットフォームで利用可能ですこのメソッドではメディアから手動でオーディオバッファを引き抜く必要はありませんオーディオトラックのついた AVAssetをパスしシグネチャに変えるだけですアセットに複数のトラックがある場合は全てがミックスされ必ずシグネチャ内に全てがキャプチャされますではメディアを表すシグネチャがあったとしてもどうやって正確にコンテンツを同期したのでしょうか？ Timed MediaItem APIを使いましたメディアアイテムに時間を付与することで開始時間および終了時間の特定が簡単になりましたメディアアイテムは複数の時間範囲を持つ場合がありシグネチャの一部分以外もターゲットにしていますコーラスをターゲットにしたメディアアイテムを考えてみましょう歌われている部分を表す時間範囲が追加できます
時間範囲の特定が役に立つのは開始時間と終了時間が通知された場合だけです ShazamKitは時間の範囲と同期したマッチコールバックを送り開始時に１つと終了時に１つですシグネチャは多くのメディアアイテムを包括できるのでこのコールバックは特定の時間の範囲内にあるメディアアイテムのみを含みますどのメディアアイテムがどの順番でコールバックに戻されるのか少しだけルールがありますのでそれを見てみましょう
時間範囲の外にあるものは戻されません時間範囲の中にあれば戻されますが最近のイベントが最初に戻されます
時間範囲のないものは常に最後に戻されますが順序はバラバラです時間範囲のないものはレファレンス全体に適用される全体的な情報を保存するのに適した場所だと言えます FoodMathの例ではエピソード名の保存場所にしました他のメディアアイテムが見えない場合に現れます
付け加えるとメディアアイテムの全てに時間範囲があってどれもスコープ外であれば ShazamKitが常に基本的マッチ情報を付けてメディアアイテムを戻しますこれによって常に重要なプロパティが手に入ります例えば predictedCurrentMatchオフセットや frequencySkewなどですコードでも簡単です timeRangesのメディアアイテムプロパティを特定することで時間付きのメディアアイテムが作成されます Swift範囲の配列です timeRangesプロパティを使ってリードバックすることも可能です Objective-Cのプログラマーには新しい SHRangeのクラスが完全互換品として使えます作成方法は分かったので… 素晴らしいカスタムカタログを作るコツをいくつか見てみましょうメディア１つに対して数多くの小さなシグネチャを作らないようにシグネチャはそれが表すメディアへの１対１のマッピングなので歌であろうとビデオであろうと１つのオーディオに対し最初から最後までで１つのシグネチャを作りましょう
シグネチャが長ければ ShazamKitは音のピークをマッチする機会が増えその結果正確性が向上するわけですまた複数の参照シグネチャが重複するクエリシグネチャのような問題も避けられます
新しいTimed MediaItem APIをを使えば個々のエリアで同期コンテンツをターゲットにできます１つのオーディオを複数のシグネチャに分割する必要はありませんお見せした例ではメディアは１つでしたがメディアアイテムは複数ありましたですが膨大な量のコンテンツに Shazamを利用したい場合どうすればいいのでしょうか？どう分ければいいのでしょうか？カスタムカタログのコンテンツを分割する場合はある種の犠牲が必要です各メディアアセットに個々のカタログを作るならオーディオのどの部分が演奏されているか知っていないと正しいカタログを取り込めませんそしてそれらを全部１つのカタログに入れたらダウンロードは大きくなりメモリ使用量も増えますがもっと多くのオーディオピースをマッチできるわけです作成したカタログファイルはしっかり絞りましょう例えば１曲ごとや全アルバムにカタログを１つ作ってもアーティストの全ディスコグラフィーにカタログ１つはやめましょう分別というのは実行時に何を取り込みたいかを決める事です custom catalog add APIでそれができます
自分のユースケースに合うか試してみてください同じ様に聞こえるオーディオアセットが複数ある場合例えば同じイントロで始まるテレビ番組など各エピソードにカスタム体験を提供したり別のトラックで標本化された曲を提供したければ周波数スキューを差別化要因に使うのもいいでしょうオーディオのスキューは録音の周波数を上げたり下げたりすることですこれはオーディオの聞こえ方に影響を与えますがわずかなスキューなら ShazamKitには分かっても平均的な人間の耳では無理ですですから録音をしてカスタムカタログを作ったら僅かに周波数を変えて再生すれば ShazamKitはマッチングを行い frequencySkewプロパティを通してスキュー量を報告しますコードでのやり方はこちらです
人間の耳では聞き分けられないけれど ShazamKitには聞き分けられる程度のスキュー量はきちんと決まっています
５％未満のスキューなら安全で複数のスキュー済みの録音も区別がつきます有効に活用したいなら frequencySkewRangesを使いましょう特定のスキュー範囲にあるメディアアイテムのみ戻されてきます
その範囲はパーセントで表されオリジナルからどれだけ変わっているかを意味しますゼロの値はスキューされていないことを意味し .01の値は１％のスキューを意味します frequencySkewRangeプロパティを使えばメディアアイテムのプロパティにアクセスできます
Appでのやり方を段階を踏んでお見せしましょうまずオリジナルのオーディオ録音から参照シグネチャを作成します MediaItemを３から４％の周波数スキューで制限しますカスタムカタログ内に入れます
３から４％スキューされたオーディオを再生するとメディアアイテムが戻されますスキュー無しやスキューの範囲を外れたものを再生しても戻されることはありません以上が周波数スキューです
ShazamKitの今年のアップデートをご覧になった今素晴らしい同期体験を生み出す準備ができましたねそのために重要な事をまとめますまずはメディアアセットごとに１つのシグネチャを作成しましょう ShazamKitなら精度も上がり作成パイプラインもシンプルですシグネチャの作成には SHSignatureGeneratorsの signatureFromAssetを使いましょう非常に幅広いメディアを受け入れるので低レベルのオーディオの詳細に時間を費やす必要はありません
新しいTimed MediaItem APIを使って対象を絞って同期コンテンツをターゲットしましょうそしてカスタムカタログの作成は Shazam CLIに合理化させましょう膨大な量のメディアと格闘する必要を無くすので皆さんは素晴らしい体験の作成に集中できます ShazamKitの最新アップデートをお楽しみいただけたでしょうか全てに役立てていただければ非常に光栄ですお話した全ての情報やドキュメントへのリンクは本セッションに添付されていますご清聴ありがとうございました

/*
See LICENSE folder for this sample’s licensing information.

Abstract:
The model that is responsible for matching against the catalog and update the SwiftUI Views.
*/

import ShazamKit
import AVFAudio

struct MatchResult {
    var title: String?
    var equation: Equation?
    var episode: Episode?
    var answerRange: ClosedRange<Int>?
    
    var hasContent: Bool {
        equation != nil || title != nil || answerRange != nil
    }
}

class Matcher: NSObject, ObservableObject, SHSessionDelegate {
    @Published var matchResult: MatchResult?
    
    private var session: SHSession!
    private let audioEngine = AVAudioEngine()
    private var matchingTask: Task<Void, Never>? = nil
    
    func match(catalog: SHCustomCatalog) throws {
        
        session = SHSession(catalog: catalog)
        session.delegate = self
        
        let audioFormat = AVAudioFormat(standardFormatWithSampleRate: audioEngine.inputNode.outputFormat(forBus: 0).sampleRate,
                                        channels: 1)
        audioEngine.inputNode.installTap(onBus: 0, bufferSize: 2048, format: audioFormat) { [weak session] buffer, audioTime in
            session?.matchStreamingBuffer(buffer, at: audioTime)
        }
        
        try AVAudioSession.sharedInstance().setCategory(.record)
        AVAudioSession.sharedInstance().requestRecordPermission { [weak self] success in
            guard success, let self = self else { return }
            
            Task.detached {
                try? self.audioEngine.start()
            }
        }
        
        Task { @MainActor in
            for await case .match(let match) in session.results {
                self.matchResult = match.matchResult
            }
        }
    }
}

extension SHMatch {

    var matchResult: MatchResult {
        mediaItems.reduce(into: MatchResult()) { result, mediaItem in
            result.title = result.title ?? mediaItem.title
            result.episode = result.episode ?? mediaItem.episode
            result.equation = result.equation ?? mediaItem.equation
            result.answerRange = result.answerRange ?? mediaItem.answerRange
        }
    }
}

13:51 - Timed Media Items

// Restrict this media item to only describe the first 5 seconds

 let mediaItem = SHMediaItem(properties: [
            .title: "Title",
            .timeRanges:[0.0..<5.0]
        ])

 let timeRanges: [Range<TimeInterval>] = mediaItem.timeRanges

16:02 - Combine Catalogs

let parentCatalog = SHCustomCatalog()

parentCatalog.add(from: URL(fileURLWithPath: "/path/to/Episode1.shazamcatalog"))
parentCatalog.add(from: URL(fileURLWithPath: "/path/to/Episode2.shazamcatalog"))
parentCatalog.add(from: URL(fileURLWithPath: "/path/to/Episode3.shazamcatalog"))

16:58 - Frequency Skew

func within(range: Range<Float>, for matchedMediaItem: SHMatchedMediaItem) -> Bool {
        
	range.contains(matchedMediaItem.frequencySkew)
}

17:21 - Frequency Skew Ranges

// Restrict this media item to only describe the first 5 seconds

 let mediaItem = SHMediaItem(properties: [
            .title: “Frequency Skewed Audio”,
            .frequencySkewRanges:[0.01..<0.02]
        ])

 let frequencySkewRanges: [Range<Float>] = mediaItem.frequencySkewRanges

リソース

関連ビデオ

WWDC23

WWDC21