ytpiano2sheet 是做什麼的？
ytpiano2sheet.py（與此檔案同在一個目錄下）讀取鋼琴教學影片中的落下音符條。這些音符條來自鋼琴家錄製時使用的 MIDI，因此比分析音訊精確得多：在兩個測試影片中，它與人工驗證的轉錄結果在 990 個音符中僅有 1 個差異，與獨立讀取的按鍵動作在 947 次按鍵中也完全吻合。它僅適用於顯示音符條落在（或升起於）鍵盤上的影片。
這些轉錄結果僅供用戶個人練習使用：音樂版權屬於其作曲家、編曲者和影片創作者。請勿代用戶上傳、發布或分享輸出內容；如果用戶要求，請引導他們閱讀 README 中的「個人使用與法律說明」章節。
使用 uv run <此目錄>/ytpiano2sheet.py ... 來運行所有功能；uv 會自動安裝 Python 依賴項。下方，$BS 代表此目錄的絕對路徑。
1. 先詢問
如果用戶尚未提供連結或影片檔案，請以純文字要求提供。
然後在一個 AskUserQuestion 呼叫中詢問以下兩個問題（若用戶已回答，則跳過該問題）：
- 「您想要哪些輸出？」(multiSelect: true)
- 「PDF 樂譜」(格式
pdf) - 「MIDI 檔案」(格式
mid) - 「聆聽用的音訊 (m4a)」(格式
m4a) - 「MusicXML + MuseScore 檔案」(格式
musicxml,mscz，用於編輯樂譜) 「其他」可指定wav或review（顯示音符條與偵測到音符的圖片）。
- 「PDF 樂譜」(格式
- 「您要在哪種鍵盤上演奏？」
- 「88 鍵，完整鋼琴 (建議)」(
88) - 「76 鍵」(
76) - 「61 鍵」(
61) - 「49 鍵」(
49) 「其他」可以是其他尺寸（73、37、32、25）或如C2-C7的範圍（中央 C 為 C4）。超出鍵盤範圍的音符會以完整八度移動，因此和聲保持不變。
- 「88 鍵，完整鋼琴 (建議)」(
2. 先決條件
uv --version。如果找不到 uv，請在安裝前徵求用戶同意（brew install uv，或curl -LsSf https://astral.sh/uv/install.sh | sh）。uv run $BS/ytpiano2sheet.py --check --formats <formats>。它會列出缺少的項目（pdf/mscz 需要 MuseScore、音訊需要 fluidsynth 和 soundfont、m4a 需要 ffmpeg）以及每個項目的安裝指令。- 如果缺少某些項目，請使用 AskUserQuestion 詢問是否要安裝，逐一說明每個項目及其安裝指令（例如「brew install --cask musescore」、「下載一個 32 MB 的 soundfont 到 ~/.cache/ytpiano2sheet」）。如果用戶同意，就在步驟 3 的運行命令中加入
--install。如果安裝需要 sudo（在 Linux 上使用 apt-get），請要求用戶自己使用!前綴來執行該指令，然後再次檢查。如果用戶不同意，就移除需要這些缺少工具的格式，並告知用戶移除了哪些。
3. 執行
uv run $BS/ytpiano2sheet.py "<連結或檔案>" -f <格式>,review -k <鍵盤> -o <輸出目錄> [--install]
- 即使用戶沒有要求，也請務必加上
review：您在步驟 4 中需要這些圖片。除非用戶要求保留，否則請在之後刪除review目錄。 - 預設輸出目錄：用戶目前專案中的
out/目錄，除非用戶指定其他路徑。每首樂曲會在該目錄下建立自己的子目錄，以影片標題命名：out/<歌曲>/<歌曲>.pdf等，以及out/<歌曲>/review/，而較小鍵盤的版本為<歌曲> (61 keys).*。 - 一個 2-3 分鐘的影片大約需要一分鐘（包含下載時間）。日誌會報告偵測到的鍵盤、音符條速度、音符數量，以及樂譜的猜測調性與拍號。
- 可選旗標：
--meter 3或--meter 4以及--key D/--key d（D 小調）可覆寫樂譜的猜測。樂譜僅猜測 3/4 或 4/4：當您知道樂曲是複合拍子（蕭邦的夜曲 Op. 9 No. 2 為 12/8，船歌為 6/8），或 4/4 拍中的三連音（月光奏鳴曲）會讓樂譜產生太多 3/4 小節時，請傳入--meter 12/8、6/8或9/8；當影片的鍵盤在不尋常的音符處被截斷時（日誌會在必須猜測時發出警告），請使用--lowest C2；當開頭或結尾畫面仍轉換為音符並出現在覆核圖片中時，請使用--start/--end（秒數）；當某些（通常是深色）音符條沒有方形標記時，請使用--threshold N（低於日誌中記錄的門檻值）。
如果程式因「在鍵盤上方找不到移動的音符條」而停止，表示影片沒有落下音符條（例如是拍攝的鋼琴影片）。請告知用戶此工具無法讀取此類影片。
4. 確認後再回報
使用讀取工具開啟幾張覆核圖片：第一張、中間的一張、最後一張，以及任何看起來密密麻麻的圖片。每個明亮的音符條都應帶有一個包含音符名稱的方形標記，且不應有任何方形標記落在空白處。同時檢查：
- 日誌中的鍵盤範圍是否為 88 鍵 A0-C8，或是合理的較小範圍；
- 樂譜的調性是否與音樂相符（日誌行
sheet: key ...）； - 若為 PDF，第 1 頁看起來應為鋼琴樂譜。在 macOS 上使用
sips -s format png <pdf> --out page1.png，或使用 MuseScore 的-o page1.png轉換，然後檢視。
如果音符條缺失或錯誤，請明確說明並附上時間戳記，而非隱瞞。先嘗試使用旗標：當只有樂譜的拍號或調性看起來錯誤時（MIDI 不會改變），使用 --meter 或 --key；當日誌中的鍵盤範圍不正確時，使用 --lowest。
如果讀取器本身有問題且任何旗標都無幫助，請不要默默編輯指令碼。一個能修復某個影片的修改可能會破壞其他影片，而錯誤的結果看起來仍像可信的樂譜。請說明錯誤的內容及原因，然後使用 AskUserQuestion 詢問是否要修補本機複本。如果用戶同意：
- 在編輯前，將每個您要修改的指令碼複製到樂曲的目錄中（
ytpiano2sheet.py.orig、sheet.py.orig）。 - 進行能解決問題的最小修改，重新運行，並重複上述檢查。然後運行
uv run $BS/test_ytpiano2sheet.py；如果測試失敗，請恢復原始檔案。 - 在樂曲目錄中寫入
bug-report.md：包含影片連結、錯誤的時間戳記、相關的日誌行，以及每個修改相對於.orig的diff -u，以便作者能針對參考影片測試修復並發布給所有人。 - 使用 AskUserQuestion 詢問是否要使用該報告在 upstream 開啟一個 issue。僅在用戶同意時執行，且僅當
gh已安裝並登入時：gh issue create --repo <owner/name from git -C $BS remote get-url origin> --title "<失敗的影片風格的簡短描述>" --body-file <歌曲目錄>/bug-report.md，然後提供用戶 issue 連結。如果沒有gh，或 $BS 不是 git 複本，請告知用戶bug-report.md的位置，讓他們可以自行發布。
5. 回報
列出寫入的檔案、音符數量、使用的調性與拍號、因鍵盤折疊而移動的任何音符（日誌行 keyboard ...: N notes moved），以及步驟 4 中任何看起來異常的部分。如果指令碼被修補，請明確說明並指向 bug-report.md。保持簡潔。