lyrics-everywhere

耳邊字幕（Lyrics Everywhere）

Chrome／Edge 側欄空耳跟唱工具：單曲使用 LRCLIB 同步歌詞，自動比對失敗時可自己指定歌曲（LRCLIB 搜尋連結，或把提示詞貼到自己的 AI 再貼回結果）。YouTube 合輯可在本機建立文字字幕後二刷跟唱；音訊辨識使用裝置上的 WebGPU Whisper。沒有 localhost companion、CLI、雲端音訊辨識、內建共用金鑰或共用字幕服務。

功能

• 自動單曲跟唱／指定來源：開啟側欄預設讀取目前 YouTube、YouTube Music 或 Spotify Web 分頁；「播放來源與說明」的「播放分頁」可指定某個分頁。跟隨模式切換作用中分頁會重新匹配；指定模式切換其他分頁不換歌詞，指定分頁內換歌仍會重新匹配。指定來源關閉時會清除舊歌詞並提示重新選擇，不偷偷改用其他分頁。比對歌曲名稱與可信歌手，合併文字及行、字時間戳完全相同的重複資料，優先選片長最接近的版本，同分時依歌手別名順序、LRCLIB ID 穩定選取。多筆候選會標示「自動選版」；沒有可信歌手或有效同步歌詞時不顯示。播放資訊失聯時凍結同步位置。
• YouTube 音樂標題：支援 [MV]／[Official Music Video] 等前綴及既有音樂影片後綴，辨識「歌手 - 歌名」或「歌手 _ 歌名」；保留歌手的雙語別名（含 박재범 Jay Park、EXO 엑소 這類以空白分隔的韓英名稱），英文歌名附韓文名稱時以英文名查詢，移除完整的末尾 feat. 合作歌手註記。Live 等版本標註不會被移除，後面另有版本標註時亦保留合作資訊。沒有明確音樂標籤的分隔標題與一般上傳頻道不會自動被當成可信歌手；取得資料後仍須精確匹配歌名、歌手。播放清單或推薦影片換片時，等 YouTube 頁面標題、影片 ID 與正片片長一致後才回報，避免用上一首標題或廣告片長查詞。
• 歌名格式與查詢容錯：LRCLIB 比對容許 feat.、ft.、featuring、合作演出註記、全形字元與明確列出的中／日／韓文及英文雙語名稱；支援圓括號與方括號，只有同一可信歌手的相符歌曲可套用。不採用子字串或模糊相似度猜歌；Live、Cover、Remix、Acoustic、Part 2 等錄音或未知版本註記不會當成一般合作註記刪除。每首查詢至多三個歌手別名及兩個明列歌名，同時最多兩個 LRCLIB 請求；HTTP 429／5xx 會自動重試兩次（0.5、1.2 秒後）。單一別名失敗不會丟棄其他成功結果，且成功搜尋回傳的資料可匹配任一已驗證歌手別名。部分查詢失敗會在主畫面提示並保留可用歌詞；重試後仍全部失敗會直接顯示 HTTP／網路原因，不冒稱「沒有歌詞」。可按「重新偵測」再查，不會改用其他歌手。
• 特別剪輯提示：普通 YouTube 影片標題含 Special Clip、Medley、Mashup、메들리 等多首歌標記時，側欄顯示「特別剪輯」並說明沒有能對齊整支影片的單一歌詞，不自動查詢，改提供本機「建立字幕」入口；Making Video、Behind the scenes、Teaser、訪談等非完整歌曲影片則顯示「非完整歌曲」。
• YouTube 曲目資訊、標題比對與手動指定：普通 YouTube 單曲在 LRCLIB 精確比對失敗後，依序嘗試：(1) 讀取已載入 YouTube 頁面「音樂」區塊的曲名與歌手，只有唯一一首歌時採用，標示「YouTube 曲目資訊」；(2) 以去除節目雜訊的影片標題片段查 LRCLIB，要求標題同時出現曲名與同一筆紀錄的歌手之一，並套用片長容差，標示「標題比對」且顯示「不是這首」；Live、翻唱、混音標題不猜測。合輯、medley 與非完整歌曲不採用。(3) 仍無結果時可在「手動指定歌詞」自行指定 LRCLIB 歌曲或貼上 AI 回覆的歌名／歌手，標示「手動指定」；手動指定的優先順序高於所有自動比對，載入失敗時會提示並改用自動比對。Spotify、YouTube Music 的結構化曲目及合輯章節不進行上述解析，也不支援手動指定。
• 無歌詞影片建立字幕：只有已取得有效 YouTube /watch 來源、但沒有可用同步歌詞時，才顯示「載入辨識模型」、「建立字幕」及「重播字幕」。模型由使用者點擊才下載、啟動，正常同步歌詞跟唱不載入 Whisper。「建立字幕」須模型就緒且影片停在 0 秒、暫停、1× 才可按；連接成功後再播放，一路播至結束。畫面顯示實際收到的音訊秒數、已辨識窗口及字幕行數；首段須收滿 12 秒，再等待本機辨識，之後每 10 秒更新。靜音／低音量與沒有新增可用字幕會分別提示。啟動或辨識失敗後保留原因及重新準備入口，不自動重新錄製。
• 合輯二刷跟唱：只載入同一 mediaId 且片長完全相符的完整字幕快取；依播放、暫停與 seek 顯示文字。完成首遍後字幕保留在畫面，可直接從頭重播。未完成草稿不能二刷。建立與重播均鎖定指定來源分頁，切換前景分頁不停止；更換來源前先按「停止」。
• 五行跟唱視窗：單曲同步歌詞與合輯二刷字幕顯示目前位置及前後共五行，通常保留前兩行與後兩行；歌曲開頭、結尾會用其餘相鄰行補足。空白時間提示不計入五行，不足五行時顯示全部可用文字；原文與空耳屬於同一行歌詞。
• 歌詞校時：普通 YouTube 單曲取得同步歌詞後，主畫面可按「校時」：歌詞變成附時間的完整清單，聽到某句開始唱時點那一句即可自動算出偏移，也可用「歌詞提前／延後 0.5 秒」微調，「還原」回到進入前的值。設定的「校正歌詞時間」仍可手動輸入偏移（秒數或 m:ss，可為負值）。偏移只套用於該影片 ID 與該份歌詞內容，保存在本機 storage.local。前奏與間奏（LRCLIB 的空白行）會顯示「♪ 前奏／間奏 · N 秒後」倒數，下一句以點狀底線預告。
• 歌詞優先介面與顯示偏好：側欄採深茄紫「練歌房夜光」配色；頂部只留標誌、「重新偵測」、「停止」與狀態燈，歌詞區使用剩餘高度並可捲動。正在唱的那行以珊瑚粉螢光筆底線標示，尚未開唱的下一行用點狀底線，已唱過的行轉淡。「校正歌詞時間」、「顯示設定」、「手動指定歌詞」、「播放來源與說明」收在底部抽屜，同時只展開一個；來源與偏好儲存錯誤仍會直接顯示。原文與空耳相同時只顯示一行。空耳方式單選中文近音字或羅馬拼音（韓文採 Revised Romanization，日文採羅馬字）；原文保留語言可多選中文、英文、日文、韓文，也可全部不選。偏好儲存在 extension storage.local，變更後即時重算目前顯示，不重新執行 ASR。日文含假名的詞使用隨附的本機讀音字典處理漢字讀音與假名；純漢字段無法安全區分中日文，會保留原文。

隱私與限制

• 合輯擷取只使用使用者操作時鎖定的 YouTube 分頁 tabCapture，只擷取音訊並保留分頁原聲；不擷取畫面、桌面／系統混音。擴充功能圖示透過 chrome.action.onClicked 開啟側欄並取得目前分頁的 activeTab 授權；直接開側欄或只按側欄按鈕不等於授權其他分頁。指定其他來源時，須先切到該 YouTube 分頁點圖示，再建立字幕。沒有新增全網站或 tabs 權限。
• PCM 音訊只在本機 Worker 與 WebGPU Whisper 處理，不上傳。IndexedDB 只保存辨識文字與時間戳，不保存音訊樣本或空耳。
• 第一次合輯首播需要下載 Whisper 模型權重；LRCLIB 搜尋只傳歌曲名稱與歌手。Extension 需要網路取得模型與 LRCLIB 資料。
• YouTube 音樂區塊直接讀取已載入頁面的資料，不另外向 youtube.com 發出請求。
• 日文讀音使用隨擴充功能打包的 Kuromoji／IPADIC 離線字典，不會把歌詞傳到網路；字典檔及 Apache-2.0、IPADIC NOTICE、WanaKana MIT 授權文字一併發布。純漢字段不查字典。
• 歌曲只向 LRCLIB 查詢，不會把影片標題、頻道或音訊傳給任何 AI 服務；「複製 AI 提示詞」只是把文字放進剪貼簿，是否貼到哪個 AI 由你決定。升級時側欄會一次性刪除舊版留在 storage.local 的 Gemini API key。
• 合輯首遍中斷、seek、變速、換片、來源失聯、音軌中斷、ASR 佇列溢位或儲存失敗，都會將草稿標記為未完成。
• 需要桌面 Chrome／Edge 116+、WebGPU、AudioWorklet 與 extension 側欄。未提供 CPU 備援。
• YouTube 播放清單與 SPA 換片可能使目前網址不同於 Chrome 訊息的初始文件網址；播放報告驗證同一 HTTPS origin，並獨立檢查目前網址、影片 ID 與進度，不要求完整網址字串相等。
• 自動選版只比較歌曲資料與片長，不會自動偵測或校正 MV 片頭、剪輯、不同錄音版本造成的時間差；需要使用者手動記錄歌詞對齊點。片長接近不代表歌詞時間軸已驗證完全吻合。
• 音訊辨識及其快取都標示「音訊推測」；Whisper 可能誤認歌詞、口音或背景音樂，不是官方字幕。
• Extension 重載後，若目前支援的播放頁沒有訊息接收器，會以 scripting 在原分頁補載播放腳本；不刷新 YouTube，也不在其他網站注入。YouTube 的主頁面 chapter bridge 與隔離播放腳本分開載入，重複注入會清理舊 listener、timer。若使用者拒絕網站存取權限，仍須先允許擴充功能讀取該網站。

安裝與使用

1. 安裝依賴並建置 extension：

   pnpm install
   pnpm run lint:extension
   pnpm run build:extension
   

2. 在 Chrome 開啟 chrome://extensions，或在 Edge 開啟 edge://extensions，啟用開發人員模式並載入本專案的 browser-extension/ 目錄。 每次重新建置後，在擴充功能管理頁按「重新載入」，關閉再重開側欄即可；既有 YouTube 播放頁不必刷新。載入目錄仍是 browser-extension/，不是 extension-ui/ 或 browser-extension/app/。
3. 在 YouTube、YouTube Music 或 Spotify Web 播放歌曲，點擊 extension 圖示開啟側欄。
4. 側欄自動取得目前歌曲並比對同步歌詞；必要時可按小型「重新偵測」按鈕。展開「播放來源與說明」，在「播放分頁」選擇要固定的分頁；選「跟隨目前作用中的分頁」則恢復自動跟隨。「更新」可重列已開啟的播放分頁。這個來源選擇不寫入顯示偏好。該區也顯示平台、歌手、播放狀態及 LRCLIB 選版資訊。YouTube 沒有可信歌手時仍回報影片標題，但不猜測歌詞；沒有播放器、廣告中、網站權限不足或報告驗證失敗時會直接顯示來源診斷。 手動指定：自動比對找不到或找錯時，展開「手動指定歌詞」。按「到 LRCLIB 搜尋」會以影片標題的關鍵字開啟 lrclib.net 搜尋頁，挑好歌後把 https://lrclib.net/tracks/<編號> 連結貼回並按「套用」；或按「複製 AI 提示詞」貼到你自己的 AI，把它回覆的「歌名：…／歌手：…」兩行貼回，側欄會向 LRCLIB 驗證並選版。指定結果依 YouTube 影片 ID 記住，下次開同一支影片會優先套用；按「清除這支影片的指定」改回自動比對。
5. 若 YouTube 影片沒有可用同步歌詞，才會出現本機字幕選項：
   1. 在要擷取的 YouTube 分頁點擴充功能圖示，取得該分頁授權；若已指定另一個來源，先改選正確分頁。
   2. 按「載入辨識模型」，等待模型就緒。
   3. 把影片停在 0 秒、暫停、1×；準備提示會指出缺少哪個條件。
   4. 按「建立字幕」，先保持暫停；看到狀態「音訊已連接」後才按影片播放，不是先播放再建立。
   5. 首段至少需要 12 秒實際音訊＋本機辨識時間。依收音秒數及窗口進度判斷是否正常，不會立刻出字；靜音或沒有辨識結果會明確提示。
   6. 持續播放至結束，不暫停、seek、變速或換片；可以切換其他前景分頁，字幕仍跟隨鎖定來源。完成後字幕保留，可從頭重播；已有完整字幕時也可按「重播字幕」，不需載入模型。要更換來源，先按「停止」。
6. 展開「顯示設定」選擇空耳系統與原文保留語言；選項載入本機偏好前會暫時停用。若瀏覽器無法讀寫 extension storage，仍可變更當頁顯示，但會在收折區外提示偏好無法儲存。

開發驗證

pnpm test
pnpm run lint:extension
pnpm run build:extension

來源主要分層：browser-extension/ 負責播放報告驗證、側欄訊息轉送與 tabCapture 權限閘門；extension-ui/src/ 是側欄、LRCLIB、合輯 ASR 與文字快取原始碼，建置至 browser-extension/app/。youtube-music-credit.ts 負責從頁面資料中挑選單一音樂區塊曲目資訊；manual-lyrics.ts 負責手動指定的輸入解析、AI 提示詞與本機記憶格式；src/pronunciation/ 提供韓文與日文轉寫器。舊 Node／companion 的根目錄 dist/ 不再使用，也不會由 extension 建置產生。

上架打包

執行以下指令建置並打包商店發行檔：

pnpm run package:extension

打包完成後會產生 release/lyrics-everywhere-extension.zip，其根目錄即為包含 manifest.json 的擴充功能封裝檔，可直接上傳至 Chrome Web Store 或 Edge Add-ons。相關上架文字與商店權限聲明請參閱 docs/chrome-web-store.md。