ヘルプ

問題解決ガイド

Python環境の問題、インストールエラー、その他のよくある問題の解決方法を詳しく解説します

🔧 インストール・環境設定のトラブルシューティング

問題をクリックすると詳細が表示されます

Python環境の重要な注意事項

Python 3.12以外は問題が起こる可能性があります

Python 3.12以外のバージョンでは、faster-whisperのインストールに失敗する場合があります。
特にPython 3.14（2024年10月リリース）では、必要なソフトウェアがインストールできません。

推奨環境

Python 3.12 を使用してください（最も安定）

Python 3.11でも動作しますが、ビルド済みパッケージが豊富な3.12を推奨します

Python 3.12以外をお使いの方へ

Python 3.12以外のバージョン（特に3.14）がインストールされている場合は、アンインストールしてPython 3.12をインストールすることを強く推奨します。
複数バージョンの共存も可能ですが、環境の混乱を避けるため単一バージョンの使用を推奨します。

音声認識エンジン（Whisper）のインストール失敗

解決フロー

エラーメッセージ

「音声認識エンジン（Whisper）の自動インストールに失敗しました」

ステップ1: Python バージョンを確認

① コマンドプロンプト/ターミナルを開く

Windows
  1. Win + R を押す
  2. cmd と入力
  3. Enter を押す
Windowsファイル名を指定して実行ダイアログ
Mac
  1. ⌘ + Space を押す
  2. ターミナル と入力
  3. Enter を押す
Mac Spotlight検索

② 以下のコマンドを実行

python --version
結果による対処方法
❌ エラー表示: 'python' は、内部コマンド...として認識されていません

🔧 解決策A:

  1. Python 3.12をインストール
  2. インストール時「Add Python to PATH」に必ずチェック
  3. PCを再起動
  4. KoeMoji-Goを起動（自動インストール）
⚠️ Python 3.14.x: 非対応（インストール失敗）

🔧 解決策B:

  1. Python 3.14をアンインストール
  2. Python 3.12をインストール
  3. インストール時「Add Python to PATH」に必ずチェック
  4. PCを再起動
  5. KoeMoji-Goを起動（自動インストール）
✅ Python 3.12.x: 正常（なのにエラー）

🔧 解決策C:

  1. KoeMoji-Goを再起動
    （自動でfaster-whisperインストール再試行）
  2. それでもダメなら、コマンドプロンプト/ターミナルで以下を実行：
    pip install faster-whisper whisper-ctranslate2
❓ その他 / 不明: 複数バージョン表示など

💡 解決策:

  1. 全Pythonをアンインストール
  2. Python 3.12をインストール
  3. インストール時「Add Python to PATH」に必ずチェック
  4. PCを再起動
  5. KoeMoji-Goを起動（自動インストール）

🎉 解決完了！

音声認識エンジン（Whisper）が正常にインストールされました

「requests モジュール見つからず」エラー

エラーメッセージ
ModuleNotFoundError: No module named 'requests'
原因

faster-whisper ライブラリが内部で必要とするPythonの requests モジュールがインストールされていないためです。

解決方法

① コマンドプロンプト/ターミナルを開く

  • Windows: Win + R → cmd と入力 → Enter
  • Mac: ⌘ + Space → ターミナル と入力 → Enter

② 以下のコマンドを実行

pip install requests

③ KoeMoji-Goを再起動

インストール完了後、KoeMoji-Goを再起動すると正常に動作するようになります。

🎉 解決完了！

requests モジュールが正常にインストールされました

「ctranslate2.dll 見つからず」エラー (Windows)

エラーメッセージ
Could not find module '...ctranslate2\ctranslate2.dll' (or one of its dependencies).

症状: 文字起こしが完全に失敗し、FileNotFoundError が発生します。

原因

ctranslate2 ライブラリが依存する Microsoft Visual C++ 再頒布可能パッケージ がシステムにインストールされていないためです。

解決方法

① Microsoft公式サイトからダウンロード

ダウンロードリンク

https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist

ファイル名: VC_redist.x64.exe
対象: Latest supported Visual C++ Redistributable for Visual Studio 2015-2022 (x64)

② インストールを実行

  1. ダウンロードした VC_redist.x64.exe をダブルクリック
  2. インストールウィザードの指示に従う
  3. インストール完了後、PCを再起動

③ KoeMoji-Goを起動

再起動後、KoeMoji-Goを起動すると正常に動作するようになります。

🎉 解決完了！

ctranslate2 が正常に動作するようになりました

ファイル処理が始まらない

対応ファイル形式（合計9形式）
🎵 音声形式（6形式）
  • MP3 (.mp3)
  • WAV (.wav)
  • M4A (.m4a)
  • AAC (.aac)
  • FLAC (.flac)
  • OGG (.ogg)
🎬 動画形式（3形式）
  • MP4 (.mp4)
  • MOV (.mov)
  • AVI (.avi)

※ 音声トラックのみ抽出

大文字小文字を区別しません（.MP3も.mp3も処理可能）

その他の確認事項
  • ファイル名：日本語や特殊文字（#, %, &）を避ける
  • ファイル権限：読み取り権限があるか確認
  • ファイル破損：他のプレーヤーで再生できるか確認
  • 音声トラック：動画ファイルに音声が含まれているか確認
詳細なログを確認する方法

デバッグモードで起動すると、詳細なログが記録されます。

Windows

koemoji-go.exe --debug

Mac

./koemoji-go --debug

🎙️ 録音機能のトラブルシューティング

録音に関する問題の解決方法

Windows版

録音されない場合

  • 録音ボタンが正しく押されているか確認
  • ディスク容量が十分にあるか確認
  • コエモジを再起動してみる

システム音声が入らない場合

  • Windowsのスピーカー音量が適切に設定されているか
  • 録音中にPCで音声が再生されているか
  • システム音声の音量設定を +1 または +2 に上げてみる

マイク音声が入らない場合

  • Windowsのマイク音量が適切に設定されているか
  • マイクが正しく接続されているか
  • コエモジがマイクへのアクセス許可を持っているか

Mac版（v1.8.0～）

システム音声（相手の声）が録音されない

原因

画面収録権限が許可されていません

解決方法

  1. 「システム設定」を開く
  2. 「プライバシーとセキュリティ」をクリック
  3. 「画面収録」をクリック
  4. 「コエモジ」または「koemoji-go」を探す
  5. スイッチを「オン」にする
  6. コエモジを完全に終了して再起動

マイク音声（自分の声）が録音されない

原因

マイクアクセス権限が許可されていません

解決方法

  1. 「システム設定」を開く
  2. 「プライバシーとセキュリティ」をクリック
  3. 「マイク」をクリック
  4. 「コエモジ」または「koemoji-go」を探す
  5. スイッチを「オン」にする
  6. コエモジを完全に終了して再起動

macOS 12以前を使っている

問題

デュアル録音機能はmacOS 13 Ventura以降でのみ動作します

解決方法

macOS 13 Ventura以降にアップグレードしてください。古いバージョンのmacOSではデュアル録音機能は使用できません。

💡 その他のトラブルシューティング

軽微な問題や注意事項について

ログの文字化け・パーミッション警告

結論: 運用上無視して問題ありません

以下の警告やメッセージは表示上の問題であり、文字起こし機能やデータ出力には影響しません。

ログの文字化け

ログ表示において一部の日本語テキストが文字化けして見える場合がありますが、これは表示上の問題です。

✅ 文字起こしされた最終的なテキストデータは正しく出力されています

Hugging Faceキャッシュディレクトリの警告

Hugging Faceのモデルキャッシュディレクトリへの書き込み権限に関する警告がログに出る場合があります。

✅ モデルのロードや文字起こし機能には実害がありません

pkg_resources 廃止警告
UserWarning: pkg_resources is deprecated as an API

✅ Pythonライブラリの内部警告であり、動作に影響はありません

😌 安心してご利用ください

これらの警告は文字起こし機能に影響しません

"Python not found" エラーが出る

原因

Pythonがインストールされていないか、Python 3.13以降がインストールされています。

解決方法

① Pythonバージョンを確認

python --version

② Python 3.12をインストール

  • 推奨バージョン：Python 3.12
  • ⚠️ 注意：Python 3.13以降は動作しません
  • Windows: インストール時に「Add Python to PATH」をチェック
  • インストール後、ターミナル/コマンドプロンプトを再起動
重要な注意

Python 3.7以下の古いバージョンも動作しません。必ずPython 3.12をインストールしてください。

FasterWhisperのインストールに失敗する

FasterWhisperとは

KoeMoji-Goが音声認識に使用する高精度な文字起こしエンジンです。初回起動時に自動インストールされますが、環境によっては失敗する場合があります。

解決方法

方法1: 手動インストール（推奨）

pip install faster-whisper whisper-ctranslate2

方法2: pipが古い場合

pip install --upgrade pip
pip install faster-whisper whisper-ctranslate2

方法3: 権限エラーの場合

pip install --user faster-whisper whisper-ctranslate2
インストール確認

インストール後、以下のコマンドで確認できます：

pip show faster-whisper

文字起こし結果が不正確

文字起こし精度について

文字起こしの精度は、音声品質・モデル設定・言語設定によって大きく変わります。以下の方法で品質を向上できます。

品質向上の方法
1. AIモデルを変更する

より高精度なモデルに変更します（処理時間は長くなります）：

  • tiny / small → medium → large-v3
  • 推奨：large-v3（日本語最適化、最高精度）
2. 言語設定を確認

設定画面で言語が「日本語 (ja)」になっているか確認：

  • 設定画面 → 言語設定 → 「ja」を選択
3. 音声品質を改善
  • 発話がはっきりしている音声を使用
  • 背景音・雑音が少ない環境で録音
  • 音量が適切か確認（小さすぎ・大きすぎはNG）
  • 必要に応じてノイズ除去ソフトを使用
4. 方言・専門用語について
  • 標準的な発話の方が認識精度が高い
  • 専門用語は認識されにくい場合がある
  • 必要に応じて手動で修正
ヒント

処理速度と精度のバランスを取りたい場合はmediumモデルがおすすめです。最高精度が必要な場合はlarge-v3モデルを使用してください。

音声ファイルが処理されない

確認項目
対応ファイル形式か確認

対応形式（合計9形式）：

  • 音声：MP3, WAV, M4A, FLAC, OGG, AAC（6形式）
  • 動画：MP4, MOV, AVI（音声トラックのみ抽出）
  • 大文字小文字を区別しません（.MP3も.mp3も処理可能）

推奨形式

  • 汎用性重視 → MP3
  • 品質重視 → WAV, FLAC
  • iPhone録音 → M4A
ファイル名を確認
  • ❌ 避けるべき文字：日本語、特殊文字（#, %, &, など）
  • ✅ 推奨：半角英数字とハイフン、アンダースコア
  • 例：meeting_20250101.mp3
ファイルサイズを確認
  • 極端に大きなファイル（2GB以上）は処理できない場合があります
  • 大容量ファイルは分割して処理することをおすすめします
ファイルが破損していないか確認
  • AAC/M4Aファイルは再生可能でも文字起こしに失敗する場合があります
  • 対処法：WAV形式に変換してから再度処理
ファイルの権限を確認
  • ファイルに読み取り権限があるか確認
  • 別のアプリケーションで開かれていないか確認
それでも解決しない場合

koemoji.log ファイルを確認して、エラーメッセージを探してください。詳細は「ログファイルの確認方法」セクションを参照してください。

デバッグモードの起動方法

デバッグモードとは

詳細なログを出力して問題の原因を特定しやすくするモードです。トラブルシューティングや開発者への問題報告時に役立ちます。

Windows版

① コマンドプロンプトを開く

  • Win + R → cmd と入力 → Enter

② KoeMoji-Goのフォルダに移動

cd C:\path\to\koemoji-go

③ デバッグモードで起動

koemoji-go.exe --debug
Mac版

① ターミナルを開く

  • ⌘ + Space → ターミナル と入力 → Enter

② KoeMoji-Goのフォルダに移動

cd /path/to/koemoji-go

③ デバッグモードで起動

./koemoji-go --debug
ログの確認方法

デバッグモードで起動すると、コマンドプロンプト/ターミナルに詳細なログが表示されます。エラーが発生した場合は、このログをコピーして開発者に報告してください。

問題が解決しない場合

上記の方法で解決しない場合は、以下のサポート情報をご利用ください

README.md 使い方の詳細ドキュメント
GitHub Issues バグ報告・質問・機能リクエスト
メールでお問い合わせ