UkePack AI

把一首歌變成小朋友也能練的烏克麗麗練習包——從 MusicXML 匯入到 PDF，< 5 秒出稿。

UkePack AI 讀取 MusicXML（或手動和弦），自動簡化和弦、推薦調性、分級難度、配對刷法，輸出含和弦圖、刷法說明、段落地圖的 A4 練習 PDF。老師可在審稿模式校稿後再交給學生練習。

快速開始

需求：Python 3.12+、uv、ffmpeg（practice audio 需要）

# 安裝
git clone https://github.com/Reese-max/UkePack.git
cd UkePack
uv sync --extra dev

# 啟動 Web Server
uv run uvicorn app.main:app --reload
# 瀏覽器打開 http://localhost:8000

# Windows PowerShell：CLI 產 PDF（北極星驗證）
uv run python -m app.demo --input samples\public_domain\twinkle.musicxml --level 1 --out $env:TEMP\demo.pdf

# Windows PowerShell：產老師試用包（PDF + teacher docs + outreach templates + score）
uv run python -m app.demo --input samples\public_domain\twinkle.musicxml --level 1 --out $env:TEMP\trial.pdf --trial-packet $env:TEMP\teacher-trial.zip

# Windows PowerShell：Discord bot（需設 DISCORD_BOT_TOKEN）
uv run python -m app.discord_bot

# macOS / Linux：CLI 產 PDF（北極星驗證）
uv run python -m app.demo \
  --input samples/public_domain/twinkle.musicxml \
  --level 1 \
  --out /tmp/demo.pdf

# macOS / Linux：產老師試用包（PDF + teacher docs + outreach templates + score）
uv run python -m app.demo \
  --input samples/public_domain/twinkle.musicxml \
  --level 1 \
  --out /tmp/trial.pdf \
  --trial-packet /tmp/teacher-trial.zip

# macOS / Linux：Discord bot（需設 DISCORD_BOT_TOKEN）
uv run python -m app.discord_bot

要把試用包寄給外部老師時，記得加 --host-url https://<your-host>/new，而且要用完整 http:// 或 https:// 網址。不加時 ZIP 內 README 會標示 localhost 只限同機器使用；新版 ZIP 也會附上可直接 copy-paste 的邀請 / 排程 / 提醒 / 追蹤模板，且 teacher_guide.md / teacher_trial_sop.md 內的外寄網址示意會一起代成實際 host URL。本文與 repo 內原始 teacher docs 則維持 https://<your-host> 佔位，避免把 localhost 誤寄出去。

Beta 老師招募

UkePack 正在徵求烏克麗麗老師協助 15 分鐘 Beta 試用。目標是確認一首歌從匯入到產出可練 PDF、老師審稿、分享給學生的流程，是否能降低第一堂課準備時間。

老師試用包用途：一次附上 PDF 練習包、老師操作手冊、K7 onboarding checklist、回饋問卷、邀請 / 排程 / 提醒 / 追蹤範本，以及測試用 MusicXML。產包時請使用可公開開啟的 trial URL，不要把 localhost 連結寄給外部老師。

# Windows PowerShell：產外寄用老師試用包
uv run python -m app.demo --input samples\public_domain\twinkle.musicxml --level 1 --out $env:TEMP\trial.pdf --trial-packet $env:TEMP\teacher-trial.zip --host-url https://<your-host>/new

# macOS / Linux：產外寄用老師試用包
uv run python -m app.demo \
  --input samples/public_domain/twinkle.musicxml \
  --level 1 \
  --out /tmp/trial.pdf \
  --trial-packet /tmp/teacher-trial.zip \
  --host-url https://<your-host>/new

試用前請先檢查 docs/teacher/checklist.md，試用後把老師回饋整理到 feedback.md。邀請與追蹤文字可直接從 docs/teacher/templates/ 取用。

📦 Publish 準備

Repo 已公開：https://github.com/Reese-max/UkePack

完整前置清單見 docs/publish_ready_checklist.md。

# Git remote（已完成）
git remote add origin https://github.com/Reese-max/UkePack.git
git push -u origin master

下一步讓老師可以用：

點下方按鈕一鍵部署到 Render.com（已有 render.yaml 零設定），取得公開 URL

詳細選項見 docs/deployment_guide.md（亦支援 Fly.io / Railway）。
用 app.demo --trial-packet --host-url <公開網址>/new 產老師試用包
從 docs/teacher/templates/ 寄邀請信
跑完後把回饋填到 feedback.md

功能一覽

功能	說明
MusicXML / .mxl 匯入	music21 解析，自動取 Key / BPM / 時間拍號 / 和弦 / 旋律
和弦簡化	20+ 規則把 `Cmaj7`、`F#m7b5` 等降到烏克麗麗初學者可彈的和弦
調性建議	評分算法推薦 GCEA 友善 key（C / G / F / Am 優先）
難度分級 / 可彈性分數	6 因子加權（和弦數、BPM、換和弦頻率…）→ Level 1 / 2 / 3，分析頁顯示因子條、需學和弦數、最高把位
刷法配對	5 種刷法（入門單刷 / 華爾滋 / 慢搖 / 輕快刷法 / 常見流行刷法）依難度建議
段落偵測	Intro / Verse / Chorus 自動辨識（支援手動 header）
PDF 輸出	4 頁 A4：練習總覽、刷法說明、段落地圖、老師備註；含授權聲明
慢速練習音檔	先透過 API 上傳 MIDI，再產 50 BPM / 70% / 100% 三種 MIDI+MP3 variant，含 1 小節 count-in
老師審稿模式	修改和弦 / 刷法 / 練習說明；比較 / 復原；儲存並套用模板
Discord bot	`/ukepack` 上傳 MusicXML，直接回傳 PDF 練習包
Web UI	HTMX 表單，兒童友善大字體（18px / 52px 按鈕）
REST API	FastAPI，自動生成 `/docs` Swagger UI

Web API 快速參考

POST   /api/projects                     建立專案
POST   /api/projects/{id}/import         上傳 MusicXML（≤ 10MB）
POST   /api/projects/{id}/midi           上傳 MIDI
POST   /api/projects/{id}/chords         手動輸入和弦
GET    /api/projects/{id}/analysis       取分析結果（Key / BPM / 難度 / 段落）
POST   /api/projects/{id}/arrange        指定 Level 重新排版
GET    /api/projects/{id}/export.pdf     下載 PDF 練習包
GET    /api/projects/{id}/export.musicxml 下載編輯版 MusicXML
POST   /api/projects/{id}/practice-audio 產慢速練習音檔
GET    /api/projects/{id}/export.practice-audio/{variant}.{format} 下載音檔
POST   /api/projects/{id}/share-link     建立或輪替私人分享連結
DELETE /api/projects/{id}/share-link     撤銷私人分享連結
GET    /share/{code}                     開啟短碼分享頁

完整 API 規格見 openspec/specs/projects-api.md。啟動後也可訪問 http://localhost:8000/docs 取得 interactive Swagger UI。

目前 Web UI 主流程：建立專案、匯入 MusicXML、手動輸入和弦、PDF 預覽/分享都可直接在頁面完成。
MIDI 上傳目前走 API POST /api/projects/{id}/midi，主要用於後續產生練習音檔。

安裝詳細步驟

步驟 1：Clone

git clone https://github.com/Reese-max/UkePack.git
cd UkePack

步驟 2：安裝 Python 依賴

uv sync --extra dev

步驟 3：複製環境設定（可選，預設值可直接啟動）

# Windows PowerShell
Copy-Item .env.example .env

# macOS / Linux
cp .env.example .env

步驟 4：啟動 Web Server

# Windows PowerShell
uv run uvicorn app.main:app --reload
# 瀏覽器打開 http://localhost:8000

# macOS / Linux
uv run uvicorn app.main:app --reload
# 瀏覽器打開 http://localhost:8000

步驟 5：健康檢查（另開終端視窗，確認 server 已啟動）

# Windows PowerShell
Invoke-RestMethod http://localhost:8000/health

# macOS / Linux
curl http://localhost:8000/health

步驟 6：跑測試確認環境正確

uv run pytest -q

Git 不會隨 clone 安裝本機 .git/hooks/pre-commit，乾淨 checkout 會略過 daemon hook 存在檢查。需要強制守門的開發機可設定 UKEPACK_ENFORCE_DAEMON_HOOK=1；此時未安裝 hook 會使測試失敗，CI 也適用。

ffmpeg（practice audio MP3 轉檔）：Windows 可用 winget install Gyan.FFmpeg，macOS 用 brew install ffmpeg，Ubuntu / Debian 用 apt install ffmpeg，或直接下載 Windows 版。若 ffmpeg 不在 PATH，.mid 仍可產出，.mp3 會跳過而不報錯。

Discord bot：在 .env 設 DISCORD_BOT_TOKEN；可選 DISCORD_BOT_GUILD_ID 做 guild-scoped slash-command sync。啟動後用 /ukepack score_file:<attachment> source_type:public_domain confirm_license:true level:1 產 PDF。

目前狀態

北極星指標

一首歌從匯入到小朋友能彈出第一段，所需時間少於 30 分鐘。

機器端守門：import → PDF < 5 秒（在 twinkle / happy_birthday / jingle_bells 三首 fixture 自動回歸）。

文件

文件	說明
PRD.md	完整產品需求文件 v1.0
BACKLOG.md	任務清單（依 Phase 排列）
docs/teacher_guide.md	老師操作手冊（建立專案 → 審稿 → 分享，30 分鐘上手）
docs/teacher/checklist.md	K7 onboarding 5/5 驗收表（Windows setup / MIDI workflow / web UI / feedback / 中文 invite）
docs/teacher/polaris_measurement.md	北極星人類體感量測模板（試用當下填 timestamp，驗算「從匯入到學生試彈 < 30 分鐘」）
docs/teacher/templates/	試用邀請 / 排程確認 / 前一天提醒 / 24 小時追蹤範本（ZIP 也會附上）
openspec/specs/	各模組 API / 行為規格（15 份）
docs/teacher_trial_sop.md	老師試用 SOP（15 分鐘流程、邀請信、驗收清單）
docs/deployment_guide.md	雲端部署指南（Render.com / Fly.io / Railway，5 分鐘讓 app 上線供老師試用）
docs/publish_ready_checklist.md	Publish 準備驗收清單（公開 repo 前的所有前置條件）
feedback.md	老師試用回饋問卷
engineering-log.md	技術決策 + 重大 incident 記錄

貢獻

工程規範見 AGENTS.md：技術棧、目錄結構、程式風格、測試門檻、commit 格式皆在其中。

Name		Name	Last commit message	Last commit date
.github		.github
.serena		.serena
.tmp-run		.tmp-run
.tool-cache		.tool-cache
app		app
baseline-temp		baseline-temp
docs		docs
openspec		openspec
samples/public_domain		samples/public_domain
scripts		scripts
tests		tests
.auto-dev.env		.auto-dev.env
.env.example		.env.example
.gitignore		.gitignore
.harness-chore-ratio.json		.harness-chore-ratio.json
.issue-loop-evidence.json		.issue-loop-evidence.json
.issue-loop-review.json		.issue-loop-review.json
.kpi-gate-streak.lock		.kpi-gate-streak.lock
.spectra.yaml		.spectra.yaml
AGENTS.md		AGENTS.md
BACKLOG.md		BACKLOG.md
LICENSE		LICENSE
MISSION.md		MISSION.md
PRD.md		PRD.md
README.md		README.md
dogfood.sh		dogfood.sh
engineering-log.archive.md		engineering-log.archive.md
engineering-log.md		engineering-log.md
feedback.md		feedback.md
program.md		program.md
pyproject.toml		pyproject.toml
render.yaml		render.yaml
uv.lock		uv.lock
uv.toml		uv.toml

Navigation Menu

Repository navigation

About

Repository files navigation

UkePack AI

快速開始

Beta 老師招募

📦 Publish 準備

功能一覽

Web API 快速參考

安裝詳細步驟

目前狀態

北極星指標

文件

貢獻

授權

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

UkePack AI

快速開始

Beta 老師招募

📦 Publish 準備

功能一覽

Web API 快速參考

安裝詳細步驟

目前狀態

北極星指標

文件

貢獻

授權

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages