macOS で WhisperKit を使った音声の文字起こし
WhisperKit は Apple デバイス上で Whisper 音声認識モデルを実行します。このガイドでは Swift パッケージを 0.9.0 に固定し、英語音声を文字起こしする macOS コマンドラインプログラムの完全な例を示します。同じライブラリは iOS アプリにも対応していますが、ここでは macOS 実行ファイルをビルドして実行します。
WhisperKit の概要と機能
WhisperKit は Core ML を使ってローカルで推論を実行します。初期設定時には、モデルとトークナイザーファイルを Hugging Face からダウンロードする場合があります。ローカル処理だからといって、初回実行時からネットワーク接続が不要とは限りません。ネットワークに接続せずにアプリを使う前に、これらのアセットを準備し、検証してください。
iOS と macOS での WhisperKit のセットアップ
前提条件
- このガイドのネイティブ実行例に使用する Apple Silicon Mac
- Apple Command Line Tools または Xcode。固定したパッケージで宣言されている最小要件は Swift
5.9です。ここで示す実行ファイルは、macOS26.6.2上の Apple Swift6.4でテスト済みです。iOS アプリのビルドと実行には、完全版の Xcode が必要です。 - 固定したパッケージのマニフェストで宣言されている、iOS
16または macOS13以降のデプロイターゲット - ローカルの音声ファイルと、選択したモデルおよびトークナイザーのアセットを保存するための十分なストレージ
この例は macOS で検証済みです。ただし、この検証は iOS シミュレーターや実機向けのビルド、すべてのデプロイターゲットへの対応、ほかのハードウェアでの文字起こし速度を確認したものではありません。
インストール
空のディレクトリを作成し、次の Package.swift を配置してください。最小バージョンのみを指定するのではなく、パッケージのバージョンを固定しているため、API の仕様が以下の例と一致します。
// 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")
])
]
)
iOS アプリでは、Xcode のパッケージ依存関係のインターフェースから、このリポジトリと正確なバージョンを追加し、WhisperKit ライブラリ製品を選択して、アプリのデプロイターゲットを iOS 16 以上に設定してください。以下のコマンドラインエントリーポイントは macOS 用です。iOS では、アプリ独自のタスクまたはビューモデルからライブラリを呼び出してください。
音声ファイルを文字起こしする手順
Sources/TranscribeAudio/ を作成し、以下の完全なプログラムを TranscribeAudio.swift として保存してください。音声のパスと、書き込み可能なモデルキャッシュディレクトリを渡します。省略可能な第3引数には、ダウンロード済みのモデルディレクトリを指定できます。この例はファイルを処理するため、マイクの使用許可を要求しません。
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)
}
}
}
有効な英語の録音をパッケージディレクトリに recording.wav としてコピーするか、この引数を使用するファイルのパスに置き換えてください。Package.swift があるディレクトリで、次のコマンドを実行してください。2 番目のコマンドは、ビルドが成功した場合にのみ実行されます。
swift build --product TranscribeAudio &&
swift run --skip-build TranscribeAudio "recording.wav" Models
プログラムは認識したテキストを標準出力に出力します。長いファイルの終盤の音声も含め、録音に含まれているとわかっている言葉と比較してください。正常終了しても、文字起こしの正確性や完全性は保証されません。ヘッダーは読み取れてもペイロードが途中で切れている WAV では、ステータス 0 で部分的なテキストが生成される場合があります。破損のない録音を使用し、認識された言葉を確認してください。ファイルが存在しない場合や読み取れない場合、初期化またはデコードでエラーが発生した場合は、診断情報を標準エラー出力に出力し、ステータス 1 で終了します。
[TranscriptionResult] 型を明示すると、配列を返す API が選択されます。すべての結果を順番に結合してください。非推奨のオプショナルな結果を返すオーバーロードは、最初の結果しか返さず、後続のチャンクを破棄する場合があります。固定バージョンの文字起こし実装を参照してください。
音声ローダーは AVFoundation を使用します。まずは PCM WAV、MP3、M4A に格納された AAC など、対応するローカル音声ファイルを使用してください。動画の場合は、先に音声トラックを抽出してください。アプリでは、録音ごとにモデルを読み込むのではなく、読み込み済みの
WhisperKit インスタンスを保持して再利用し、アクセスを直列化してください。
特定のモデルの使用
この手順では、英語専用モデルの tiny.en を使用します。base.en や多言語対応の base など、ほかのエクスポートには、それぞれ専用のモデルとトークナイザーのアセットが必要です。指定した modelFolder によってローカルアセットが選択されるため、model の名前だけを変更し、tiny.en フォルダーを再利用しても、モデルは切り替わりません。別の構成を検討する際は、モデルリポジトリでフォルダー名を確認してください。このガイドのネイティブ環境での検証対象は、英語でデコードする tiny.en です。
文字起こしの精度とパフォーマンスの最適化
音声品質に関する考慮事項
- 可能な限り、明瞭で高品質な録音を使用
- 録音環境の背景ノイズを最小限に抑制
- 音声録音では、マイクを話者の近くに配置
モデルの選択
モデルファミリーには、英語用の tiny.en、base.en、small.en、medium.en と、tiny、base、large-v3 などの多言語版があります。Core ML エクスポートや圧縮方式のバリエーションによって、ストレージ使用量と実行時のコストが異なります。大きいモデルを選ぶ前に、代表的な録音と対象デバイスで精度とメモリ使用量を測定してください。
パフォーマンスに関する考慮事項
- ダウンロードサイズと推論時のピークメモリ使用量は別物。モデル、デコーダーの状態、音声を考慮
- 処理時間はモデル、音声の長さ、対象ハードウェアに依存
- 小さいモデルから始め、読み込み済みのパイプラインを再利用
よくある問題のトラブルシューティング
モデルのダウンロード失敗
問題:モデルのダウンロードまたは初期化に失敗します。
解決方法:ネットワーク接続、ストレージの空き容量、選択したモデル名を確認してください。初回実行が成功したら、プログラムの第3引数でダウンロード済みモデルを再利用します。
swift run --skip-build TranscribeAudio "recording.wav" Models \
Models/models/argmaxinc/whisperkit-coreml/openai_whisper-tiny.en
modelFolder は、AudioEncoder.mlmodelc、TextDecoder.mlmodelc、MelSpectrogram.mlmodelc があるディレクトリを指す必要があります。Models という名前の親ディレクトリだけを指定してはいけません。トークナイザーのキャッシュも保持してください。このモデルとパッケージバージョンでは、Models/models/openai/whisper-tiny.en/ の下にあり、tokenizer.json と tokenizer_config.json が含まれます。
0.9.0 では、download: false がモデルのダウンロードを制御します。ローカルファイルが存在しない、または無効な場合、トークナイザーの読み込みではネットワークへのフォールバックが発生する可能性があります。オフライン動作を保証する前に、必要なファイルをすべて配置したインストール環境で、ネットワーク接続を無効にしてテストしてください。固定バージョンのトークナイザーローダーに、この違いが記載されています。iOS にアセットを同梱する場合は、実際のバンドル URL を解決し、ディレクトリ構造を維持して、アプリターゲットにリソースが含まれていることを確認してください。
メモリ不足
問題:メモリの制約によりアプリがクラッシュします。
解決方法:小さいモデルを使用してください。この例では SDK の chunkingStrategy: .vad を使用し、concurrentWorkerCount を 1 に制限しています。これにより並行して行うデコード処理は減りますが、ファイルローダーは依然として音声をメモリに読み込みます。そのため、長い録音には、メモリ使用量を制限する別の音声分割ワークフローが必要になる場合があります。
文字起こしの遅延
問題:用途に対して文字起こしに時間がかかりすぎます。
解決方法:モデルの読み込みと文字起こしを別々に測定してから、小さいモデルを試してください。認識オプションは DecodingOptions に設定し、transcribe に decodeOptions として渡します。対応するオプションは、固定バージョンのデコードオプションを参照してください。
ストリーミング文字起こし
上記のプログラムは既存のファイルを文字起こしします。マイクからのストリーミングには、キャプチャのライフサイクル管理、マイクの使用許可、アプリ固有の開始・停止処理が必要です。WhisperKit の開発元によるストリーミング実装は、この別途の統合を進める出発点になります。開発元の CLI は WhisperKit 自体のソースパッケージに属しています。ライブラリの依存関係を追加しても、このサンプルパッケージにその CLI はインストールされません。
Transloadit の音声文字起こし機能
サーバーで処理したい録音には、Transloadit の人工知能サービスに含まれる speech/transcribe Robotで、音声または動画ファイル内の音声を文字起こしできます。ドキュメントには、対応するプロバイダー、出力形式、言語に加え、話者分離などのプロバイダー固有のオプションが記載されています。
