練琴練習小幫手

給弦樂學習者的平板練習工具。節拍器、調音器、計時器、樂譜檢視與練習紀錄整合在一個可離線使用的網頁 App 裡，不需要帳號、不需要伺服器，所有資料都留在自己的裝置上。

線上版本：https://violinassistant.vercel.app

建議以平板直式使用 —— 版面是以譜架上的平板為前提設計的。

功能

練習工具

• 節拍器 — 可設拍號、細分拍（八分／三連音／十六分）、速度漸進模式，以及「靜音小節」（響 N 小節後刻意停 M 小節，訓練自己維持速度）
• 調音器 — 即時音高偵測，顯示與標準音的音分偏差
• 計時器 — 倒數練習時間，結束後記錄練習時數與筆記，可指定這次練的是哪一首

樂譜

• 上傳樂譜照片，支援多頁、資料夾分類與標籤搜尋
• 畫筆標註、旋轉、裁切（逐頁設定）
• 智能翻頁 — 用鏡頭偵測臉部動作翻頁，手不用離開琴
• 段落循環練習 — 框出難的那幾小節，練習時只亮出那一塊，並記錄練了幾遍、最快練到多少 BPM
• 速度進展圖 — 看得出「幾天內從多少練到多少」

錄影與音準分析

• 錄下自己的練習，可分割畫面與示範影片對照
• 影片慢速播放（0.25x–1.5x，保留原音高）
• 音準回放分析 — 把錄影期間偵測到的音高畫成曲線，列出最需要注意的片段，點擊直接跳到影片該秒

紀錄與習慣

• 練習歷程圖表、每日／每週目標
• 集點卡與徽章（每 30 分鐘練習 = 1 個音符）
• 備份匯出／匯入

技術

純前端 PWA，沒有後端也沒有資料庫。

• React 18 + TypeScript + Vite + Tailwind CSS 4
• 資料存在瀏覽器的 IndexedDB（透過 idb-keyval）
• 音高偵測用自相關法（src/lib/pitch.ts）
• 智能翻頁用 MediaPipe FaceLandmarker
• vite-plugin-pwa 提供離線能力與安裝到主畫面

沒有使用任何 AI 服務或外部 API。這個專案最初是從 Google AI Studio 的模板建立的，但程式碼裡從來沒有呼叫過 Gemini 或其他任何服務 —— 如果你在舊版 README 看到 GEMINI_API_KEY 的設定說明，那是模板殘留，可以忽略。

開發

需要 Node.js 20 以上。

npm install
npm run dev

常用指令：

指令	用途
npm run dev	開發伺服器
npm run build	正式建置
npm run check	型別檢查 + ESLint + 單元測試（數秒）
npm run check:all	再加上 Playwright E2E（約 2 分鐘，會自己 build + preview）
npm run test:e2e:ui	以 UI 模式跑 E2E

送出修改前請先跑 npm run check。

專案慣例

• 純計算邏輯放在 src/lib/*.ts 並附單元測試，元件只負責畫面與事件。這個專案吃過的虧就是邏輯埋在 useEffect 裡沒有任何方式驗證。
• 版面與互動問題要把 App 跑起來實際量測，不要只看 JSX 推論。最嚴重的幾個歷史缺陷（平板版面被切掉、觸控裝置看不到按鈕）都是靜態分析抓不到的。
• 版本號有三處要同步：package.json、src/App.tsx 的頁尾、src/components/UserGuide.tsx 的更新日誌。

更完整的背景、資料模型與開發歷程見 開發歷程與交接紀錄.md。

隱私

所有樂譜、錄影與練習紀錄都只存在你自己的瀏覽器裡，不會上傳到任何地方。錄影與調音功能需要攝影機／麥克風權限，影像與聲音只在裝置本機處理。

唯一的對外連線是智能翻頁功能所需的 MediaPipe 模型檔（從 CDN 載入），其他功能離線皆可使用。

備份檔例外：「下載備份」會把樂譜照片與完整練習紀錄打包成一個檔案。那個檔案一旦分享出去或存到雲端，就離開了這台裝置 —— 分享前請確認對象與位置。