Allow manual correction of AI-extracted song metadata

[GeneralD]

記録ステータス: ・方針確定済み、は。大きい機能なので一旦この本文に全と計画をし、日ここからする。時点 = origin/main の c7a0d04（2026-06-14）。作業ブランチ feat/53/manual-metadata-correction（worktree 保持中）。

Motivation

The AI-based title/artist extraction (#51) works well in most cases, but occasionally returns incorrect results. Once a wrong result is cached, it persists until the cache is manually cleared. Users need a way to correct misidentified songs without developer intervention.

Proposal

Provide a mechanism for users to override AI-extracted metadata when it is incorrect. Possible approaches:

• Keyboard shortcut or menu to cycle through alternative candidates
• A way to clear the cached AI result for the current song and retry
• Manual title/artist override via or config

Related

• Use LLM to extract song title and artist from metadata #51 — AI metadata extraction (implemented)

---

確定スコープ

• 案（候補サイクル ）＋ 案（キャッシュクリア再試行）＋ 案（手動オーバーライド）すべてをする。
• 手動オーバーライドのはキャッシュ直書き方式。 ただし述の is_override 列でする。
• 案 は NSStatusItem（メニューバー常駐） でする（グローバルホットは採らない）。

---

A. メタデータ解決パイプライン

解決の順位（Sources/MetadataRepository/MetadataRepositoryImpl.swift）:

1. LLM cache（ai_metadata_cache）
2. LLM DataSource（LLMMetadataDataSourceImpl）
3. MusicBrainz cache（musicbrainz_cache）
4. MusicBrainz DataSource
5. Regex DataSource（キャッシュなし）

:

• LLM は常に単一候補しか返さない（[Track] だが要素は最大）。複数候補を返すのは MusicBrainz（最大件 × 各バリエーション）と Regex。
• 候補配列は呼び出し元まで渡るが、キャッシュへの write は常に .first のみ。
• MetadataUseCaseImpl（Sources/MetadataUseCase/MetadataUseCaseImpl.swift）には resolve()（先頭のみ）と resolveCandidates()（全候補） の両方が公開済み。→ 候補サイクル はこの resolveCandidates() をそのまま使える。
• LLM 抽出（Sources/MetadataDataSource/LLMMetadataDataSourceImpl.swift）は configDataSource.load()?.config.ai から AIEndpoint を取り、MetadataExtractionPrompt を組んで OpenAICompatible（Papyrus）で chat completion を叩き、{title, artist} にデコードする。は MediaRemote の生 track.title / track.artist 文字列。

B. キャッシュとストア

• プロトコル MetadataDataStore（Sources/Domain/DataStore/MetadataDataStore.swift）は read(title:artist:) と write(title:artist:value:) のみ。delete / clear はしない。
• write は onConflict: .replace（UPSERT 相当）なので上書きは。
• キャッシュは両ストアとも (raw_title, raw_artist) の複合ユニーク。すなわち MediaRemote がする生の曲名・アーティスト文字列のペア。ファイルや内部 ID は使っていない。
• テーブル定義（Sources/SQLiteDataStore/DatabaseManager.swift のマイグレーション）:
  • v3 ai_metadata_cache — (raw_title, raw_artist) → (resolved_title, resolved_artist)（GRDBLLMMetadataDataStore）
  • v2 musicbrainz_cache — (query_title, query_artist) → (resolved_title, resolved_artist, duration, musicbrainz_id)（GRDBMetadataDataStore）
• SQLite 実体は ~/.cache/lyra/database 単一ファイル（XDG_CACHE_HOME 尊重。Folder+DefaultCache.swift / DatabaseManager.swift）。歌詞・Wallpaper キャッシュも。

C. オーバーレイのハンドリング

• AppWindow（Sources/Views/Overlay/AppWindow.swift）は styleMask: .borderless ＋ ignoresMouseEvents = true ＋ window level = desktopWindow + 1（通常ウィンドウより下）＋ collectionBehavior = [.canJoinAllSpaces, .stationary, .ignoresCycle]。canBecomeKey/canBecomeMain は未オーバーライド（→ false）。
• アプリの activationPolicy は .accessory（Sources/App/ForegroundApplication.swift）。
• → オーバーレイウィンドウ自体はもクリックも受け取れない（クリックは下のウィンドウへ透過する的）。
• グローバルモニタは RipplePresenter（Sources/Presenters/Wallpaper/RipplePresenter.swift）の NSEvent.addGlobalMonitorForEvents(matching: .mouseMoved) が唯一。ボードモニタは未使用。
• な: 初期で「.accessory だと NSStatusItem を持てない」としたが、これは誤り。.accessory（LSUIElement 相当）アプリでもメニューバー常駐アイコン NSStatusItem は所有できる（メニューバーに独自のアプリメニューが出ないだけで、ステータスバー項目は別物）。これが案 の手段になる。

D. CLI / config / daemon

• サブコマンド（Sources/CLI/Commands/RootCommand.swift）: start / stop / restart / service / completion / version / daemon / healthcheck / config / track / benchmark。cache 操作系コマンドは無い。
• lyra track -r（TrackCommand / TrackHandlerImpl）がワンショットでメタデータ解決を走らせる経路。
• AIConfig（Sources/Entity/Config/AIConfig.swift）は endpoint / model / apiKey のみ。override 用フィールド無し。
• daemon と CLI は別プロセスで IPC が一切無い（XPC / Darwin notify / Unix socket / NSDistributedNotification すべて未）。両者は SQLite キャッシュ経由でのみ間接する。
• daemon 側 TrackInteractorImpl（Sources/TrackInteractor/TrackInteractorImpl.swift）は observeNowPlaying() を購読し removeDuplicates(by: sameTrack) でトラックのイベントを無視する。→ CLI でキャッシュを書き換えても「今まさに再生中の曲」は再描画されない（次曲 / 同曲再生し直し / lyra restart が）。

---

方針の — なぜ NSStatusItem か

NSStatusItem のメニューは daemon プロセス内で動く。したがって Presenter / Interactor に直接アクセスでき、ユーザーが候補を選んだ瞬間に新しい TrackUpdate を TrackInteractor から直接流して再描画できる（removeDuplicates(by: sameTrack) を迂回する経路を本足すだけ）。

つまり CLI 経由では IPC が無くて不だった「再生中の曲への」が、（in-process）経由なら IPC 無しでする。 これが案 を採る最大のであり、グローバルホット（.keyDown グローバルモニタ / CGEventTap は Accessibility がで侵襲的）を避ける。

---

メニュー案（案 ）

[lyra アイコン]
├─ 現在: <resolved title> — <resolved artist>   (表示のみ・無効化)
├─ 候補を選ぶ ▸
│    ├─ ✓ <candidate 1>
│    ├─   <candidate 2>
│    └─   <candidate 3> …          (MetadataUseCase.resolveCandidates の結果)
├─ 手動で入力…                      (title/artist 入力パネル)
├─ ─────────────
└─ キャッシュをクリアして再解決      (案2)

• 「候補を選ぶ」「手動で」= 案（オーバーライドをキャッシュへ直書き ＋ ）
• 「キャッシュをクリアして再解決」= 案

---

計画（.claude/rules/module-checklist.md ）

1. キャッシュ （案） — MetadataDataStore プロトコルに delete(title:artist:) をし、GRDBLLMMetadataDataStore / GRDBMetadataDataStore に。
2. オーバーライド — ai_metadata_cache に is_override INTEGER DEFAULT 0 列をマイグレーション。手動値は is_override = 1 で write し、案のクリアは is_override = 0 の行だけする。これで「キャッシュ直書き」のまま、再解決クリアがユーザーの手動を巻き込まない（直書き方式のを本で補う）。
3. 候補取得 — MetadataUseCase.resolveCandidates(track:) を流用。
4. メニューバー （案） — Views/App 層に NSStatusItem 所有者を（VIPER に合わせ Presenter ＋ Interactor 、AppRouter で wireframe 配線）。
5. — オーバーライド適用後に TrackInteractor が現在トラックを再 emit する経路を（removeDuplicates 迂回）。
6. CLI（補助） — Handler をして lyra metadata clear / lyra metadata set --title --artist を（ を使わない運用・スクリプト向け。CLI 経由は従来どおり次曲 or lyra restart で）。

---

残（時に詰める）

1. 手動パネルの activation — .accessory のままテキストにフォーカスを当てられるか。なら中だけ的に .regular へ昇格し、閉じたら戻す。
2. 候補の鮮度 — メニューを開いた時点で resolveCandidates を都度叩くか、直近をキャッシュするか。
3. CLI のコマンド形 — metadata を独立サブコマンドにするか track の拡張にするか。
4. MusicBrainz 側のオーバーライド — is_override は ai_metadata_cache のみ。MusicBrainz cache 由来の誤りも上書きにするか（解決順で LLM cache が先に当たるため、LLM 側に override を書けばカバーできる見込み）。

---

の起点（再開時メモ）

• ブランチ: feat/53/manual-metadata-correction（worktree .claude/worktrees/feat-53-metadata-correction、origin/main 起点）
• まず手を付けるべきは （delete ）→ （is_override マイグレーション） の層から。（）はその。
• 主要ファイル: Sources/Domain/DataStore/MetadataDataStore.swift / Sources/SQLiteDataStore/{GRDBLLMMetadataDataStore,GRDBMetadataDataStore,DatabaseManager}.swift / Sources/MetadataRepository/MetadataRepositoryImpl.swift / Sources/MetadataUseCase/MetadataUseCaseImpl.swift / Sources/TrackInteractor/TrackInteractorImpl.swift / Sources/App/ForegroundApplication.swift / Sources/AppRouter/（NSStatusItem 配線先）

[GeneralD]

メモ（に入るの事前）

コードベースをした、issue 本文の案のうちどれが現アーキと相性が良いかがはっきりしたのでする。結論を先に言うと「オーバーレイ上の 操作（案）は高コスト・低相性、CLI ファースト（案 + 案）が」。

わかったつの

1. オーバーレイは完全に非インタラクティブ。 AppWindow は styleMask: .borderless + ignoresMouseEvents = true + window level がデスクトップ直上、canBecomeKey/canBecomeMain 未オーバーライド（→ false）。アプリの activationPolicy は .accessory で、メニューバー / NSStatusItem を一切持たない。ウィンドウはもクリックも受け取れない（クリックは下のウィンドウへ透過する的）。
2. メタデータキャッシュに が無い。 MetadataDataStore プロトコルは read / write のみ（delete/clear 無し）。キャッシュは (raw_title, raw_artist) = MediaRemote がする生の曲名・アーティスト文字列のペア。write は onConflict: .replace なので上書きは。
3. daemon と CLI は別プロセスで IPC が無い。 両者は SQLite キャッシュ（~/.cache/lyra/database）経由でのみ間接する。さらに daemon の TrackInteractor は removeDuplicates(by: sameTrack) で**トラックのイベントを無視する**ため、「今まさに再生中の曲」のキャッシュを書き換えてもでは再描画されない。

調査の根拠（ファイル・該当箇所）

メタデータパイプライン

• Sources/MetadataRepository/MetadataRepositoryImpl.swift — 解決順位: LLM cache → LLM DataSource → MusicBrainz cache → MusicBrainz DataSource → Regex。cache write は常に候補の .first のみ。
• Sources/MetadataUseCase/MetadataUseCaseImpl.swift — resolve() は .first、resolveCandidates() は全候補を返す公開 あり。
• LLM (LLMMetadataDataSourceImpl) は単一候補のみ返す（[Track] だが要素は最大）。MusicBrainz / Regex は複数候補を返す。
• Sources/Domain/DataStore/MetadataDataStore.swift — read(title:artist:) / write(title:artist:value:) のみ。
• Sources/SQLiteDataStore/GRDBLLMMetadataDataStore.swift — テーブル ai_metadata_cache、複合 (raw_title, raw_artist) → (resolved_title, resolved_artist)。
• Sources/SQLiteDataStore/GRDBMetadataDataStore.swift — テーブル musicbrainz_cache、 (query_title, query_artist)。
• キャッシュ実体: ~/.cache/lyra/database（Folder+DefaultCache.swift / DatabaseManager.swift、XDG_CACHE_HOME 尊重）。

オーバーレイ

• Sources/Views/Overlay/AppWindow.swift — .borderless / ignoresMouseEvents = true / overlayLevel = desktopWindow + 1 / collectionBehavior = [.canJoinAllSpaces, .stationary, .ignoresCycle]。
• Sources/App/ForegroundApplication.swift — setActivationPolicy(.accessory)。NSMenu / NSStatusItem の使用はコードベースで 0 件。
• Sources/Presenters/Wallpaper/RipplePresenter.swift — 唯一のグローバルモニタ（NSEvent.addGlobalMonitorForEvents(matching: .mouseMoved)、Accessibility ）。ボードモニタは未使用。

CLI / config / daemon

• Sources/CLI/Commands/RootCommand.swift — サブコマンド: start / stop / restart / service / completion / version / daemon / healthcheck / config / track / benchmark。cache 操作系コマンドは無い。
• Sources/CLI/Commands/TrackCommand.swift + TrackHandler — lyra track -r がワンショット解決経路。
• Sources/Entity/Config/AIConfig.swift — endpoint / model / apiKey のみ。override 用フィールド無し。
• Sources/TrackInteractor/TrackInteractorImpl.swift — observeNowPlaying() を購読、removeDuplicates(by: sameTrack) で曲を無視。
• IPC（XPC / Darwin notify / Unix socket / NSDistributedNotification）は未（grep 0 件）。

各案の

案	性	コメント
案: /メニューで候補サイクル	高コスト	オーバーレイが・クリックを受け取れない。グローバルホットはだが macOS の **Accessibility **がで侵襲的。メニューバー化は .accessory + NSStatusItem のが要る。別 issue / 将来に切り出すことを。
案: キャッシュをクリアして再試行		MetadataDataStore に delete(title:artist:) を + 新 CLI で。
案: 手動 title/artist オーバーライド	確実	最も確実に「正しい値」を固定できる。config or CLI で。

方針 — CLI ファースト・段

Phase 1（このスコープ）

• (A) 再解決用のキャッシュ
  • MetadataDataStore に delete(title:artist:) を（LLM / MusicBrainz 両ストア）。
  • 新 CLI（仮 lyra metadata clear）: 引数なしなら現在再生中の曲の (raw_title, raw_artist) を MediaRemote から取得して該当行を、--title/--artist で明示指定も可。次回解決時に LLM / MusicBrainz へ再問い合わせ。
• (B) 手動オーバーライド
  • 「正しい値」を (raw_title, raw_artist) → (title, artist) でマップとして保持し、MetadataRepository.resolve() の 最（LLM cache より）でする。
  • 新 CLI（仮 lyra metadata set --title X --artist Y）で登録。

Phase 2（別 issue 候補）

• のための IPC（Darwin notification / SQLite ）。
• 候補サイクル （案）。

決めたい

1. オーバーライドの先（B の置き場所）
   • B1: config の override テーブル（例 [[metadata.overrides]]）。宣言的・で、キャッシュ全しても消えない。raw 文字列は lyra track でできる。— 個人的にはこちらが（ユーザーの「的な真実」と的な計算であるキャッシュを別レイヤーに分けたい。混ぜると将来のキャッシュ化で手動まで飛ぶ。Cache-Aside の cache とは別物として扱う考え方）。
   • B2: 手動値をそのまま ai_metadata_cache に直書き（write 流用）。は最小だが、キャッシュと的のがになる。
2. を Phase 1 に含めるか。 現状 IPC が無いため、Phase 1 は「次曲 / 同曲を再生し直す / lyra restart で」と割り切るのが軽い。がなら IPC が要るのでスコープが膨らむ。
3. 案（候補サイクル ）をこの issue のスコープに含めるか、別 issue に切り出すか。

方針が固まればこの issue をスコープにする。

[GeneralD]

方針確定 — スコープと計画

のに決着がついたので、スコープを確定する。

事項

• スコープ: 案（候補サイクル ）＋ 案（キャッシュクリア再試行）＋ 案（手動オーバーライド）すべて。
• オーバーライドの: キャッシュ直書き方式。

コメントの（）

で「.accessory だと NSStatusItem を持てない」と書いたが、これは誤り。.accessory（LSUIElement 相当）アプリでもメニューバー常駐アイコン（NSStatusItem）は所有できる（独自のアプリメニューがメニューバーに出ないだけで、ステータスバー項目は別物）。グローバルホット（NSEvent の .keyDown グローバルモニタ / CGEventTap）は macOS の Accessibility を要求して侵襲的なので、**案 は NSStatusItem メニューでするのを**する。

このでのが解ける

NSStatusItem のメニューは daemon プロセス内で動く。つまり Presenter / Interactor に直接アクセスでき、ユーザーが候補を選んだ瞬間に新しい TrackUpdate を TrackInteractor から直接流して再描画できる（removeDuplicates(by: sameTrack) を迂回する経路を本足すだけ）。CLI 経由では IPC が無くて不だった「再生中の曲への」が、 経由なら IPC 無しでする。 これが案 を選ぶ最大の。

メニュー案

[lyra アイコン]
├─ 現在: <resolved title> — <resolved artist>   (無効化・表示のみ)
├─ 候補を選ぶ ▸
│    ├─ ✓ <candidate 1>
│    ├─   <candidate 2>
│    └─   <candidate 3> …          (MetadataUseCase.resolveCandidates の結果)
├─ 手動で入力…                      (title/artist 入力パネル)
├─ ─────────────
└─ キャッシュをクリアして再解決      (案2)

候補を選ぶ／手動 = 案（オーバーライドをキャッシュへ直書き＋）、最下段 = 案。

計画（module-checklist.md ）

1. キャッシュ （案） — MetadataDataStore プロトコルに delete(title:artist:) をし、GRDBLLMMetadataDataStore / GRDBMetadataDataStore に。
2. オーバーライド — ai_metadata_cache に is_override INTEGER DEFAULT 0 列をマイグレーション。手動値は is_override = 1 で書き込み、案のクリアは is_override = 0 の行だけ消す。これで「キャッシュ直書き」のまま、再解決クリアがユーザーの手動を巻き込まない（直書き方式のを本で補う）。
3. 候補取得 — MetadataUseCase.resolveCandidates(track:) をそのまま流用。
4. メニューバー （案） — Views/App 層に NSStatusItem 所有者を（VIPER に合わせ Presenter ＋ Interactor 、AppRouter で wireframe 配線）。
5. — オーバーライド適用後に TrackInteractor が現在トラックを再 emit する経路を。
6. CLI（補助） — Handler をして lyra metadata clear / lyra metadata set --title --artist も（ を使わない運用やスクリプト向け。CLI 経由は従来どおり次曲再生 or lyra restart で）。

残る小（中に詰める）

1. 手動パネルの activation — .accessory のままテキストフィールドにフォーカスを当てられるか。なら中だけ的に .regular へ昇格して閉じたら戻す。
2. 候補の鮮度 — メニューを開いた時点で resolveCandidates を都度叩くか、直近をキャッシュするか。
3. CLI の metadata サブコマンドを独立コマンドにするか track の拡張にするか。

異論なければこのスコープでに入る。