=====================================================================================
   FreeDV Audio Processor v3                              readme.txt
=====================================================================================

   マイク → Equalizer → ALC（自動レベル制御） → Clipper → 仮想ケーブル → FreeDV
  というオーディオ信号の流れをリアルタイムに可視化するとともに音量や音質を調整するツ
  ールです。
  FreeDV で質の良い変調をかけるために、マイクレベルや音質を適切に調整します。
  
   動作環境 ： Windows 10 / 11 (64bit)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. ファイル構成
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  同じフォルダに以下のファイルを置いて使用します。

  任意のフォルダ/
  ├── FreeDVAudioProcessor.exe       ← 本プログラム（実行ファイル）
  ├── readme.txt                       ← この説明書
  └── freedv_processor_settings.json   ← 設定値保存用ファイル
  
  例）OS(C:)\FreeDV_Audio\FreeDVAudioProcessor.exe 

  ※ freedv_processor_settings.json は FreeDVAudioProcessor.exe を実行すると自動
     生成されます。配布時のzipファイルには含まれていません。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  2. 必要なソフトウェアのインストール
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  このツールの音声出力を FreeDV へ渡すためのソフトウェアが必要となります。
  無料のソフト「VB-Audio Virtual Cable」の利用を推奨します。
  
  「VB-Audio Virtual Cable」のインストール手順
    (1) https://vb-audio.com/Cable/ にアクセス
    (2) "VBCABLE_Driver_Pack45.zip"（またはその時点の最新版）をダウンロード
    (3) ZIP を展開し、VBCABLE_Setup_x64.exe を右クリック →「管理者として実行」
    (4) インストール後、Windows を再起動
    (5) 再起動後、Windows のサウンド設定に以下の3デバイスが追加されます。
          再生デバイス : CABLE Input 、CABLE In 16ch
          録音デバイス : CABLE Output
    (6) インストール後ダウンロードしたファイルを削除

   ※ 再生デバイス CABLE Input は標準的な2chオーディオ処理信号で、CABLE In 16ch は
      最大16chのマルチチャンネル信号です。どちらも利用可能ですが、CABLE In 16ch は
      処理負荷が大きいので CABLE Input の利用を推奨します。

  [信号の流れ]
   🎤 マイク
        ↓
    📊 FreeDV Audio Processor（Equlizer / ALC / Clipper 処理）
        ├─[音声出力]──→ CABLE Input ──→ CABLE Output ──→ 📻 FreeDV
        └─[モニター]─→ 🎧 ヘッドホン / スピーカー（任意）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  3. 起動方法
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  FreeDVAudioProcessor.exe をダブルクリックするとプログラムが起動します。
  
  ※ ショートカットアイコンの作成方法は、exeファイルを右クリックして「その他のオプ
  ションを確認」→「ショートカットの作成(S)」です。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  4. 画面各部の説明
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ● ステータスドット（画面右上）
      灰色 : STANDBY（マイク未使用）
      緑点滅: TX LIVE（音声処理・出力中）

  ● TX 開始 / TX 停止 ボタン
      押すとマイク入力の取得を開始し、仮想ケーブルへの出力が始まります。
      もう一度押すと停止します。

  ● デバイス選択プルダウン（3種類）
      入力(マイク)        : 使用するマイクやオーディオI/Fを選択
      TX出力→仮想ケーブル : CABLE Input を選択（FreeDV へ渡す出力先）
      モニター出力(任意)   : ヘッドホンなど手元で聞くためのデバイス

  ● INPUT メーター（左）
      マイクからの入力レベルを表示します。
      緑ゾーン: -40 ～ -12 dB  （適正）
      橙ゾーン: -12 ～ -3 dB   （やや高め）
      赤ゾーン: -3  ～  0 dB   （過大入力・クリップ注意）
      白い縦線: ピークホールド値

  ● TX OUTPUT メーター（右）
      EQ / ALC / Clipper を通した後、仮想ケーブルへ送出されるレベルです。

  ● マイクゲイン スライダー（INPUT パネル内）
      入力感度を -20 ～ +20 dB の範囲で調整します。
      ツマミは常時緑色で表示されます。

  ● マスター出力 スライダー（OUTPUT パネル内）
      仮想ケーブルへの出力レベルを最終調整します（-20 ～ +6 dB）。

  ● モニター再生 チェックボックス
      チェックを入れると、処理後の音声を「モニター出力」デバイスで
      リアルタイムに確認できます。
      ⚠ スピーカーからマイクへのハウリングに注意してください。
        必ずヘッドホンを使用してください。

  ● スペクトラム / 波形 タブ
      スペクトラム: 周波数ごとのレベル分布を表示します。
                   緑ハイライト帯が FreeDV の音声帯域目安（約300-2700Hz）です。
                   灰色が入力（処理前）、緑が TX 出力（処理後）です。
      波形        : 時間軸の波形を表示します。クリップの有無が確認できます。

  ● チェーンバー（画面下部）
      [🎛 EQUALIZER ▸]  : クリックで EQ 設定ポップアップを開閉
      [📈 ALC ▸]        : クリックで ALC 設定ポップアップを開閉
                           ポップアップを開かなくてもミニメーターで状態確認可
      [✂ CLIPPER ▸]    : クリックで Clipper 設定ポップアップを開閉
                           ポップアップを開かなくても CLIP LED で状態確認可

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  5. 調整手順
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  【STEP 1: デバイスを選択する】

    (1) 「デバイス更新」ボタンを押してデバイス一覧を最新状態にする
    (2) 入力(マイク)  : 使用するマイクを選択
    (3) TX出力        : 「CABLE Input」を選択
    (4) モニター出力  : ヘッドホンが接続されていれば選択（なければ「使用しない」）

  【STEP 2: TX を開始する】

    「TX 開始」ボタンを押す。
    ステータスドットが緑になり「TX LIVE」と表示されれば正常です。

  【STEP 3: マイクゲインを調整する】

    マイクに向かって普通の声量で話しながら、
    INPUT メーターのピーク（白い縦線）が -12 ～ -6 dB 付近に
    収まるようにマイクゲインスライダーを調整します。

      ピークが -12 dB より低い → マイクゲインを上げる
      ピークが -6 dB より高い  → マイクゲインを下げる

  【STEP 4: EQ で音質を整える（任意）】

    「🎛 EQUALIZER ▸」ボタンを押して EQ ポップアップを開きます。

    推奨の初期設定:
      LOW  (200Hz)    : -3 ～ -6 dB（低域の被りを削る）
      LOW-MID (600Hz) :  0 dB（まず変えない）
      HIGH-MID(1800Hz):  0 ～ +3 dB（明瞭度を軽く持ち上げる）
      HIGH (3000Hz)   :  0 dB（過度なブーストは不要）

    スペクトラム表示を見ながら、緑ハイライト帯（300-2700Hz）にエネルギーが収まる
    よう調整します。

  【STEP 5: ALC を調整する】

    「📈 ALC ▸」ボタンを押して ALC ポップアップを開きます。
    話し声の大小に合わせてレベルが自動制御されます。

    推奨の初期設定:
      THRESHOLD : -24 dB
      RATIO     : 8:1
      ATTACK    :  3 ms
      RELEASE   : 250 ms

    ALC リダクションメーターの見方:
      緑ゾーン(0-6 dB)   : 適正な圧縮量
      橙ゾーン(6-12 dB)  : やや強めの圧縮
      赤ゾーン(12dB 以上): 圧縮過多 → THRESHOLD を下げるかマイクゲインを下げて
                           ください

  【STEP 6: クリッパーを確認する】

    「✂ CLIPPER ▸」ボタンを押して Clipper ポップアップを開きます。

    通常は SOFT CLIP / DRIVE = 0 dB で問題ありません。
    CLIP LED（赤）が常時点灯する場合は歪みが発生中です。
    → DRIVE を下げるか、上流（マイクゲイン / ALC）のレベルを見直してください。

  【STEP 7: OUTPUT レベルを確認する】

    TX OUTPUT メーターのピークが -6 ～ -3 dB 程度に収まっていれば仮想ケーブルへ
    適正なレベルで送出されています。

    低すぎる場合 → マスター出力スライダーを上げる
    高すぎる場合 → マスター出力スライダーを下げる

  【STEP 8: FreeDV と無線機での最終確認】

    FreeDV を起動し、PTT を押して実際に送信します。
    無線機側の ALC メーターを見ながら、
    ALC が振れる範囲で最大限スケールするよう微調整してください。

    受信側（別の局・またはダミーロードでの受信確認）で音声が明瞭に聞こえることを
    確認して完了です。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  6. 各モジュールの詳細
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ────────────────────────────────────────
  6-1. EQUALIZER（EQ）
 ────────────────────────────────────────

  4バンドのパラメトリック / シェルビング EQ です。

  ┌─────────────┬────────────────────────┐
  │ バンド   │ 種別         │ 説明                                           │
  ├─────────────┼────────────────────────┤
  │ LOW      │ ローシェルフ │ 200Hz 以下の低域全体を持ち上げ/削る            │
  │          │ 200Hz        │ 男性声のこもり除去: -3 ～ -6 dB が目安         │
  ├─────────────┼────────────────────────┤
  │ LOW-MID  │ ピーキング   │ 600Hz 付近を調整                               │
  │          │ 600Hz        │ ぼやけた印象を改善したい場合に削る             │
  ├─────────────┼────────────────────────┤
  │ HIGH-MID │ ピーキング   │ 1800Hz 付近（子音の明瞭度に関わる帯域）        │
  │          │ 1800Hz       │ 軽くブーストすると声の抜けが良くなる場合がある │
  ├─────────────┼────────────────────────┤
  │ HIGH     │ ハイシェルフ │ 3000Hz 以上の高域全体を調整                    │
  │          │ 3000Hz       │ 必要以上のブーストは雑音感増加の原因になる     │
  └─────────────┴────────────────────────┘

  BYPASS チェックをオンにすると EQ を完全に無効化できます。
  調整前後の音質比較に活用してください。

 ────────────────────────────────────────
  6-2. ALC（自動レベル制御）
 ────────────────────────────────────────

  声の強弱によるレベル変動を自動で抑えるコンプレッサーです。
  無線機の ALC 回路が安定して動くための前段処理として機能します。

  ┌──────────────────────────────────────┐
  │ パラメータ│ 説明                                                          │
  ├──────────────────────────────────────┤
  │THRESHOLD  │ 圧縮を開始するレベル（dB）                                    │
  │           │ この値より大きい音に対して圧縮がかかります。                  │
  │           │ 推奨: -24 dB（音量が足りない場合は上げる）                    │
  ├──────────────────────────────────────┤
  │RATIO      │ 圧縮の強さ（N:1）                                             │
  │           │ 値が大きいほど強く圧縮します。                                │
  │           │ 推奨: 8:1（リミッター的な動作）                               │
  ├──────────────────────────────────────┤
  │ATTACK     │ 音が大きくなったときに圧縮が始まるまでの時間（ms）            │
  │           │ 短すぎると瞬間的な音も圧縮されて不自然になる。                │
  │           │ 推奨: 3 ms                                                    │
  ├──────────────────────────────────────┤
  │RELEASE    │ 音が小さくなったときに圧縮が解除されるまでの時間（ms）        │
  │           │ 短すぎるとポンピング感が出る。                                │
  │           │ 推奨: 250 ms                                                  │
  └──────────────────────────────────────┘

 ────────────────────────────────────────
  6-3. CLIPPER / LIMITER（クリッパー）
 ────────────────────────────────────────

  ALC 後の過大レベルを最終的にカットするリミッターです。

  ┌──────────────────────────────────────┐
  │ パラメータ│ 説明                                                          │
  ├──────────────────────────────────────┤
  │DRIVE      │ クリッパー前の増幅量（dB）                                    │
  │           │ 0 dB から少しずつ上げ、CLIP LED が点灯し始める手前が目安。    │
  │           │ 過度に上げると音が歪みます。                                  │
  ├──────────────────────────────────────┤
  │SOFT CLIP  │ tanh 関数による滑らかな飽和（推奨）                           │
  │           │ 小さな音は変化なし、大きな音だけ徐々に丸める。                │
  │           │ 自然な音質で制限できます。                                    │
  ├──────────────────────────────────────┤
  │HARD CLIP  │ -1.0 ～ +1.0 でハードにカット                                 │
  │           │ 高い平均電力が必要な場合に使用。歪みが出やすい。              │
  ├──────────────────────────────────────┤
  │CLIP LED   │ 赤く光っている間はクリッピング（歪み）が発生中です。          │
  │           │ 常時点灯する場合は DRIVE を下げてください。                   │
  └──────────────────────────────────────┘

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  7. 設定の保存と復元
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   ツールを閉じると、すべての設定値が自動的に保存されます。
   次回起動時に前回の設定が自動的に復元されます。

  【保存される設定】
    - マイクゲイン / マスター出力
    - EQ の各バンドゲイン / バイパス状態
    - ALC の THRESHOLD / RATIO / ATTACK / RELEASE / バイパス状態
    - Clipper の DRIVE / モード（SOFT/HARD）/ バイパス状態
    - モニター再生のオン/オフ・音量
    - デバイス選択（デバイス名で記憶）
    - スペクトラム / 波形 の表示切替

  【設定ファイルの場所】
    FreeDVAudioProcessor.exe と同じフォルダに保存されます。
    freedv_processor_settings.json

    設定をリセットしたい場合は、このファイルを削除してください。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  8. 開発・技術情報
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  言語    : Python 3.10+
  GUI     : tkinter（標準ライブラリ）
  音声処理: sounddevice + numpy
  DSP     :
    EQ   → RBJ Audio EQ Cookbook 準拠のバイクアッドフィルタ
    ALC  → フィードフォワード型コンプレッサー（ソフトニー付き）
    CLIP → ソフトクリップ（tanh 基底のソフトニーリミッター）
            / ハードクリップ（-1.0 ～ +1.0 ハードリミット）

 ※ pyinstaller により exe ファイルに変換し配布しています。

=====================================================================================

  このプログラムは生成AIで作成されています。
  プログラムの改変、配布は自由です。
  
  2026/7/4
  JA3WUI/Tonaru
  https://tonaru.net/details7.html#radio-42

=====================================================================================
