🎤 ShazamKit

오디오 인식 및 음악 매칭 프레임워크

iOS 15+오디오 인식

✨ ShazamKit이란?

ShazamKit은 Shazam의 오디오 인식 기술을 앱에 통합할 수 있는 프레임워크입니다. 재생 중인 음악을 실시간으로 인식하고, 커스텀 오디오 카탈로그를 만들어 앱 내 오디오 콘텐츠를 매칭하며, Shazam의 방대한 음악 데이터베이스에 접근할 수 있습니다. 음악 앱, 게임, 교육 앱 등에서 오디오 기반 경험을 제공할 때 유용합니다.

💡 핵심 기능: 음악 인식 · 커스텀 카탈로그 · 실시간 매칭 · Shazam 라이브러리 접근 · 오디오 시그니처 생성 · 오프라인 인식

🎵 1. 기본 음악 인식

SHSession을 사용하여 Shazam 카탈로그에서 음악을 인식합니다.

ShazamManager.swift — 기본 음악 인식

import ShazamKit
import AVFoundation
import SwiftUI

@Observable
class ShazamManager: NSObject, SHSessionDelegate {
    private var session: SHSession?
    private var audioEngine: AVAudioEngine?

    var matchedMedia: SHMatchedMediaItem?
    var isListening = false
    var errorMessage: String?

    override init() {
        super.init()
        setupSession()
    }

    // 세션 설정
    private func setupSession() {
        // Shazam 카탈로그 세션 생성
        session = SHSession()
        session?.delegate = self
        print("✅ Shazam 세션 생성됨")
    }

    // 음악 인식 시작
    func startListening() {
        guard !isListening else { return }

        do {
            // 오디오 세션 설정
            let audioSession = AVAudioSession.sharedInstance()
            try audioSession.setCategory(.record)
            try audioSession.setActive(true)

            // 오디오 엔진 설정
            audioEngine = AVAudioEngine()
            guard let audioEngine = audioEngine else { return }

            let inputNode = audioEngine.inputNode
            let bus = 0
            let bufferSize: AVAudioFrameCount = 2048

            // 오디오 탭 설치
            inputNode.installTap(onBus: bus, bufferSize: bufferSize, format: inputNode.outputFormat(forBus: bus)) { [weak self] buffer, time in
                self?.session?.matchStreamingBuffer(buffer, at: time)
            }

            // 오디오 엔진 시작
            try audioEngine.start()

            isListening = true
            errorMessage = nil
            print("🎤 음악 인식 시작")
        } catch {
            errorMessage = "오디오 엔진 시작 실패: \(error.localizedDescription)"
            print("❌ \(errorMessage ?? "")")
        }
    }

    // 음악 인식 중지
    func stopListening() {
        guard isListening else { return }

        audioEngine?.stop()
        audioEngine?.inputNode.removeTap(onBus: 0)
        audioEngine = nil

        isListening = false
        print("⏹️ 음악 인식 중지")
    }

    // MARK: - SHSessionDelegate

    func session(_ session: SHSession, didFind match: SHMatch) {
        guard let mediaItem = match.mediaItems.first else { return }

        Task { @MainActor in
            matchedMedia = mediaItem
            print("🎵 발견: \(mediaItem.title ?? "Unknown") - \(mediaItem.artist ?? "Unknown")")
        }
    }

    func session(_ session: SHSession, didNotFindMatchFor signature: SHSignature, error: Error?) {
        Task { @MainActor in
            errorMessage = "음악을 찾을 수 없습니다"
            print("❌ 매칭 실패")
        }
    }
}

📦 2. 오디오 파일 인식

저장된 오디오 파일에서 음악을 인식합니다.

AudioFileRecognition.swift — 파일 인식

import ShazamKit
import AVFoundation

extension ShazamManager {
    // 오디오 파일에서 시그니처 생성
    func generateSignature(from url: URL) async throws -> SHSignature {
        // 오디오 파일 읽기
        let file = try AVAudioFile(forReading: url)

        // 시그니처 생성기
        let generator = SHSignatureGenerator()

        // 버퍼 읽기 및 시그니처 생성
        let bufferSize: AVAudioFrameCount = 2048
        guard let buffer = AVAudioPCMBuffer(
            pcmFormat: file.processingFormat,
            frameCapacity: bufferSize
        ) else {
            throw NSError(domain: "AudioError", code: -1)
        }

        while file.framePosition < file.length {
            try file.read(into: buffer)
            try generator.append(buffer, at: nil)
        }

        // 시그니처 반환
        return generator.signature()
    }

    // 파일에서 음악 인식
    func recognizeAudioFile(at url: URL) async {
        do {
            // 시그니처 생성
            let signature = try await generateSignature(from: url)

            // Shazam 카탈로그에서 매칭
            let match = try await session?.match(signature)

            if let mediaItem = match?.mediaItems.first {
                matchedMedia = mediaItem
                print("🎵 파일 인식 성공: \(mediaItem.title ?? "Unknown")")
            }
        } catch {
            errorMessage = "파일 인식 실패: \(error.localizedDescription)"
            print("❌ \(errorMessage ?? "")")
        }
    }
}

🗂️ 3. 커스텀 카탈로그

자체 오디오 카탈로그를 만들어 앱 내 콘텐츠를 인식합니다.

CustomCatalog.swift — 커스텀 카탈로그

import ShazamKit
import AVFoundation

@Observable
class CustomCatalogManager: NSObject, SHSessionDelegate {
    private var session: SHSession?
    private var catalog: SHCustomCatalog?

    var matchedReference: SHMediaItem?
    var isListening = false

    // 커스텀 카탈로그 생성
    func createCustomCatalog(from audioFiles: [URL]) async throws {
        var referenceSignatures: [SHSignature] = []

        // 각 오디오 파일에서 시그니처 생성
        for (index, fileURL) in audioFiles.enumerated() {
            let file = try AVAudioFile(forReading: fileURL)
            let generator = SHSignatureGenerator()

            let bufferSize: AVAudioFrameCount = 2048
            guard let buffer = AVAudioPCMBuffer(
                pcmFormat: file.processingFormat,
                frameCapacity: bufferSize
            ) else { continue }

            while file.framePosition < file.length {
                try file.read(into: buffer)
                try generator.append(buffer, at: nil)
            }

            let signature = generator.signature()
            referenceSignatures.append(signature)

            print("✅ 시그니처 생성: \(fileURL.lastPathComponent)")
        }

        // 미디어 아이템 생성
        var mediaItems: [SHMediaItem] = []
        for (index, signature) in referenceSignatures.enumerated() {
            let mediaItem = SHMediaItem(
                properties: [
                    .title: "Track \(index + 1)",
                    .artist: "Custom Artist"
                ]
            )
            mediaItems.append(mediaItem)
        }

        // 커스텀 카탈로그 생성
        catalog = SHCustomCatalog()

        for (signature, mediaItem) in zip(referenceSignatures, mediaItems) {
            try await catalog?.addReferenceSignature(signature, representing: [mediaItem])
        }

        // 커스텀 카탈로그 세션 생성
        if let catalog = catalog {
            session = SHSession(catalog: catalog)
            session?.delegate = self
            print("✅ 커스텀 카탈로그 생성 완료")
        }
    }

    // 커스텀 카탈로그에서 매칭
    func matchAgainstCustomCatalog(signature: SHSignature) async {
        guard let session = session else { return }

        do {
            let match = try await session.match(signature)
            if let mediaItem = match.mediaItems.first {
                matchedReference = mediaItem
                print("🎵 커스텀 카탈로그 매칭: \(mediaItem.title ?? "Unknown")")
            }
        } catch {
            print("❌ 커스텀 매칭 실패: \(error)")
        }
    }

    // MARK: - SHSessionDelegate

    func session(_ session: SHSession, didFind match: SHMatch) {
        guard let mediaItem = match.mediaItems.first else { return }

        Task { @MainActor in
            matchedReference = mediaItem
            print("🎵 커스텀 매칭 성공")
        }
    }

    func session(_ session: SHSession, didNotFindMatchFor signature: SHSignature, error: Error?) {
        print("❌ 커스텀 매칭 실패")
    }
}

💾 4. 시그니처 저장 및 로드

생성한 시그니처를 파일로 저장하고 나중에 다시 사용합니다.

SignatureStorage.swift — 시그니처 관리

import ShazamKit
import Foundation

class SignatureStorage {
    // 시그니처를 파일로 저장
    func saveSignature(_ signature: SHSignature, to fileName: String) throws {
        // 시그니처 데이터
        let data = signature.dataRepresentation

        // 저장 경로
        let url = FileManager.default
            .urls(for: .documentDirectory, in: .userDomainMask)[0]
            .appendingPathComponent("\(fileName).shazamsignature")

        // 파일 저장
        try data.write(to: url)
        print("✅ 시그니처 저장: \(url)")
    }

    // 파일에서 시그니처 로드
    func loadSignature(from fileName: String) throws -> SHSignature {
        // 파일 경로
        let url = FileManager.default
            .urls(for: .documentDirectory, in: .userDomainMask)[0]
            .appendingPathComponent("\(fileName).shazamsignature")

        // 데이터 읽기
        let data = try Data(contentsOf: url)

        // 시그니처 생성
        let signature = try SHSignature(dataRepresentation: data)
        print("✅ 시그니처 로드: \(url)")

        return signature
    }

    // 저장된 모든 시그니처 목록
    func listSavedSignatures() -> [String] {
        let documentsURL = FileManager.default
            .urls(for: .documentDirectory, in: .userDomainMask)[0]

        do {
            let files = try FileManager.default
                .contentsOfDirectory(at: documentsURL, includingPropertiesForKeys: nil)
                .filter { $0.pathExtension == "shazamsignature" }
                .map { $0.deletingPathExtension().lastPathComponent }

            return files
        } catch {
            print("❌ 파일 목록 가져오기 실패: \(error)")
            return []
        }
    }

    // 시그니처 삭제
    func deleteSignature(fileName: String) throws {
        let url = FileManager.default
            .urls(for: .documentDirectory, in: .userDomainMask)[0]
            .appendingPathComponent("\(fileName).shazamsignature")

        try FileManager.default.removeItem(at: url)
        print("✅ 시그니처 삭제: \(fileName)")
    }
}

📱 종합 예제

ShazamAppView.swift — Shazam 앱

import SwiftUI
import ShazamKit

struct ShazamAppView: View {
    @State private var shazamManager = ShazamManager()
    @State private var showingResult = false

    var body: some View {
        NavigationStack {
            VStack(spacing: 30) {
                // 버튼
                Button {
                    if shazamManager.isListening {
                        shazamManager.stopListening()
                    } else {
                        shazamManager.startListening()
                    }
                } label: {
                    ZStack {
                        Circle()
                            .fill(shazamManager.isListening ? Color.red : Color.blue)
                            .frame(width: 150, height: 150)

                        if shazamManager.isListening {
                            Image(systemName: "waveform.circle.fill")
                                .font(.system(size: 60))
                                .foregroundStyle(.white)
                        } else {
                            Image(systemName: "magnifyingglass")
                                .font(.system(size: 60))
                                .foregroundStyle(.white)
                        }
                    }
                }
                .buttonStyle(.plain)

                Text(shazamManager.isListening ? "인식 중..." : "탭하여 음악 인식")
                    .font(.headline)

                // 결과 표시
                if let media = shazamManager.matchedMedia {
                    VStack(spacing: 12) {
                        AsyncImage(url: media.artworkURL) { image in
                            image
                                .resizable()
                                .scaledToFit()
                        } placeholder: {
                            Rectangle()
                                .fill(Color.gray.opacity(0.3))
                        }
                        .frame(width: 200, height: 200)
                        .cornerRadius(12)

                        VStack(spacing: 4) {
                            Text(media.title ?? "Unknown")
                                .font(.title2)
                                .fontWeight(.bold)

                            Text(media.artist ?? "Unknown Artist")
                                .font(.subheadline)
                                .foregroundStyle(.secondary)
                        }

                        if let appleMusicURL = media.appleMusicURL {
                            Link("Apple Music에서 열기", destination: appleMusicURL)
                                .buttonStyle(.borderedProminent)
                        }

                        if let webURL = media.webURL {
                            Link("웹에서 보기", destination: webURL)
                                .buttonStyle(.bordered)
                        }
                    }
                    .padding()
                }

                // 에러 메시지
                if let error = shazamManager.errorMessage {
                    Text(error)
                        .foregroundStyle(.red)
                        .font(.caption)
                }

                Spacer()
            }
            .padding()
            .navigationTitle("음악 인식")
        }
    }
}

💡 HIG 가이드라인

권한: 마이크 권한 필요 (Info.plist에 NSMicrophoneUsageDescription 추가)
피드백: 인식 중임을 명확히 표시
결과 표시: 앨범 아트, 제목, 아티스트를 시각적으로 표시
링크 제공: Apple Music 또는 웹 링크 제공
오프라인: 인터넷 연결 필요 (Shazam 카탈로그 사용 시)

🎯 실전 활용

음악 앱: 재생 중인 음악 자동 인식
라디오 앱: 방송 중인 음악 식별
게임: 커스텀 카탈로그로 배경 음악 트래킹
교육 앱: 오디오 콘텐츠 진도 추적
이벤트 앱: 공연 중 곡 정보 제공

📚 더 알아보기

⚡️ 성능 팁: 커스텀 카탈로그는 앱 번들에 포함하거나 서버에서 다운로드하여 사용할 수 있습니다. 시그니처 생성은 CPU 집약적이므로 백그라운드 스레드에서 실행하세요. Shazam 카탈로그 사용 시 네트워크 연결이 필요하지만, 커스텀 카탈로그는 오프라인에서도 작동합니다.