Transcribe audio en iOS y macOS: WhisperKit

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos ·

WhisperKit ejecuta modelos de reconocimiento de voz Whisper en dispositivos Apple. Esta guía fija el paquete de Swift en 0.9.0 y proporciona un ejemplo completo de línea de comandos para macOS que transcribe archivos de audio. La misma biblioteca admite apps de iOS; sus requisitos de compilación y permisos se describen por separado.

Introducción a WhisperKit y sus capacidades

WhisperKit utiliza Core ML para la inferencia local. Durante la configuración inicial, puede descargar modelos y archivos del tokenizador desde Hugging Face. El procesamiento local no significa que la primera ejecución se realice sin conexión: prepara y valida esos recursos antes de usar la app sin acceso a la red.

Configura WhisperKit en iOS y macOS

Para integrar WhisperKit en tus apps, necesitarás preparar el entorno adecuado:

Requisitos previos

Una Mac con Apple Silicon para el ejemplo nativo de esta guía.
Swift 5.9 o posterior. Apple Command Line Tools permite compilar este paquete de Swift para macOS; se requiere Xcode completo para compilar y ejecutar una app de iOS.
Versiones mínimas de implementación de iOS 16 o macOS 13, tal como se declara en el manifiesto del paquete de la versión fijada.
Un archivo de audio local y suficiente almacenamiento para el modelo seleccionado y los recursos del tokenizador.

El ejemplo está verificado en macOS. Esa verificación no confirma que compile para un simulador o un dispositivo iOS, que admita todas las versiones de implementación ni cuál será la velocidad de transcripción en otro hardware.

Instalación

Crea un directorio vacío que contenga este Package.swift. El paquete se fija en una versión concreta en lugar de establecer una versión mínima sin límite superior, de modo que el contrato de la API coincida 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 app de 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 configura la versión mínima de implementación de la app en iOS 16 o posterior. 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 app.

Guía paso a paso para transcribir archivos de audio

Guarda este programa completo como Sources/TranscribeAudio/TranscribeAudio.swift. Pasa la ruta de un archivo de audio y un directorio de caché de modelos con permisos de escritura. Un tercer argumento opcional permite especificar un directorio de 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)
        }
    }
}

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

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 primer resultado y puede descartar los fragmentos posteriores. Consulta la implementación de transcripción de la versión fijada.

El cargador de audio utiliza 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 app, conserva y reutiliza una instancia cargada de WhisperKit y serializa el acceso a ella en lugar de cargar los modelos para cada grabación.

Usa un modelo específico

El programa elige explícitamente tiny.en, un modelo exclusivo para inglés. Cambia model por base.en para usar otro modelo exclusivo para inglés, o utiliza una variante multilingüe como base. Si el idioma hablado es otro, establece también el valor correspondiente de DecodingOptions.language. Comprueba los nombres reales de las carpetas de Core ML en el repositorio de modelos antes de cambiar la configuración; el sufijo para inglés lleva un punto, como en tiny.en.

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

Para obtener resultados óptimos con WhisperKit, ten en cuenta las siguientes recomendaciones.

Consideraciones sobre la calidad del audio

Usa grabaciones de audio claras y de alta calidad siempre que sea posible.
Minimiza el ruido de fondo en los entornos de grabación.
Para las grabaciones de voz, coloca los micrófonos más cerca de quienes 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 a Core ML y variantes de compresión tienen distintos requisitos de almacenamiento y costos de ejecución. Mide la precisión y el consumo 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 la descarga no equivale al consumo máximo de memoria durante la inferencia; ten en cuenta 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.

Casos de uso prácticos y ejemplos

WhisperKit puede utilizarse eficazmente en:

Aplicaciones de notas de voz con transcripción automática.
Funciones de accesibilidad para personas con discapacidad auditiva.
Herramientas de transcripción de reuniones y entrevistas.
Transcripción de contenido de podcasts y videos.
Aplicaciones de aprendizaje de idiomas.

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 exitosa, 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 simplemente 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 puede seguir recurriendo a la red si faltan archivos locales o no son válidos. Prueba una instalación con todos los recursos preparados y el acceso a la red desactivado antes de prometer un funcionamiento sin conexión. El cargador del tokenizador de la versión fijada documenta esta distinción. Para los recursos incluidos en el paquete de la app en 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 app.

Presión de memoria

Problema: La app se cierra inesperadamente debido a limitaciones de memoria.

Solución: Usa un modelo más pequeño. El ejemplo utiliza 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 memoria. Por lo tanto, las grabaciones largas pueden requerir un flujo de trabajo independiente que divida el audio en fragmentos de tamaño limitado. Este ejemplo no incluye una función splitAudioIntoChunks integrada.

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. WhisperKitConfig no tiene una propiedad beamSize en esta versión fijada. Consulta las definiciones de configuración para conocer las opciones compatibles.

Transcripción en streaming

El programa anterior transcribe archivos existentes. El streaming desde el micrófono necesita un ciclo de vida de captura, autorización para usar el micrófono y gestión del inicio y la detención específica de la app. 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 forma parte del 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

Si necesitas una solución en la nube sin gestionar infraestructura, Transloadit ofrece un potente servicio de transcripción de voz como parte de nuestro servicio de inteligencia artificial. Nuestro 🤖 Robot speech/transcribe transcribe 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.

Este enfoque basado en la nube puede ser ideal para procesar archivos grandes o cuando el procesamiento en el dispositivo no es viable.