CoolFace
Apppublic

Tokimoto/pronunciation-checker-beginners

sourceHugging Faceupdated 5mo agoView on Hugging Face
0likes
App README

Pronunciation Checker for Beginners (Self-Introduction)

英語初級者向けの、完全ローカル実行を前提にした発音チェックMVPです。

このアプリは OpenAI API、Google API、Azure API、AWS API、ElevenLabs API などの課金APIを使いません。録音、音声認識、採点、フィードバック生成はローカルPC上で行います。

できること

  • —簡易パスワードロックで受講生向けに試験運用
  • —添付PDFから作成した22カテゴリ、合計540文の英文を表示
  • —カテゴリ番号と順番を維持
  • —1文または連続する2文をランダム表示
  • —ブラウザ上で録音
  • —Voskによるローカル音声認識
  • —正解英文と認識結果の単語差分比較
  • —100点満点の簡易スコア表示
  • —英語フィードバックと日本語フィードバック表示
  • —複数形 s、過去形 ed、語尾子音、be動詞や助動詞の抜けをルールベースで指摘

ファイル構成

text
簡単な発音チェックツール/
  app.py
  requirements.txt
  README.md
  start_windows.bat
  data/
    sentences.json
  scoring/
    scorer.py
    feedback.py
  utils/
    audio_recorder.py
    speech_recognition.py
    text_compare.py
  audio/
    recordings/
  models/

必要なもの

  • —Windows
  • —Python 3.10 以上
  • —マイク
  • —Voskの英語音声認識モデル

起動方法

  1. 1.このフォルダーを開きます。
  2. 2.start_windows.bat をダブルクリックします。
  3. 3.初回起動時は .venv が作成され、必要なPythonパッケージがインストールされます。
  4. 4.ブラウザでStreamlitアプリが開きます。
  5. 5.ログイン画面で今月のクラス用パスワードを入力します。

手動で起動する場合:

powershell
py -3 -m venv .venv
.\.venv\Scripts\activate
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
py -m streamlit run app.py

簡易パスワードロック

このアプリには、試験運用向けの簡易パスワードロックがあります。

ローカル確認用の仮パスワード:

text
SEKAEL-May2026

パスワードの読み込み優先順位:

  1. 1.環境変数 APP_PASSWORD
  2. 2.Streamlit secrets の APP_PASSWORD
  3. 3.ローカル開発用の仮パスワード SEKAEL-May2026

オンライン公開時は、APP_PASSWORD に毎月の共通パスワードを設定して変更する想定です。

PowerShellで一時的に設定する例:

powershell
$env:APP_PASSWORD="SEKAEL-June2026"
py -m streamlit run app.py

これは本格的な会員管理ではなく、月10人程度の試験運用を想定した共通パスワード方式です。ユーザー別アカウント、利用履歴、個別権限管理はありません。

ログアウトする場合は、ログイン後の左サイドバーにある Logout ボタンを押してください。同じブラウザセッションではログイン状態が保持されますが、Logout を押すと再びパスワード入力画面に戻ります。

音声認識モデルの扱い

このアプリは音声認識に無料OSSの Vosk を使います。初心者向けMVPでは、Vosk公式モデル一覧に掲載されている小型英語モデル vosk-model-small-en-us-0.15 を推奨します。

ローカル版では C:\vosk_models\vosk-model-small-en-us-0.15 に置く方法と、プロジェクト内の models/vosk-model-small-en-us-0.15/ に置く方法のどちらでも使えます。

Vosk公式モデル一覧: https://alphacephei.com/vosk/models

推奨配置例:

text
C:\vosk_models\
  vosk-model-small-en-us-0.15\
    am\
    conf\
    graph\
    ivector\

アプリの Vosk model folder のデフォルト値は C:\vosk_models\vosk-model-small-en-us-0.15 です。別の場所に置いた場合は、アプリ左側の入力欄にモデルフォルダーのパスを入力してください。

Hugging Face Spaces用の公開フォルダーでは、Voskモデルを models/vosk-model-small-en-us-0.15/ に含める想定です。アプリは以下の順番でモデルを探します。

  1. 1../models/vosk-model-small-en-us-0.15
  2. 2.C:/vosk_models/vosk-model-small-en-us-0.15
  3. 3.アプリ画面の Vosk model folder に入力されたパス

Hugging Face Spaces公開準備

オンライン版は Hugging Face Spaces の Docker + Streamlit template で動かす想定です。OpenAI API、Google API、Azure APIなどの課金APIは使わず、Voskをサーバー側で動かします。

今回の公開準備フォルダー:

text
hf_space_pronunciation_checker/

このフォルダーには、Hugging Face Spacesへアップロードするために必要なファイルだけを入れます。録音ファイルや仮想環境は含めません。

Hugging Face Spaces作成時の推奨設定:

  • —Space SDK: Docker
  • —Template: Docker + Streamlit
  • —Visibility: Private または試験運用方針に応じて Public
  • —Hardware: CPU Basic
  • —Secrets: APP_PASSWORD

Dockerfile は以下のコマンドでアプリを起動します。

bash
streamlit run app.py --server.port 7860 --server.address 0.0.0.0

Spacesの Secrets には、毎月のクラス用共通パスワードを APP_PASSWORD として設定してください。パスワードの読み込み優先順位は、環境変数 APP_PASSWORD、Streamlit secrets の APP_PASSWORD、ローカル仮パスワードの順です。

Voskモデルは公開フォルダー内の models/vosk-model-small-en-us-0.15/ に含めます。スマホから使う場合は、ブラウザでマイク許可が必要です。

無料枠では、起動時間、音声認識の処理速度、同時利用人数に制限が出る可能性があります。まずは月10人程度の受講生による試験運用を想定してください。

使い方

  1. 1.ログイン画面で今月のクラス用パスワードを入力します。
  2. 2.左側のメニューで Choose your practice topic. からカテゴリを選びます。
  3. 3.1 sentence または 2 sentences を選びます。
  4. 4.New Random Sentence で問題を選び直せます。
  5. 5.Choose sentence number と Use Selected Sentence で同じ文を繰り返し練習できます。
  6. 6.画面の録音欄で録音します。
  7. 7.Check Pronunciation を押します。
  8. 8.認識結果、スコア、英語と日本語のフィードバックを確認します。

うまく録音できない場合

  • —Windowsのマイク権限がオンになっているか確認してください。
  • —ブラウザのマイク許可をオンにしてください。
  • —外部マイクを使っている場合は、Windowsの入力デバイス設定を確認してください。
  • —録音が短すぎると認識が不安定になります。1文なら2〜6秒程度を目安にしてください。
  • —周囲の音が大きい場合は、できるだけ静かな場所で録音してください。

起動できない場合

  • —Python was not found. と表示された場合は、Python 3.10以上をインストールしてください。
  • —python --version で Python だけ表示されて失敗する場合は、Windowsの「アプリ実行エイリアス」でPythonのストア版エイリアスをオフにするか、python.org版をインストールしてください。
  • —インストール後、新しいコマンドプロンプトまたはPowerShellを開き直してから start_windows.bat を実行してください。

うまく認識できない場合

  • —C:\vosk_models\vosk-model-small-en-us-0.15 が正しく配置されているか確認してください。
  • —モデルフォルダーの中に am と conf フォルダーがあるか確認してください。
  • —pip install -r requirements.txt が完了しているか確認してください。
  • —小型モデルは軽量ですが、発音や環境音によって認識精度に限界があります。

採点について

このMVPは本格的な発音判定AIではありません。以下を組み合わせたルールベース採点です。

  • —正解英文と音声認識結果の単語差分
  • —欠落単語
  • —置き換わった可能性のある単語
  • —複数形 s の抜け
  • —過去形 ed の抜け
  • —語尾子音の抜け
  • —be動詞、do/does/did/will などの抜け
  • —録音時間による簡易リズム判定

今後の改善案

  • —faster-whisperやWhisper.cppへの切り替えオプション
  • —発音記号や音素単位の比較
  • —文ごとの学習履歴保存
  • —苦手単語リストの自動生成
  • —カテゴリ別の平均スコア表示
  • —Zip配布用のセットアップスクリプト追加
  • —Voskモデルを別途同梱したオフライン配布版の作成

データについて

data/sentences.json は pronunciation_checker_sentence_bank_v1_corrected.pdf から作成しました。

  • —22カテゴリ
  • —Grammarカテゴリ: 各20文
  • —Conversationカテゴリ: 各30文
  • —合計540文
  • —正規化した英文重複チェック: 重複なし