VoiceMemoLM 操作ガイド

アプリ全体の流れ

VoiceMemoLM は、音声の取り込み → Markdown 化 → 知識検索・活用 の 3 ステップで構成されています。

1. ClipView で音声ファイルまたはフォルダをインポートすると、自動で文字起こしと要約が走り、Markdown が生成されます。
2. FileView で生成された Markdown を一覧・検索・リネームし、波形と同期しながら内容を再生できます。
3. AskView で蓄積した Markdown をまとめて参照しながらチャット形式で質問できます。業務ノートや会議録のナレッジベースとして活用できます。

初期設定と環境準備

初回起動時に確認する項目

• 初めて ClipView で「インポート」するときは、ファイルアプリのアクセス許可が求められるので許可してください。
• バックグラウンド実行や通知を利用するため、通知の許可を求められた場合は「許可」を推奨します。

設定画面（歯車アイコン）で整える内容

ClipView と FileView の右上にある歯車アイコンから SettingsView を開けます。主な設定項目は以下の通りです。

設定を保存すると次回以降の処理に即時反映されます。特に 無音カット や タイムスタンプの有無 は ClipView の挙動に影響するので、業務用途に合わせて調整してください。

ClipView（Clip/Transcribe タブ）の使い方

ClipView は音声ファイルをまとめて処理する中心画面です。アプリのタブバーで Clip（表示タイトルは Transcribe）を選択すると表示されます。

基本フロー

1. 画面上部の Reset アイコンで状態を初期化し、前回の選択をクリアできます。
2. インポート ボタンを押すとファイルピッカーが開き、音声ファイル（複数選択やフォルダ選択も可能）を追加できます。選択が完了するとファイル一覧が内部にコピーされ、自動的に処理がスタートします。
3. 選択後は確認ダイアログが表示され、必要に応じて「リセット」でキャンセル可能です。特に問題がなければそのまま待機します。
4. 画面中央の円形プログレスとテキストで進捗が確認できます。
   例：「バッチ処理中」「バックグラウンドで実行中」 といったステータスが表示されます。
5. 右上の小さなプログレスインジケータでステータスを常時確認できます。処理中はタスクキルせず、アプリを前面またはバックグラウンドで待機してください。
6. 処理完了後はダイアログで通知され、「OK」を押すと FileView へ移動して生成された Markdown を開けます。

画面内の操作パーツ

• 波形プレビュー: インポートした直近の音声エネルギーを可視化します。無音カットの閾値を設定している場合、緑と赤の背景で検出具合を確認できます。
• 進捗メッセージ: 「インポート処理中 (アプリから離れないでください!)」「処理の準備ができています」など状況に合わせたメッセージが表示されます。
• インポート済みファイル一覧: インポート後に表示される i アイコンから、選択中ファイル名とサイズを一覧できます。
• 設定（歯車）: Whisper モデルや Git 連携などの詳細設定にアクセスします。

処理内容の概要

ClipView では以下の処理が順番に実行されます。

• 必要に応じて無音区間をトリムしてから文字起こしを実施。
• ローカルまたはクラウドのモデルで要約文とファイル名候補を生成。
• Markdown に「要約」「全文書き起こし」「タイムスタンプ付きコードブロック」などを保存。
• Git 連携が有効な場合は、生成した Markdown を push して PR を作成するか、既定ブランチへ直接反映します。結果に応じて PR URL を開くか選択できます。

FileView（ファイル管理タブ）の使い方

FileView では生成された Markdown を一覧し、詳細を確認・編集できます。タブバーで File を選択すると表示されます。

一覧画面のポイント

• プルダウンで更新: 下に引っ張ると最新のファイル一覧を取得します。
• ソート: 左上の上下矢印メニューで「昇順 / 降順」を切り替えできます。ファイル名冒頭に含まれるタイムスタンプ（yyyy-MM-dd-HH-mm-ss）をもとに並び替えます。
• 日付フィルタ: カレンダーアイコンから特定の日付のファイルだけを表示できます。シートで「クリア」を選ぶと解除されます。
• 検索: 右上の虫眼鏡で検索バーを表示し、ファイル名と本文の両方を対象に検索します。本文ヒット時はヒット件数と一行プレビューが表示されます。
• リネーム: 行を長押しして「Rename」を選ぶか、詳細画面右上の鉛筆アイコンからタイトルと本文をまとめて編集できます。タイムスタンプ部分は自動で保護されます。
• 設定: 右上の歯車から SettingsView を開き、ClipView と同じ詳細設定へアクセスできます。

Markdown 詳細画面

• 左右 2 ペイン表示: 左側にタイムスタンプ付きの文字起こし、右側に要約・メモを表示します。タイムラインをタップすると該当位置へ音声がシークします。
• 音声プレーヤー: 下部に波形付きプレーヤーを備え、再生・巻き戻し・早送り・再生速度変更・シークができます。音声が見つからない場合は案内が表示されます。
• コピー & リンク: Git 連携が有効なら、右上の矢印アイコンからリポジトリ上の該当ファイルを開いたり、最新の内容を pull できます。
• リネームボタン: 鉛筆アイコンからタイトルと本文を編集できます。保存時に Git 連携が有効なら自動で push / PR まで実行されます。
• ステッキー見出し: 要約側のスクロール中もファイル名が固定表示されるので、どのメモを見ているか迷いません。

AskView（質問タブ）の使い方

AskView は蓄積した Markdown を文脈として活用しながら質問できるチャット画面です。タブバーで Ask を選択します。

チャット一覧画面

• 新規チャット: 右上の + で新しいスレッドを作成します。作成直後は入力欄が展開された状態になります。
• 検索: 上部の検索バーでタイトルだけでなく本文も対象にフィルタリングし、ヒットした一行をプレビュー表示します。
• スワイプ操作: 行を左へスワイプすると「削除」「名前変更」が表示されます。長押しでも同じメニューにアクセスできます。
• 自動タイトル: 初回の質問と回答が完了すると、内容から 15 文字以内のタイトルが自動生成されます。

チャット詳細画面

• 対象期間の設定: 画面下部のガラス調コンテナで、カレンダーアイコンから期間シートを開いて任意の日付に設定できます。プリセット（今日・昨日・直近7日）も利用可能です。
• 対象ファイル一覧: リストアイコンから、質問に使われる Markdown ファイルの一覧を確認できます。
• 入力欄の最小化: 右上の斜め矢印で入力欄を折りたたみ、画面右下のペンアイコンから再度展開できます。
• 質問送信: テキストエディタに入力し、紙飛行機アイコンまたは ⌘ + Enter で送信します。送信中はプレースホルダのメッセージが表示されます。
• Markdown 表示: アシスタントの回答は Markdown 形式で表示され、リンクや箇条書きも綺麗にレンダリングされます。長文は「続きを読む」で展開可能です。
• コピー: 右上の書類アイコンで会話全体をまとめてクリップボードにコピーできます。各メッセージを長押しして個別コピーも可能です。

SettingsView（設定タブ）の使い方

ClipView と FileView の右上にある歯車アイコンから SettingsView を開きます。Sources/View/SettingsView.swift に定義されている各種設定は、以下のカテゴリで整理されています。

文字起こし・要約のコア設定

• 要約モード: SummaryMode（ローカル / Gemini）を切り替えます。クラウドを選ぶと Gemini API Key が必要です。
• デフォルト言語: 文字起こし言語を指定します。日本語を含む 60 以上の言語から選択でき、@AppStorage で永続化されます。
• タイムスタンプ / 特殊文字: タイムスタンプの付与や特殊文字の扱いをトグルで制御します。
• サイレンスカット・デコーダプレビュー: 無音カットや Decoder プレビューなど WhisperKit の詳細挙動を設定します。

デコーディング詳細とパフォーマンス

• Prompt / Cache Prefill: 初期化時のキャッシュ利用を制御し、推論速度を最適化します。
• チャンク戦略・温度パラメータ: chunkingStrategy や temperatureStart を調整して生成品質をチューニングします。
• Fallback・サンプル長: fallbackCount や sampleLength を設定し、長尺ファイルの安定性を高めます。
• Compute Units: エンコーダ・デコーダで使用する MLComputeUnits（CPU/GPU/Neural Engine）を個別に選択できます。
• 推奨モデル: openai_whisper-* 系を中心にローカルで検出したモデルが Picker に並びます。Discover Local Models をタップすると再スキャンできます。

Gemini / Git 連携エリア

• Gemini API Key: 安全に Keychain へ保存され、再表示時は「保存済み」バッジで確認できます。
• GitHub トークン: SecureField で入力し、Keychain に暗号化保存します。保存済みなら「Saved」表示に変わります。
• Git オプション: リポジトリ URL、保存先ディレクトリ、PR 作成の有無などを個別に切り替えられます。ファイル編集時専用の PR 設定も用意されています。
• ログ共有: WhisperKit のログを共有シート経由で書き出せるため、トラブルシュートが容易です。

Gemini / Google API Key の設定方法

Gemini を使ったクラウド要約を有効化するには、Google が提供する API Key を取得し、アプリに保存する必要があります。

API Key の取得手順

1. Google Cloud Console にアクセスし、Google アカウントでログインします。
2. 画面上部のプロジェクトセレクタから既存プロジェクトを選ぶか、新しいプロジェクトを作成して Gemini 用のワークスペースを用意します。
3. 左上のハンバーガーメニューから API とサービス > ライブラリ を開き、検索欄で「Vertex AI API」（または「Generative Language API」）を検索して 有効化 します。
4. API とサービス > 認証情報 を開き、認証情報を作成 > API キー を選択します。生成されたキーがダイアログで表示されるのでコピーして安全な場所に控えます。
5. 必要に応じて キーの制限 を設定し、API の利用先を Vertex AI API に限定すると安全性を高められます。

VoiceMemoLM への登録

1. アプリで SettingsView を開き、Gemini API Key の入力欄に取得したキーを貼り付けます。
2. Save ボタンを押すと Keychain に暗号化保存され、「保存済み」バッジが表示されます。
3. 要約モードを「Gemini」に切り替えて、AskView や ClipView の要約がクラウド経由で動作することを確認します。

GitHub 連携の手順

Git 連携を活用すると、生成した Markdown や音声ファイルを GitHub リポジトリへ自動同期できます。SettingsView の GitHub Integration ブロックから設定します。

事前準備

• アクセストークン: GitHub の Personal Access Token を repo 権限付きで発行します。
• 保存先リポジトリ: Markdown を保管したいリポジトリとブランチを事前に用意し、初回だけ手動でクローンしておくとスムーズです。

アプリ側の設定

1. SettingsView の GitHub Integration をオンにし、Repository URL と Save Directory を入力します。
2. GitHub Token の欄に Personal Access Token を貼り付け、Save で Keychain に保存します。保存済みの場合は「Saved」と表示されます。
3. 必要に応じて Create Pull Request や Create PR on File Update を有効にし、Push のたびに PR を自動作成するかどうかを選びます。

運用時のポイント

• ClipView / FileView で生成・編集した Markdown は、処理完了後に自動で git add → commit → push が実行され、設定に応じて PR URL が表示されます。
• ログ共有機能で Git のエラー詳細を確認できるため、認証エラーや競合が起きた場合はメッセージを確認して再設定してください。
• トークンを更新したときは旧トークンを SettingsView でクリアし、新しいトークンを再保存することで認証情報をリフレッシュできます。

日常運用のモデルケース

1. 会議終了後: 会議の音声を ClipView でインポートし、無音カットとタイムスタンプを有効にした状態でバッチ処理を実行します。
2. レビュー: 処理が完了したら FileView で Markdown を開き、タイトルを会議名にリネームします。必要であれば要約本文に追記します。
3. 共有: Git 連携を有効にしている場合、Push/PR が完了した旨のダイアログが表示されるので、そのまま GitHub で内容を確認します。
4. 後日検索: AskView の日付範囲を会議日付に合わせ、決定事項や経緯をチャット形式で検索します。

ヒント・トラブルシューティング

• 処理が止まったように見える: 円形プログレスの内側に表示されるメッセージを確認し、バックグラウンドで実行中 の場合はアプリを閉じずに待機してください。必要であれば Reset でやり直せます。
• 音声が再生できない: Markdown と同じフォルダに音声が保存されているか確認してください。ファイル名のタイムスタンプが一致しない場合は、FileView 詳細画面の波形セクションに「対応する音声が見つかりません」と表示されます。
• Git 連携が失敗する: SettingsView でトークンとリポジトリ設定が正しいか確認し、アプリ内の通知に表示されるメッセージを参考にしてください。失敗時はログに詳細が残ります。
• AskView で古い情報が出る: 日付範囲が広すぎる可能性があります。Range シートで対象期間を絞り込むと最新情報に集中できます。
• ローカルモデルが見つからない: SettingsView のモデル一覧に表示されているか確認し、huggingface/models/<repo> 配下にモデルフォルダが存在するかをチェックしてください。
• 録音品質を底上げする: ハードウェアを強化したい場合は、長時間録音に対応しノイズカット機能も備えた Sony ICD-UX570F などのボイスレコーダーを利用すると文字起こしの精度が安定します。

それでも解決しない場合は、SettingsView のログ共有機能からログをエクスポートし、開発チームへ共有してください。