Transcribe audio con WhisperKit en macOS

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

WhisperKit ejecuta modelos de reconocimiento de voz Whisper en dispositivos Apple. Esta guía fija la versión del paquete Swift en 0.9.0 y ofrece un ejemplo completo de línea de comandos para macOS que transcribe audio en inglés. La misma biblioteca admite aplicaciones iOS, pero este tutorial compila y ejecuta un programa para macOS.

Introducción a WhisperKit y sus capacidades

WhisperKit usa Core ML para la inferencia local. Su configuración inicial puede descargar modelos y archivos de tokenizadores desde Hugging Face. El procesamiento local no significa que la primera ejecución sea sin conexión: prepara y valida esos archivos antes de usar la aplicación sin acceso a la red.

Configuración de WhisperKit en iOS y macOS

Requisitos previos

Un Mac con Apple Silicon para el ejemplo nativo de esta guía.
Apple Command Line Tools o Xcode. El paquete de versión fija declara Swift 5.9 como versión mínima; el ejecutable de esta guía se probó con Apple Swift 6.4 en macOS 26.6.2. Se requiere la versión completa de Xcode para compilar y ejecutar una aplicación iOS.
Versiones de destino iOS 16 o macOS 13 y posteriores, según lo declarado en el manifiesto del paquete de versión fija.
Un archivo de audio local y suficiente almacenamiento para el modelo seleccionado y los archivos del tokenizador.

El ejemplo está verificado en macOS. Esa verificación no demuestra que se pueda compilar para un simulador o dispositivo iOS, que admita todas las versiones de destino ni qué velocidad de transcripción ofrece en otro hardware.

Instalación

Crea un directorio vacío que contenga este Package.swift. El paquete usa una versión fija en lugar de una versión mínima sin límite superior, de modo que el contrato de la API coincide con los ejemplos siguientes.

// 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 una aplicación iOS, añade ese repositorio y la versión exacta mediante la interfaz de dependencias de paquetes de Xcode, selecciona el producto de biblioteca WhisperKit y establece al menos iOS 16 como versión de destino. El punto de entrada de línea de comandos que aparece a continuación es para macOS; en iOS, invoca la biblioteca desde una tarea o un modelo de vista de tu propia aplicación.

Guía paso a paso para transcribir archivos de audio

Crea Sources/TranscribeAudio/ y guarda allí este programa completo como TranscribeAudio.swift. Pasa una ruta de audio y un directorio de caché de modelos con permisos de escritura. Un tercer argumento opcional permite indicar el directorio de un modelo ya descargado. Este ejemplo basado en archivos no solicita permiso para usar el micrófono.

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

Copia una grabación válida en inglés al directorio del paquete como recording.wav, o sustituye ese argumento por la ruta de tu archivo. Ejecuta estos comandos desde el directorio que contiene Package.swift. El segundo comando se ejecuta solo si la compilación termina correctamente.

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

El programa imprime el texto reconocido en la salida estándar. Compáralo con palabras que sepas que están en la grabación, incluida la voz cerca del final de un archivo largo. Una salida correcta no garantiza una transcripción precisa ni completa: un WAV con una cabecera legible y datos truncados puede producir texto parcial con el estado 0. Usa una grabación intacta y comprueba las palabras reconocidas. Si faltan archivos o no se pueden leer, o si se producen errores de inicialización o decodificación, el programa imprime un diagnóstico en la salida de error estándar y termina con el estado 1.

El tipo explícito [TranscriptionResult] selecciona la API que devuelve un array. Une todos los resultados en orden: la sobrecarga obsoleta que devuelve un resultado opcional solo devuelve el primero y puede descartar los fragmentos posteriores. Consulta la implementación de transcripción de la versión fija.

El cargador de audio usa AVFoundation. Empieza con un archivo de audio local compatible, como PCM WAV, MP3 o AAC en M4A. Para video, extrae primero la pista de audio. En una aplicación, conserva y reutiliza una instancia cargada de WhisperKit y serializa el acceso a ella, en lugar de cargar los modelos para cada grabación.

Uso de un modelo específico

Este tutorial usa tiny.en, un modelo solo para inglés. Otras exportaciones, como base.en y la multilingüe base, requieren sus propios modelos y archivos de tokenizador. El valor proporcionado en modelFolder selecciona esos archivos locales, por lo que cambiar solo el nombre de model mientras se reutiliza una carpeta tiny.en no cambia de modelo. Comprueba los nombres de las carpetas en el repositorio de modelos cuando planifiques otra configuración. La verificación nativa de esta guía abarca tiny.en con decodificación en inglés.

Optimización de la precisión y el rendimiento de la transcripción

Consideraciones sobre la calidad del audio

Usa grabaciones de audio claras y de alta calidad cuando sea posible.
Minimiza el ruido de fondo en los entornos de grabación.
Para grabaciones de voz, coloca los micrófonos más cerca de las personas que hablan.

Selección del modelo

Las familias de modelos incluyen tiny.en, base.en, small.en y medium.en para inglés, con variantes multilingües como tiny, base y large-v3. Sus exportaciones Core ML y variantes de compresión tienen distintos costos de almacenamiento y ejecución. Mide la precisión y el uso de memoria con grabaciones representativas y en los dispositivos de destino antes de seleccionar un modelo más grande.

Consideraciones sobre el rendimiento

El tamaño de descarga no equivale al pico de memoria de inferencia; considera el modelo, el estado del decodificador y el audio.
El tiempo de procesamiento depende del modelo, la duración del audio y el hardware de destino.
Empieza con un modelo más pequeño y reutiliza el pipeline cargado.

Solución de problemas comunes

Fallos en la descarga de modelos

Problema: Los modelos no se descargan o no se inicializan.

Solución: Comprueba el acceso a la red, el almacenamiento disponible y el nombre del modelo seleccionado. Tras una primera ejecución correcta, reutiliza el modelo descargado con el tercer argumento del programa:

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

modelFolder debe apuntar al directorio que contiene AudioEncoder.mlmodelc, TextDecoder.mlmodelc y MelSpectrogram.mlmodelc, no solo a un directorio superior llamado Models. Conserva también la caché del tokenizador: para este modelo y esta versión del paquete, se encuentra en Models/models/openai/whisper-tiny.en/ e incluye tokenizer.json y tokenizer_config.json.

En 0.9.0, download: false controla la descarga de modelos. La carga del tokenizador aún puede recurrir a la red si los archivos locales faltan o no son válidos. Prueba una instalación con todos los archivos necesarios y el acceso a la red deshabilitado antes de prometer el funcionamiento sin conexión. El cargador de tokenizadores de la versión fija documenta esta distinción. Para los archivos incluidos en el paquete de una aplicación iOS, resuelve sus URL reales dentro del paquete, conserva la estructura de directorios y verifica que los recursos pertenezcan al destino de compilación de tu aplicación.

Presión de memoria

Problema: La aplicación se cierra inesperadamente debido a limitaciones de memoria.

Solución: Usa un modelo más pequeño. El ejemplo usa chunkingStrategy: .vad del SDK y limita concurrentWorkerCount a 1. Esto reduce el trabajo de decodificación concurrente; el cargador de archivos sigue leyendo el audio en la memoria. Por lo tanto, las grabaciones largas pueden requerir un flujo de trabajo independiente que divida el audio en fragmentos de tamaño limitado.

Transcripción lenta

Problema: La transcripción tarda demasiado para tu caso de uso.

Solución: Mide la carga del modelo por separado de la transcripción y luego prueba un modelo más pequeño. Las opciones de reconocimiento se definen en DecodingOptions, que se pasa a transcribe como decodeOptions. Consulta las opciones de decodificación de la versión fija para conocer las opciones compatibles.

Transcripción en streaming

El programa anterior transcribe archivos existentes. El streaming desde el micrófono requiere un ciclo de vida de captura, autorización para usar el micrófono y un manejo del inicio y la detención específico de la aplicación. La implementación de streaming del proyecto original de WhisperKit es un punto de partida para esa integración independiente. La CLI del proyecto original pertenece al propio paquete de código fuente de WhisperKit; añadir su biblioteca como dependencia no instala esa CLI en el paquete de este ejemplo.

Capacidades de transcripción de voz de Transloadit

Para las grabaciones que quieras procesar en un servidor, el servicio de inteligencia artificial de Transloadit incluye el Robot speech/transcribe para transcribir voz en archivos de audio o video. Su documentación enumera los proveedores, formatos de salida e idiomas compatibles, así como las opciones específicas de cada proveedor, incluida la diarización.