Audio auf iOS & macOS transkribieren: WhisperKit

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

WhisperKit führt Whisper-Spracherkennungsmodelle auf Apple-Geräten aus. Diese Anleitung legt das Swift-Paket auf 0.9.0 fest und bietet ein vollständiges macOS-Kommandozeilenbeispiel zum Transkribieren von Audiodateien. Dieselbe Bibliothek unterstützt iOS-Apps; deren Build- und Berechtigungsanforderungen werden separat beschrieben.

Einführung in WhisperKit und seine Funktionen

WhisperKit nutzt Core ML für lokale Inferenz. Bei der Ersteinrichtung können Modelle und Tokenizer-Dateien von Hugging Face heruntergeladen werden. Lokale Verarbeitung bedeutet nicht, dass der erste Start ohne Netzwerkverbindung erfolgt: Stellen Sie diese Ressourcen bereit und validieren Sie sie, bevor Sie die App ohne Netzwerkzugriff verwenden.

WhisperKit auf iOS und macOS einrichten

Um WhisperKit in Ihre Apps zu integrieren, müssen Sie die passende Umgebung einrichten:

Voraussetzungen

Ein Mac mit Apple Silicon für das native Beispiel in dieser Anleitung.
Swift 5.9 oder neuer. Mit den Apple Command Line Tools lässt sich dieses macOS-Swift-Paket erstellen; zum Erstellen und Ausführen einer iOS-App ist die vollständige Xcode-Installation erforderlich.
iOS 16 oder macOS 13 und neuer als Mindestzielversionen, wie im Manifest der festgelegten Paketversion angegeben.
Eine lokale Audiodatei und genügend Speicherplatz für das ausgewählte Modell und die Tokenizer-Ressourcen.

Das Beispiel wurde auf macOS überprüft. Diese Prüfung bestätigt weder einen Build für den iOS-Simulator oder ein iOS-Gerät noch die Unterstützung aller Zielversionen oder die Transkriptionsgeschwindigkeit auf anderer Hardware.

Installation

Erstellen Sie ein leeres Verzeichnis. Legen Sie darin anschließend die Datei Package.swift mit dem folgenden Inhalt an. Das Paket ist auf eine feste Version festgelegt, statt lediglich eine Mindestversion vorzugeben. So stimmt die API-Spezifikation mit den folgenden Beispielen überein.

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "AudioTranscription",
    platforms: [.iOS(.v16), .macOS(.v13)],
    dependencies: [
        .package(url: "https://github.com/argmaxinc/WhisperKit.git", exact: "0.9.0")
    ],
    targets: [
        .executableTarget(name: "TranscribeAudio", dependencies: [
            .product(name: "WhisperKit", package: "WhisperKit")
        ])
    ]
)

Fügen Sie für eine iOS-App dieses Repository mit genau dieser Version über die Oberfläche für Paketabhängigkeiten in Xcode hinzu. Wählen Sie das Bibliotheksprodukt WhisperKit aus und legen Sie als Mindestzielversion der App mindestens iOS 16 fest. Der folgende Kommandozeileneinstiegspunkt ist für macOS vorgesehen; rufen Sie die Bibliothek unter iOS aus einem eigenen Task oder ViewModel Ihrer App auf.

Schritt-für-Schritt-Anleitung zum Transkribieren von Audiodateien

Speichern Sie dieses vollständige Programm als Sources/TranscribeAudio/TranscribeAudio.swift. Übergeben Sie den Pfad zu einer Audiodatei und ein beschreibbares Verzeichnis für den Modellcache. Ein optionales drittes Argument gibt ein bereits heruntergeladenes Modellverzeichnis an. Dieses dateibasierte Beispiel fordert keine Mikrofonberechtigung an.

import Foundation
import WhisperKit

@main
struct TranscribeAudio {
    static func main() async {
        let arguments = CommandLine.arguments
        guard arguments.count == 3 || arguments.count == 4,
              FileManager.default.isReadableFile(atPath: arguments[1]) else {
            FileHandle.standardError.write(Data(
                "Usage: TranscribeAudio readable-audio-file cache-directory [model-directory]\n".utf8
            ))
            exit(1)
        }
        do {
            let cache = URL(fileURLWithPath: arguments[2], isDirectory: true)
            try FileManager.default.createDirectory(at: cache, withIntermediateDirectories: true)
            let localModel = arguments.count == 4 ? arguments[3] : nil
            let config = WhisperKitConfig(
                model: "tiny.en",
                downloadBase: cache,
                modelRepo: "argmaxinc/whisperkit-coreml",
                modelFolder: localModel,
                tokenizerFolder: cache,
                verbose: false,
                load: true,
                download: localModel == nil
            )
            let pipe = try await WhisperKit(config)
            let options = DecodingOptions(
                language: "en",
                skipSpecialTokens: true,
                concurrentWorkerCount: 1,
                chunkingStrategy: .vad
            )
            let results: [TranscriptionResult] = try await pipe.transcribe(
                audioPath: arguments[1], decodeOptions: options
            )
            print(results.map(\.text).joined(separator: "\n"))
        } catch {
            FileHandle.standardError.write(Data("Audio transcription failed.\n".utf8))
            exit(1)
        }
    }
}

swift build --product TranscribeAudio
swift run --skip-build TranscribeAudio "recording.wav" Models

Der explizite Typ [TranscriptionResult] wählt die API aus, die ein Array zurückgibt. Fügen Sie alle Ergebnisse in ihrer Reihenfolge zusammen: Die als veraltet markierte Überladung mit optionalem Ergebnis gibt nur das erste Ergebnis zurück und kann spätere Abschnitte verwerfen. Siehe die Transkriptionsimplementierung der festgelegten Version.

Zum Laden von Audio wird AVFoundation verwendet. Beginnen Sie mit einer unterstützten lokalen Audiodatei, etwa PCM WAV, MP3 oder AAC in M4A. Bei Videos extrahieren Sie zuerst die Tonspur. Behalten Sie in einer App eine geladene Instanz von WhisperKit bei, verwenden Sie sie wieder und serialisieren Sie den Zugriff darauf, statt die Modelle für jede Aufnahme neu zu laden.

Ein bestimmtes Modell verwenden

Das Programm wählt explizit tiny.en, ein ausschließlich englischsprachiges Modell. Ändern Sie model in base.en, um ein anderes rein englischsprachiges Modell zu verwenden, oder nutzen Sie eine mehrsprachige Variante wie base. Legen Sie für eine andere gesprochene Sprache auch den passenden Wert für DecodingOptions.language fest. Prüfen Sie die tatsächlichen Core-ML-Ordnernamen im Modell-Repository, bevor Sie die Konfiguration ändern; das Suffix für Englisch verwendet einen Punkt, wie in tiny.en.

Transkriptionsgenauigkeit und Leistung optimieren

So erzielen Sie mit WhisperKit optimale Ergebnisse:

Hinweise zur Audioqualität

Verwenden Sie nach Möglichkeit klare, hochwertige Audioaufnahmen.
Minimieren Sie Hintergrundgeräusche in der Aufnahmeumgebung.
Platzieren Sie Mikrofone bei Sprachaufnahmen näher an den sprechenden Personen.

Modellauswahl

Zu den Modellfamilien gehören tiny.en, base.en, small.en und medium.en für Englisch sowie mehrsprachige Varianten wie tiny, base und large-v3. Ihre Core-ML-Exporte und Komprimierungsvarianten unterscheiden sich beim Speicherbedarf und Laufzeitaufwand. Messen Sie Genauigkeit und Arbeitsspeicherbedarf anhand repräsentativer Aufnahmen und Zielgeräte, bevor Sie ein größeres Modell auswählen.

Hinweise zur Leistung

Die Downloadgröße entspricht nicht dem Spitzenbedarf an Arbeitsspeicher bei der Inferenz; berücksichtigen Sie das Modell, den Decoder-Zustand und die Audiodaten.
Die Verarbeitungszeit hängt vom Modell, der Audiolänge und der Zielhardware ab.
Beginnen Sie mit einem kleineren Modell und verwenden Sie die geladene Pipeline wieder.

Praktische Anwendungsfälle und Beispiele

WhisperKit lässt sich effektiv in folgenden Bereichen einsetzen:

Apps für Sprachnotizen mit automatischer Transkription.
Barrierefreiheitsfunktionen für Menschen mit Hörbeeinträchtigungen.
Tools zur Transkription von Besprechungen und Interviews.
Transkription von Podcasts und Videoinhalten.
Sprachlern-Apps.

Häufige Probleme beheben

Fehler beim Modelldownload

Problem: Modelle lassen sich nicht herunterladen oder initialisieren.

Lösung: Prüfen Sie den Netzwerkzugriff, den verfügbaren Speicherplatz und den ausgewählten Modellnamen. Verwenden Sie nach einem erfolgreichen ersten Durchlauf das heruntergeladene Modell über das dritte Programmargument erneut:

swift run --skip-build TranscribeAudio "recording.wav" Models \
  Models/models/argmaxinc/whisperkit-coreml/openai_whisper-tiny.en

modelFolder muss auf das Verzeichnis zeigen, das AudioEncoder.mlmodelc, TextDecoder.mlmodelc und MelSpectrogram.mlmodelc enthält, nicht nur auf ein übergeordnetes Verzeichnis namens Models. Behalten Sie auch den Tokenizer-Cache bei: Für dieses Modell und diese Paketversion liegt er unter Models/models/openai/whisper-tiny.en/ und enthält tokenizer.json und tokenizer_config.json.

In 0.9.0 steuert download: false den Modelldownload. Beim Laden des Tokenizers kann weiterhin auf das Netzwerk zurückgegriffen werden, wenn lokale Dateien fehlen oder ungültig sind. Testen Sie eine vollständig vorbereitete Installation mit deaktiviertem Netzwerkzugriff, bevor Sie Offline-Betrieb zusagen. Der Tokenizer-Lader der festgelegten Version dokumentiert diesen Unterschied. Ermitteln Sie für Ressourcen im App-Bundle unter iOS deren tatsächliche Bundle-URLs, behalten Sie die Verzeichnisstruktur bei und prüfen Sie, ob die Ressourcen Ihrem App-Target zugeordnet sind.

Hohe Arbeitsspeicherauslastung

Problem: Die App stürzt wegen begrenzten Arbeitsspeichers ab.

Lösung: Verwenden Sie ein kleineres Modell. Das Beispiel verwendet chunkingStrategy: .vad aus dem SDK und begrenzt concurrentWorkerCount auf 1. Dadurch werden weniger Daten gleichzeitig decodiert; beim Laden der Datei werden die Audiodaten weiterhin in den Arbeitsspeicher eingelesen. Lange Aufnahmen können daher einen separaten Workflow erfordern, der Audio in Abschnitte begrenzter Größe aufteilt. Dieses Beispiel enthält keine integrierte Funktion namens splitAudioIntoChunks.

Langsame Transkription

Problem: Die Transkription dauert für Ihren Anwendungsfall zu lange.

Lösung: Messen Sie das Laden des Modells getrennt von der Transkription und probieren Sie anschließend ein kleineres Modell aus. Erkennungsoptionen gehören in DecodingOptions und werden an transcribe als decodeOptions übergeben. WhisperKitConfig hat in dieser festgelegten Version keine Eigenschaft namens beamSize. Die unterstützten Optionen finden Sie in den Konfigurationsdefinitionen.

Streaming-Transkription

Das obige Programm transkribiert vorhandene Dateien. Mikrofon-Streaming benötigt eine Verwaltung des Aufnahmelebenszyklus, eine Mikrofonberechtigung und eine app-spezifische Start-Stopp-Steuerung. Die Streaming-Implementierung im WhisperKit-Projekt ist ein Ausgangspunkt für diese separate Integration. Die dortige CLI gehört zum eigenen Quellpaket von WhisperKit; durch das Hinzufügen der Bibliotheksabhängigkeit wird diese CLI nicht in diesem Beispielpaket installiert.

Transloadits Funktionen zur Sprachtranskription

Wenn Sie eine cloudbasierte Lösung benötigen, ohne selbst Infrastruktur zu verwalten, bietet Transloadit einen leistungsstarken Sprachtranskriptionsdienst als Teil unseres Dienstes für künstliche Intelligenz. Unser 🤖 speech/transcribe Robot transkribiert Sprache in Audio- oder Videodateien. Seine Dokumentation führt die unterstützten Anbieter, Ausgabeformate, Sprachen und anbieterspezifischen Optionen auf, einschließlich der Sprecherzuordnung.

Dieser cloudbasierte Ansatz kann ideal sein, um große Dateien zu verarbeiten oder wenn eine Verarbeitung direkt auf dem Gerät nicht möglich ist.