Audio mit WhisperKit auf macOS transkribieren

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 enthält ein vollständiges macOS-Kommandozeilenbeispiel zum Transkribieren englischer Audioaufnahmen. Dieselbe Bibliothek unterstützt iOS-Apps, doch diese Anleitung erstellt und startet ein ausführbares macOS-Programm.

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 bereits der erste Start ohne Netzwerkverbindung erfolgt: Stellen Sie diese Ressourcen bereit und validieren Sie sie, bevor Sie die App ohne Netzwerkzugriff nutzen.

WhisperKit auf iOS und macOS einrichten

Voraussetzungen

Ein Apple-Silicon-Mac für das native Beispiel in dieser Anleitung.
Apple Command Line Tools oder Xcode. Das festgelegte Paket setzt mindestens Swift 5.9 voraus; das ausführbare Programm wurde mit Apple Swift 6.4 auf macOS 26.6.2 getestet. Zum Erstellen und Ausführen einer iOS-App ist die vollständige Xcode-Installation erforderlich.
Zielplattformen ab iOS 16 oder macOS 13, wie im Manifest des festgelegten Pakets angegeben.
Eine lokale Audiodatei und ausreichend Speicherplatz für das gewählte Modell und die Tokenizer-Ressourcen.

Das Beispiel wurde auf macOS verifiziert. Damit sind weder ein Build für iOS-Simulatoren oder -Geräte noch die Unterstützung aller Zielplattformen oder die Transkriptionsgeschwindigkeit auf anderer Hardware belegt.

Installation

Erstellen Sie ein leeres Verzeichnis mit dieser Datei Package.swift. Das Paket ist auf eine bestimmte Version festgelegt, statt nur eine Mindestversion vorzugeben. So stimmt der API-Vertrag 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 der exakten Version über die Oberfläche für Paketabhängigkeiten in Xcode hinzu. Wählen Sie das Bibliotheksprodukt WhisperKit und setzen Sie die Zielplattform der App auf mindestens iOS 16. Der folgende Kommandozeileneinstiegspunkt ist für macOS gedacht. Rufen Sie die Bibliothek unter iOS aus einem eigenen Task oder ViewModel Ihrer App auf.

Audiodateien Schritt für Schritt transkribieren

Erstellen Sie Sources/TranscribeAudio/ und speichern Sie dort dieses vollständige Programm als TranscribeAudio.swift. Übergeben Sie einen Audiopfad und ein beschreibbares Cache-Verzeichnis für Modelle. 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)
        }
    }
}

Kopieren Sie eine gültige englische Aufnahme als recording.wav in das Paketverzeichnis oder ersetzen Sie dieses Argument durch den Pfad Ihrer Datei. Führen Sie diese Befehle im Verzeichnis aus, das Package.swift enthält. Der zweite Befehl wird nur ausgeführt, wenn der Build erfolgreich ist.

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

Das Programm schreibt erkannten Text auf die Standardausgabe. Vergleichen Sie ihn mit Wörtern, die nachweislich in der Aufnahme vorkommen, auch mit Sprache gegen Ende einer längeren Datei. Ein erfolgreicher Programmabschluss garantiert kein korrektes oder vollständiges Transkript: Eine WAV-Datei mit lesbarem Header und abgeschnittenen Nutzdaten kann trotzdem unvollständigen Text mit dem Status 0 liefern. Verwenden Sie eine intakte Aufnahme und prüfen Sie die erkannten Wörter. Bei fehlenden oder unlesbaren Dateien sowie Initialisierungs- oder Decodierungsfehlern gibt das Programm eine Diagnose auf der Standardfehlerausgabe aus und endet mit dem Status 1.

Der explizite Typ [TranscriptionResult] wählt die API, die ein Array zurückgibt. Fügen Sie alle Ergebnisse in der richtigen 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.

Der Audio-Lader nutzt AVFoundation. Beginnen Sie mit einer unterstützten lokalen Audiodatei wie 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 erneut und serialisieren Sie den Zugriff darauf, statt die Modelle für jede Aufnahme neu zu laden.

Ein bestimmtes Modell verwenden

Diese Anleitung verwendet tiny.en, ein ausschließlich englischsprachiges Modell. Andere Exporte wie base.en und das mehrsprachige base benötigen eigene Modell- und Tokenizer-Ressourcen. Ein angegebenes modelFolder wählt diese lokalen Ressourcen aus. Wenn Sie also nur den Namen model ändern und weiterhin einen Ordner für tiny.en nutzen, wechseln Sie damit nicht das Modell. Prüfen Sie die Ordnernamen im Modell-Repository, wenn Sie eine andere Konfiguration planen. Die native Verifizierung in dieser Anleitung deckt tiny.en mit englischer Decodierung ab.

Transkriptionsgenauigkeit und Leistung optimieren

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 im Speicherplatzbedarf und Laufzeitaufwand. Messen Sie Genauigkeit und Arbeitsspeicherbedarf anhand repräsentativer Aufnahmen auf den Zielgeräten, bevor Sie ein größeres Modell wählen.

Leistung

Die Downloadgröße entspricht nicht dem maximalen Arbeitsspeicherbedarf bei der Inferenz; berücksichtigen Sie Modell, Decoder-Zustand und 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 erneut.

Häufige Probleme beheben

Fehler beim Modell-Download

Problem: Modelle lassen sich nicht herunterladen oder initialisieren.

Lösung: Prüfen Sie Netzwerkzugriff, verfügbaren Speicherplatz und den gewählten Modellnamen. Verwenden Sie nach einem erfolgreichen ersten Durchlauf das heruntergeladene Modell über das dritte Argument des Programms 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: 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 das Herunterladen von Modellen. 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 bereitgestellte Installation mit deaktiviertem Netzwerkzugriff, bevor Sie Offline-Betrieb zusagen. Der Tokenizer-Lader der festgelegten Version dokumentiert diesen Unterschied. Ermitteln Sie für Ressourcen im iOS-App-Bundle deren tatsächliche Bundle-URLs, behalten Sie die Verzeichnisstruktur bei und prüfen Sie die Ressourcenzuordnung zu Ihrem App-Target.

Arbeitsspeichermangel

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

Lösung: Verwenden Sie ein kleineres Modell. Das Beispiel nutzt chunkingStrategy: .vad aus dem SDK und begrenzt concurrentWorkerCount auf 1. Das reduziert die parallele Decodierung; der Datei-Lader liest die Audiodaten weiterhin in den Arbeitsspeicher. Lange Aufnahmen können daher einen separaten Workflow zur Aufteilung der Audiodaten in begrenzte Abschnitte erfordern.

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 versuchen Sie es dann mit einem kleineren Modell. Erkennungsoptionen gehören in DecodingOptions, das an transcribe als decodeOptions übergeben wird. Die unterstützten Optionen finden Sie in den Decodierungsoptionen der festgelegten Version.

Streaming-Transkription

Das obige Programm transkribiert vorhandene Dateien. Mikrofon-Streaming benötigt einen Lebenszyklus für die Audioerfassung, eine Mikrofonberechtigung und eine app-spezifische Start/Stopp-Steuerung. Die Streaming-Implementierung im WhisperKit-Upstream-Projekt dient als Ausgangspunkt für diese separate Integration. Die Upstream-CLI gehört zum eigenen Quellpaket von WhisperKit. Wenn Sie dessen Bibliothek als Abhängigkeit hinzufügen, wird diese CLI nicht in diesem Beispielpaket installiert.

Sprachtranskription mit Transloadit

Für Aufnahmen, die Sie auf einem Server verarbeiten möchten, bietet Transloadit im Rahmen seines Dienstes für künstliche Intelligenz den Robot speech/transcribe zum Transkribieren von Sprache in Audio- oder Videodateien. Die Dokumentation führt unterstützte Anbieter, Ausgabeformate, Sprachen und anbieterspezifische Optionen auf, darunter die Sprechertrennung.