Transcrire l’audio avec WhisperKit sur macOS

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

WhisperKit exécute les modèles de reconnaissance vocale Whisper sur les appareils Apple. Ce guide fixe la version du package Swift à 0.9.0 et fournit un exemple complet en ligne de commande pour macOS permettant de transcrire de l’audio anglais. La même bibliothèque prend en charge les applications iOS, mais ce tutoriel compile et exécute un programme pour macOS.

Présentation de WhisperKit et de ses fonctionnalités

WhisperKit utilise Core ML pour l’inférence locale. Sa configuration initiale peut télécharger des modèles et des fichiers de tokeniseurs depuis Hugging Face. Le traitement local ne signifie pas que la première exécution se déroule sans connexion : préparez et validez ces ressources avant d’utiliser l’application sans accès au réseau.

Configurer WhisperKit sur iOS et macOS

Prérequis

• Un Mac Apple Silicon pour l’exemple natif de ce guide.
• Apple Command Line Tools ou Xcode. Le package à version fixe déclare Swift 5.9 comme version minimale ; l’exécutable présenté ici a été testé avec Apple Swift 6.4 sur macOS 26.6.2. La version complète de Xcode est nécessaire pour compiler et exécuter une application iOS.
• Des cibles de déploiement iOS 16 ou macOS 13, ou des versions ultérieures, comme le déclare le manifeste du package à version fixe⁠.
• Un fichier audio local et suffisamment d’espace de stockage pour les ressources du modèle et du tokeniseur sélectionnés.

L’exemple a été vérifié sur macOS. Cette vérification ne confirme ni la compilation pour un simulateur ou un appareil iOS, ni la prise en charge de toutes les cibles de déploiement, ni la vitesse de transcription sur d’autres matériels.

Installation

Créez un répertoire vide contenant ce fichier Package.swift. Le package utilise une version fixe plutôt qu’une version minimale sans limite supérieure, afin que le contrat de l’API corresponde aux exemples ci-dessous.

// 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")
        ])
    ]
)

Pour une application iOS, ajoutez ce dépôt et cette version exacte via l’interface des dépendances de packages de Xcode, sélectionnez le produit bibliothèque WhisperKit, puis définissez la cible de déploiement de l’application sur iOS 16 au minimum. Le point d’entrée en ligne de commande ci-dessous est destiné à macOS ; sur iOS, appelez la bibliothèque depuis une tâche ou un modèle de vue de votre application.

Transcrire des fichiers audio pas à pas

Créez Sources/TranscribeAudio/ et enregistrez-y ce programme complet sous le nom TranscribeAudio.swift. Passez un chemin de fichier audio et un répertoire de cache des modèles accessible en écriture. Un troisième argument facultatif indique un répertoire contenant un modèle déjà téléchargé. Cet exemple utilisant un fichier ne demande pas d’autorisation d’accès au microphone.

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)
        }
    }
}

Copiez un enregistrement valide en anglais dans le répertoire du package sous le nom recording.wav, ou remplacez cet argument par le chemin de votre fichier. Exécutez ces commandes depuis le répertoire contenant Package.swift. La seconde commande ne s’exécute que si la compilation réussit.

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

Le programme écrit le texte reconnu sur la sortie standard. Comparez-le aux mots dont vous savez qu’ils figurent dans l’enregistrement, y compris ceux prononcés vers la fin d’un fichier long. Un code de sortie indiquant une exécution réussie ne garantit pas une transcription exacte ou complète : un fichier WAV dont l’en-tête est lisible mais dont les données sont tronquées peut tout de même produire un texte partiel avec le code de sortie 0. Utilisez un enregistrement intact et vérifiez les mots reconnus. Si des fichiers sont absents ou illisibles, ou si des erreurs d’initialisation ou de décodage surviennent, le programme écrit un diagnostic sur la sortie d’erreur standard et se termine avec le code de sortie 1.

Le type explicite [TranscriptionResult] sélectionne l’API qui renvoie un tableau. Concaténez tous les résultats dans l’ordre : la surcharge obsolète qui renvoie un résultat facultatif ne renvoie que le premier résultat et peut omettre les segments suivants. Consultez l’implémentation de la transcription dans la version retenue⁠.

Le chargeur audio utilise AVFoundation. Commencez par un fichier audio local pris en charge, par exemple un fichier WAV PCM, MP3 ou AAC dans un conteneur M4A. Pour une vidéo, extrayez d’abord la piste audio EN (English). Dans une application, conservez et réutilisez une instance chargée de WhisperKit et sérialisez les accès à cette instance plutôt que de charger les modèles pour chaque enregistrement.

Utiliser un modèle spécifique

Ce tutoriel utilise tiny.en, un modèle réservé à l’anglais. D’autres exports, tels que base.en et le modèle multilingue base, nécessitent leurs propres ressources de modèle et de tokeniseur. Un modelFolder fourni sélectionne ces ressources locales ; modifier uniquement le nom model tout en réutilisant un dossier tiny.en ne change donc pas de modèle. Vérifiez les noms de dossiers dans le dépôt des modèles⁠ lorsque vous prévoyez une autre configuration. La vérification native de ce guide couvre tiny.en avec un décodage en anglais.

Optimiser la précision et les performances de la transcription

Points à prendre en compte pour la qualité audio

• Utilisez des enregistrements audio clairs et de haute qualité lorsque c’est possible.
• Réduisez le bruit de fond dans les environnements d’enregistrement.
• Pour les enregistrements vocaux, placez les microphones plus près des personnes qui parlent.

Sélection du modèle

Les familles de modèles comprennent tiny.en, base.en, small.en et medium.en pour l’anglais, avec des variantes multilingues telles que tiny, base et large-v3. Leurs exports Core ML et leurs variantes de compression ont des coûts différents en stockage et à l’exécution. Mesurez la précision et l’utilisation de la mémoire sur des enregistrements représentatifs et sur les appareils cibles avant de sélectionner un modèle plus volumineux.

Points à prendre en compte pour les performances

• La taille du téléchargement n’est pas égale au pic d’utilisation de la mémoire pendant l’inférence ; tenez compte du modèle, de l’état du décodeur et de l’audio.
• Le temps de traitement dépend du modèle, de la durée de l’audio et du matériel cible.
• Commencez par un modèle plus petit et réutilisez le pipeline chargé.

Résoudre les problèmes courants

Échecs de téléchargement des modèles

Problème : Les modèles ne se téléchargent pas ou ne s’initialisent pas.

Solution : Vérifiez l’accès au réseau, l’espace de stockage disponible et le nom du modèle sélectionné. Après une première exécution réussie, réutilisez le modèle téléchargé avec le troisième argument du programme :

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

modelFolder doit pointer vers le répertoire contenant AudioEncoder.mlmodelc, TextDecoder.mlmodelc et MelSpectrogram.mlmodelc, et pas simplement vers un répertoire parent nommé Models. Conservez également le cache du tokeniseur : pour ce modèle et cette version du package, il se trouve sous Models/models/openai/whisper-tiny.en/ et contient tokenizer.json et tokenizer_config.json.

Dans 0.9.0, download: false contrôle le téléchargement du modèle. Le chargement du tokeniseur peut encore recourir au réseau si les fichiers locaux sont absents ou invalides. Testez une installation dont toutes les ressources sont disponibles en désactivant l’accès au réseau avant de promettre un fonctionnement hors ligne. Le chargeur de tokeniseur de la version retenue⁠ documente cette distinction. Pour les ressources intégrées au bundle sur iOS, résolvez leurs URL réelles dans le bundle, conservez la structure des répertoires et vérifiez que les ressources appartiennent à la cible de votre application.

Pression mémoire

Problème : L’application plante en raison de limitations de mémoire.

Solution : Utilisez un modèle plus petit. L’exemple utilise chunkingStrategy: .vad du SDK et limite concurrentWorkerCount à 1. Cela réduit le travail de décodage simultané ; le chargeur de fichiers lit toujours l’audio en mémoire. Les enregistrements longs peuvent donc nécessiter un processus distinct et borné de découpage audio.

Transcription lente

Problème : La transcription prend trop de temps pour votre cas d’utilisation.

Solution : Mesurez le chargement du modèle séparément de la transcription, puis essayez un modèle plus petit. Les options de reconnaissance se définissent dans DecodingOptions, passé à transcribe comme decodeOptions. Consultez les options de décodage de la version retenue⁠ pour connaître les options prises en charge.

Transcription en continu

Le programme ci-dessus transcrit des fichiers existants. La transcription du flux d’un microphone nécessite un cycle de capture, une autorisation d’accès au microphone et une gestion du démarrage et de l’arrêt propre à l’application. L’implémentation de la transcription en continu⁠ du projet WhisperKit constitue un point de départ pour cette intégration distincte. L’interface en ligne de commande du projet appartient au package source de WhisperKit ; ajouter sa bibliothèque comme dépendance n’installe pas cette interface dans le package de cet exemple.

Fonctionnalités de transcription vocale de Transloadit

Pour les enregistrements que vous souhaitez traiter sur un serveur, le service d’intelligence artificielle de Transloadit comprend le Robot speech/transcribe pour transcrire la parole dans des fichiers audio ou vidéo. Sa documentation répertorie les fournisseurs, formats de sortie et langues pris en charge, ainsi que les options propres à chaque fournisseur, notamment la diarisation.