Update README.md

README.md

@@ -1,10 +1,163 @@
----
-title: JusTalk
-emoji: ⚡
-colorFrom: gray
-colorTo: blue
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: JusTalk
+emoji: ⚡
+colorFrom: gray
+colorTo: blue
+sdk: docker
+pinned: false
+---
+
+
+---
+
+## グローバル変数と主要な設定
+
+- **`users`**  
+  登録されたユーザー名のリスト。  
+- **`transcription_text`**  
+  音声から作成された書き起こしのファイルパスまたは内容。  
+- **`total_audio`**  
+  音声セグメントをマージした結果の音声ファイルパス。  
+- **`harassment_keywords`**  
+  ハラスメントとして検出するキーワードのリスト（例："バカ", "死ね" など）。
+
+また、外部ライブラリとして `pydub`、および独自の `AudioProcessor`、`TranscriptionMaker`、`TextAnalyzer` を用いて音声処理や解析を行います。
+
+---
+
+## 各エンドポイントの概要
+
+### 1. トップページ／ユーザー登録画面
+
+- **URL:** `/index`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - テンプレート `index.html` を表示。  
+  - 現在の `users` リストをテンプレートに渡す。
+
+- **URL:** `/` または `/userregister`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - ユーザー登録用の画面を表示するため、`userRegister.html` テンプレートを返す。
+
+---
+
+### 2. フィードバックおよび会話詳細画面
+
+- **URL:** `/feedback`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - フィードバック画面（テンプレート：`feedback.html`）を表示。
+
+- **URL:** `/talk_detail`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - 会話の詳細を表示する画面（テンプレート：`talkDetail.html`）を返す。
+
+---
+
+### 3. ユーザーとファイルのリセット関連
+
+- **URL:** `/reset_html`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - リセット画面（テンプレート：`reset.html`）を表示。
+
+- **URL:** `/reset_member`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - 指定されたメンバー（ユーザー）とその関連の参照音声ファイルを削除する。  
+  - リクエストボディ内で `"names"` キーが必須。  
+  - `/tmp/data/base_audio` 内の各ユーザーの音声ファイル（`{name}.wav`）を削除。  
+  - 削除後、`users` リストから対象ユーザーを除外する。  
+  - 加えて、累積音声ファイル（`total_audio`）や、書き起こしファイル（`transcription_text`）も削除する処理を実施。
+
+- **URL:** `/reset`  
+  **メソッド:** GET  
+  **機能:**  
+  - `users` リストを空にリセットし、成功レスポンスを返す。
+
+---
+
+### 4. 状態確認エンドポイント
+
+- **URL:** `/confirm`  
+  **メソッド:** GET  
+  **機能:**  
+  - 現在登録されているメンバー（`users`）を JSON 形式で返す。
+
+---
+
+### 5. 音声アップロード・解析関連
+
+#### a. 基本の音声アップロードと参照音声との照合
+
+- **URL:** `/upload_audio`  
+  **メソッド:** POST  
+  **機能:**  
+  - クライアントから受け取った Base64 形式の音声データをデコードし、一時ファイル（`/tmp/data/tmp.wav`）として保存。  
+  - リクエストボディ内には、`audio_data` とともに、`name` または `users`（登録済みユーザーの情報）が必要。  
+  - 各ユーザーの参照音声ファイル（`/tmp/data/base_audio/{user}.wav`）とアップロードされた音声を比較し、  
+    - 複数ユーザーの場合：`process_multi_audio` を使用して各ユーザー毎の一致時間を計算し、その比率（パーセンテージ）を返す。  
+    - 単一ユーザーの場合：`process_audio` を用いて一致時間と非一致時間から比率（パーセンテージ）を計算して返す。  
+  - また、処理後に複数の音声セグメントをマージし、その結果を `total_audio` に格納する。
+
+#### b. 基準音声のアップロード（ユーザー登録時に使用）
+
+- **URL:** `/upload_base_audio`  
+  **メソッド:** POST  
+  **機能:**  
+  - リクエストボディ内の `audio_data`（Base64形式）と `name` を受け取り、  
+  - `users` リストに名前を追加（重複排除を実施）。  
+  - `/tmp/data/base_audio/` 内に、`{name}.wav` という名前で保存。  
+  - 登録成功時に、状態とファイルパスを返す。
+
+---
+
+### 6. 書き起こし生成およびテキスト解析
+
+#### a. 書き起こし作成
+
+- **URL:** `/transcription`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - グローバル変数 `transcription_text` に書き起こし済みのファイルが存在しない場合、  
+    - `total_audio`（マージ済み音声ファイル）が存在しているかをチェック。  
+    - `TranscriptionMaker` の `merge_segments` メソッドでセグメントをマージし、`create_transcription` で書き起こしファイルを生成。  
+  - 書き起こしファイルを読み込み、内容を JSON 形式で返す。  
+  - エラー発生時には適切な HTTP ステータスコード（400, 404, 500）とエラーメッセージを返す。
+
+#### b. AI によるテキスト解析
+
+- **URL:** `/analyze`  
+  **メソッド:** GET, POST  
+  **機能:**  
+  - `/transcription` と同様に、書き起こしファイルの存在を確認し、必要なら再生成する。  
+  - `TextAnalyzer` クラスを使って、書き起こしテキストとハラスメントキーワードをもとに解析を実施。  
+  - 環境変数 `DEEPSEEK` を API キーとして取得し、DeepSeek 解析を呼び出す。  
+  - 解析結果（会話レベル、ハラスメントの有無や種類、繰り返しの程度、会話の心地よさ、非難やハラスメントの程度など）をコンソール出力し、JSON 形式で返す。
+
+---
+
+## エンドポイント間の流れとポイント
+
+- **ユーザー登録:**  
+  `/upload_base_audio` でユーザーごとの基準音声を登録し、`users` リストに名前を追加。
+
+- **音声解析:**  
+  `/upload_audio` によりアップロードされた音声を、登録された参照音声と照合。  
+  - 複数ユーザーの場合、各ユーザーの一致時間を計算し、パーセンテージとして返す。  
+  - 単一ユーザーの場合、一致時間と非一致時間から比率を返す。  
+  - この段階で、音声セグメントをマージし、後続の書き起こし・解析に利用するために `total_audio` に格納。
+
+- **書き起こしの生成と利用:**  
+  `/transcription` で `total_audio` から書き起こしファイルを生成し、その内容を取得可能。  
+  `/analyze` では、生成済みの書き起こしテキストをもとに、DeepSeek API を用いた AI 解析が実行される。
+
+- **リセット機能:**  
+  `/reset_member` で指定ユーザーの音声ファイル、累積音声、書き起こしファイルを削除。  
+  `/reset` で `users` リストを完全にクリアする。
+
+---
+
+