Transcrever áudio com WhisperKit no macOS

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

O WhisperKit executa modelos de reconhecimento de fala Whisper em dispositivos Apple. Este guia fixa o pacote Swift na versão 0.9.0 e fornece um exemplo completo de linha de comando para macOS que transcreve áudio em inglês. A mesma biblioteca oferece suporte a aplicativos iOS, mas este tutorial compila e executa um programa executável para macOS.

Introdução ao WhisperKit e seus recursos

O WhisperKit usa Core ML para inferência local. Sua configuração inicial pode baixar modelos e arquivos de tokenizador do Hugging Face. O processamento local não significa que a primeira execução ocorra sem conexão: prepare e valide esses recursos antes de usar o aplicativo sem acesso à rede.

Configurar o WhisperKit no iOS e no macOS

Pré-requisitos

Um Mac com Apple Silicon para o exemplo nativo deste guia.
Apple Command Line Tools ou Xcode. O pacote fixado declara Swift 5.9 como versão mínima; o executável deste guia foi testado com Apple Swift 6.4 no macOS 26.6.2. A instalação completa do Xcode é necessária para compilar e executar um aplicativo iOS.
Versões mínimas de implantação de iOS 16 ou macOS 13 e posteriores, conforme declarado no manifesto do pacote fixado.
Um arquivo de áudio local e espaço de armazenamento suficiente para os recursos do modelo e do tokenizador selecionados.

O exemplo foi verificado no macOS. Essa verificação não comprova a compilação para um simulador ou um dispositivo iOS, o suporte a todas as versões de implantação nem a velocidade de transcrição em outros hardwares.

Instalação

Crie um diretório vazio contendo este Package.swift. O pacote usa uma versão fixa em vez de uma versão mínima sem limite superior, para que o contrato da API corresponda aos exemplos abaixo.

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

Para um aplicativo iOS, adicione esse repositório e essa versão exata pela interface de dependências de pacotes do Xcode, selecione o produto de biblioteca WhisperKit e defina a versão mínima de implantação do aplicativo como iOS 16 ou posterior. O ponto de entrada de linha de comando abaixo é para macOS; no iOS, invoque a biblioteca a partir de uma tarefa ou de um modelo de visualização do próprio aplicativo.

Guia passo a passo para transcrever arquivos de áudio

Crie Sources/TranscribeAudio/ e salve este programa completo nesse diretório como TranscribeAudio.swift. Passe um caminho de áudio e um diretório de cache de modelos com permissão de gravação. Um terceiro argumento opcional fornece um diretório de modelo já baixado. Este exemplo baseado em arquivos não solicita permissão para usar o microfone.

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

Copie uma gravação válida em inglês para o diretório do pacote como recording.wav, ou substitua esse argumento pelo caminho do seu arquivo. Execute estes comandos no diretório que contém Package.swift. O segundo comando só é executado se a compilação for bem-sucedida.

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

O programa imprime o texto reconhecido na saída padrão. Compare esse texto com palavras que você sabe que estão na gravação, incluindo a fala perto do final de um arquivo mais longo. O encerramento bem-sucedido do processo não garante uma transcrição precisa ou completa: um WAV com cabeçalho legível e dados truncados ainda pode produzir texto parcial com o status 0. Use uma gravação íntegra e confira as palavras reconhecidas. Arquivos ausentes ou ilegíveis e erros de inicialização ou decodificação imprimem uma mensagem de diagnóstico na saída de erro padrão e encerram o processo com o status 1.

O tipo explícito [TranscriptionResult] seleciona a API que retorna um array. Concatene todos os resultados na ordem: a sobrecarga obsoleta que retorna um resultado opcional retorna apenas o primeiro resultado e pode descartar os trechos seguintes. Consulte a implementação de transcrição da versão fixada.

O carregador de áudio usa AVFoundation. Comece com um arquivo de áudio local compatível, como PCM WAV, MP3 ou AAC em M4A. Para vídeo, extraia primeiro a faixa de áudio (English). Em um aplicativo, mantenha e reutilize uma instância carregada de WhisperKit e serialize o acesso a ela, em vez de carregar os modelos para cada gravação.

Usar um modelo específico

Este tutorial usa tiny.en, um modelo exclusivo para inglês. Outras exportações, como base.en e a multilíngue base, exigem seus próprios recursos de modelo e tokenizador. O modelFolder fornecido seleciona esses recursos locais, portanto, alterar apenas o nome de model enquanto reutiliza uma pasta tiny.en não troca o modelo. Confira os nomes das pastas no repositório de modelos ao planejar outra configuração. A verificação nativa deste guia abrange tiny.en com decodificação em inglês.

Otimizar a precisão e o desempenho da transcrição

Considerações sobre a qualidade do áudio

Use gravações de áudio claras e de alta qualidade quando possível.
Minimize o ruído de fundo nos ambientes de gravação.
Para gravações de voz, posicione os microfones mais perto de quem fala.

Seleção do modelo

As famílias de modelos incluem tiny.en, base.en, small.en e medium.en para inglês, com variantes multilíngues como tiny, base e large-v3. Suas exportações para Core ML e variantes de compressão têm diferentes custos de armazenamento e execução. Meça a precisão e o uso de memória em gravações representativas e nos dispositivos de destino antes de selecionar um modelo maior.

Considerações sobre o desempenho

O tamanho do download não equivale ao pico de uso de memória durante a inferência; considere o modelo, o estado do decodificador e o áudio.
O tempo de processamento depende do modelo, da duração do áudio e do hardware de destino.
Comece com um modelo menor e reutilize o fluxo de processamento carregado.

Solucionar problemas comuns

Falhas no download do modelo

Problema: os modelos não são baixados ou inicializados.

Solução: verifique o acesso à rede, o armazenamento disponível e o nome do modelo selecionado. Após uma primeira execução bem-sucedida, reutilize o modelo baixado com o terceiro argumento do programa:

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

modelFolder deve apontar para o diretório que contém AudioEncoder.mlmodelc, TextDecoder.mlmodelc e MelSpectrogram.mlmodelc, não apenas para um diretório pai chamado Models. Mantenha também o cache do tokenizador: para este modelo e esta versão do pacote, ele fica em Models/models/openai/whisper-tiny.en/ e inclui tokenizer.json e tokenizer_config.json.

Em 0.9.0, download: false controla o download do modelo. O carregamento do tokenizador ainda pode recorrer à rede se os arquivos locais estiverem ausentes ou forem inválidos. Teste uma instalação com todos os recursos necessários e com o acesso à rede desativado antes de prometer funcionamento offline. O carregador de tokenizador da versão fixada documenta essa distinção. Para recursos incluídos no aplicativo iOS, resolva suas URLs reais no bundle, preserve a estrutura de diretórios e verifique se os recursos pertencem ao target do seu aplicativo.

Pressão de memória

Problema: o aplicativo falha devido a limitações de memória.

Solução: use um modelo menor. O exemplo usa chunkingStrategy: .vad do SDK e limita concurrentWorkerCount a 1. Isso reduz o trabalho de decodificação simultâneo; o carregador de arquivos ainda lê o áudio para a memória. Gravações longas podem, portanto, exigir um fluxo separado de divisão do áudio em trechos de tamanho limitado.

Transcrição lenta

Problema: a transcrição demora demais para o seu caso de uso.

Solução: meça o carregamento do modelo separadamente da transcrição e depois experimente um modelo menor. As opções de reconhecimento ficam em DecodingOptions, que é passado para transcribe como decodeOptions. Consulte as opções de decodificação da versão fixada para conhecer as opções disponíveis.

Transcrição de fluxo de áudio

O programa acima transcreve arquivos existentes. A transmissão de áudio do microfone exige um ciclo de vida de captura, autorização para usar o microfone e tratamento específico do aplicativo para iniciar e parar a captura. A implementação de transmissão de áudio do projeto WhisperKit é um ponto de partida para essa integração separada. A CLI do projeto pertence ao próprio pacote de código-fonte do WhisperKit; adicionar a dependência da biblioteca não instala essa CLI no pacote deste exemplo.

Recursos de transcrição de fala da Transloadit

Para gravações que você quer processar em um servidor, o serviço de inteligência artificial da Transloadit inclui o Robot speech/transcribe para transcrever fala em arquivos de áudio ou vídeo. A documentação desse Robot lista os provedores, formatos de saída e idiomas compatíveis, além de opções específicas de cada provedor, incluindo diarização.