🎵 Melo: nghe nhạc kiểu Spotify trên iPhone
Tìm và nghe YouTube Music với giao diện kiểu Spotify. Tắt màn hình vẫn phát, tự chuyển bài, tải về nghe offline. Chạy hoàn toàn trên iPhone, không cần server.
✨ Tính năng
Nghe nhạc 🎧
- Tìm kiếm có gợi ý khi gõ. Dán link bài, playlist hoặc album YouTube vào ô tìm kiếm để mở thẳng.
- Phát nền thật: tắt màn hình vẫn phát và tự chuyển bài. Điều khiển được từ màn hình khoá và tai nghe.
- Hàng chờ kiểu Spotify: Phát tiếp, Thêm vào hàng chờ, kéo thả để đổi thứ tự, trộn bài, lặp lại.
- Trộn thông minh (như Smart Shuffle của Spotify Premium): bấm nút trộn lần nữa, Melo chèn bài gợi ý ✨ hợp gu xen giữa danh sách. Tắt trộn thì các bài gợi ý tự biến mất.
- Radio tự động: sắp hết hàng chờ thì app tự nối thêm bài tương tự.
- Dành cho bạn (kiểu Spotify): Daily Mix theo các nghệ sĩ bạn hay nghe, Khám phá hằng tuần (bài chưa nghe, đổi mỗi thứ Hai), Nghe lại, Nhạc buổi sáng/tối của bạn. Tính ngay trên máy từ lịch sử nghe, không gửi đi đâu.
- Lời bài hát chạy theo nhạc (LRCLIB). Có hẹn giờ tắt.
Tải về & offline ⬇️
- Tải song song tự điều chỉnh, tối đa 15 bài cùng lúc. App tăng dần số bài tải cho tới khi băng thông hết tăng. YouTube chặn thì tự giảm và nghỉ một lúc. Trên 4G/5G tối đa 6 bài.
- Khi mất mạng app chỉ phát các bài đã tải.
- Thích một bài là tự tải về (bật trong Cài đặt).
- Nhạc lưu trong thư mục của app, không đồng bộ lên iCloud, và vẫn còn khi cài bản mới.
Đăng nhập Gmail: đồng bộ YouTube 🔑
- Đăng nhập bằng Gmail chỉ bằng một mã ngắn, nhập ở google.com/device. Melo không thấy mật khẩu của bạn.
- Playlist của bạn (cả playlist tạo trên YouTube Music) và bài đã thích hiện trong Thư viện với nhãn Từ YouTube. Phát và tải được ngay, tự đồng bộ khi mở app.
- Melo chỉ đọc thư viện, không sửa gì trên YouTube. Hướng dẫn: docs/GOOGLE.md.
Đồng bộ Spotify 🔄
- Kết nối Spotify một lần, có thể đăng nhập bằng Google trên trang của Spotify. Playlist của bạn và Bài hát đã thích hiện trong Thư viện với nhãn Từ Spotify.
- Melo tự tìm từng bài trên YouTube Music: so tên bài, nghệ sĩ và thời lượng, không ghép nhầm bản cover.
- Tự đồng bộ khi mở app. Playlist không đổi thì bỏ qua.
- Không có Premium: nhập từ file dữ liệu Spotify. Hướng dẫn: docs/SPOTIFY.md.
Bản web 🌐
- Không cần SideStore: mở link bằng Safari → Thêm vào MH chính. Đưa lên Vercel một lần, mỗi lần đẩy code thì tự cập nhật.
- Nhạc từ Audius (nghệ sĩ tự đăng, bài mới mỗi ngày, không cần đăng ký), Jamendo (kho Creative Commons, tuỳ chọn) và file nhạc của bạn (MP3/M4A trong app Tệp, iCloud Drive; tự đọc tên bài và ảnh bìa trong file).
- Trang chủ có Thịnh hành tuần này, Mới phát hành, nghệ sĩ đang nổi, playlist và các thể loại.
- Mở app và nghe nhạc đã tải khi không có mạng. Màn hình khoá hiện tên bài và nút chuyển bài.
- Không có YouTube Music (nên không có các bài hit của hãng đĩa lớn): trình duyệt không gọi thẳng YouTube được, và Melo không dùng server. Hướng dẫn: docs/WEB.md.
Thư viện 📚
- Bài hát đã thích, playlist tự tạo, lịch sử nghe, lịch sử tìm kiếm.
- Vuốt từ mép trái để quay lại trang trước, giống app iOS gốc.
📸 Ảnh màn hình
| Trang chủ | Tìm kiếm | Album |
|---|
| | |
| Chọn nhanh, playlist, album mới, nghệ sĩ. | Lọc theo bài hát, video, album, nghệ sĩ. | Tải cả album bằng 1 nút ⬇. |
| Trình phát | Lời bài hát | Hàng chờ |
|---|
| | |
| Màu nền theo ảnh bìa, vuốt xuống để đóng. | Lời chạy theo nhạc, chạm một dòng để tua. | Kéo thả đổi thứ tự, bật/tắt radio. |
| Thư viện | Đang tải | Cài đặt tải về |
|---|
| | |
| Bài đã thích, đã tải, playlist của bạn. | Tải nhiều bài cùng lúc, hiện tốc độ. | Tự động hoặc cố định 1–15 bài. |
Ảnh chụp ở chế độ dữ liệu mẫu (npm run dev:mock), khổ iPhone 390×844. Ảnh bìa là tranh SVG tự vẽ theo tên bài (src/youtube/mock/covers.ts), không phải ảnh bìa thật; khi dùng thật, app hiện ảnh bìa từ YouTube Music.
📲 Cài lên iPhone
Apple chỉ cho cài app đã được ký. Melo không có trên App Store (lý do), nên có 2 cách:
| 🆓 Cách 1: SideStore (khuyên dùng) | 💳 Cách 2: Cài 1 chạm (Ad Hoc) |
|---|
| Chi phí | 0 đ | Apple Developer 99 USD/năm |
| Máy tính | Cần 1 lần, khoảng 15 phút | Cần 1 lần (lấy UDID, tạo chứng chỉ) |
| Cập nhật | Bấm UPDATE trong SideStore | Mở trang cài đặt, bấm Cài đặt Melo |
| Gia hạn | 7 ngày, tự gia hạn trên iPhone | 1 năm |
flowchart LR
PC["💻 PC Windows<br/>iTunes + iloader"] -->|"cài SideStore<br/>(chỉ 1 lần)"| IP["📱 iPhone<br/>Tin cậy + Chế độ<br/>nhà phát triển"]
IP --> SS["🧩 SideStore<br/>+ source Melo"]
SS -->|"GET / UPDATE"| M["🎵 Melo"]
SC["⏰ Phím tắt<br/>3:00 hằng ngày"] -.->|"tự gia hạn 7 ngày"| SS
🆓 Cách 1: SideStore (miễn phí)
Chuẩn bị:
- PC Windows 64-bit;
- cáp USB;
- iPhone dùng Wi‑Fi, đã cài app LocalDevVPN từ App Store.
Bước 1: Trên máy tính (chỉ làm 1 lần)
Bước 2: Kích hoạt trên iPhone
Bước 3: Cài Melo bằng SideStore
Link source để dán vào SideStore (Sources → +):
https://github.com/HoangDuc1003/music_melo/releases/download/ios-latest/source.json
Bước 4: Tự gia hạn 7 ngày (khuyên làm)
Xong! Từ giờ:
- có bản mới thì mở SideStore bấm UPDATE;
- nhạc đã tải và thư viện vẫn còn sau khi cập nhật.
| Hiện tượng | Cách xử lý |
|---|
| iloader không thấy iPhone | Cài iTunes bản tải từ Apple, không dùng bản Microsoft Store. Vẫn không được thì thử app Apple Devices. Cắm lại cáp, bấm Tin cậy. |
| Mở app báo "Nhà phát triển không được tin cậy" | Làm lại bước 2, mục Tin cậy. |
| SideStore báo lỗi khi cài, cập nhật hoặc gia hạn | Mở LocalDevVPN, bấm Connect, dùng Wi‑Fi rồi thử lại. |
| Melo không mở được sau 7 ngày | Mở SideStore, bấm 7 DAYS cạnh Melo. Nhạc đã tải không mất. |
| Báo đã đủ số app | Apple ID miễn phí cho tối đa 3 app tự cài, tính cả SideStore. Gỡ bớt một app. |
| Melo lỗi khi đang dùng | Trong Melo: Cài đặt → Nhật ký lỗi → Copy, rồi gửi cho người sửa app. Nhật ký đã tự ẩn IP, link và token. |
💳 Cách 2: Cài 1 chạm, không cần app thứ ba (Ad Hoc)
Sau khi thiết lập một lần, mỗi lần cài hay cập nhật chỉ cần:
- Mở https://hoangduc1003.github.io/music_melo/ bằng Safari.
- Bấm Cài đặt Melo, rồi bấm Cài đặt.
- Ra màn hình chính chờ app tải xong.
Không cần SideStore, không cần VPN, không phải gia hạn 7 ngày. Hồ sơ dùng được 1 năm.
Thiết lập một lần:
- tài khoản Apple Developer (99 USD/năm);
- đăng ký UDID của iPhone;
- tạo chứng chỉ và hồ sơ Ad Hoc;
- dán vào 3 GitHub Secrets.
CI sẽ tự ký và đăng trang cài đặt. Hướng dẫn từng lệnh (làm được trên Windows): docs/CAI_DAT.md.
⚙️ Cách hoạt động
iOS tạm dừng JavaScript khi app chạy nền. Vì vậy hàng chờ và việc phát nhạc nằm trong plugin Swift (AVPlayer); phần JavaScript chỉ lo những việc cần mạng.
sequenceDiagram
participant U as 👤 Bạn
participant UI as 💻 Giao diện (React)
participant C as 🎛️ controller.ts
participant N as 🍎 MeloPlayer (Swift)
participant YT as ▶️ YouTube Music
U->>UI: Bấm phát album
UI->>C: playTracks()
C->>N: setQueue (cả hàng chờ, bài đã tải dùng file)
C->>YT: Lấy link 20 bài tới (youtubei.js, bằng IP của iPhone)
C->>N: updateItem(link)
Note over N: Khoá màn hình: AVPlayer tự chuyển bài,<br/>điều khiển trên màn hình khoá
N-->>C: needsUrl (link hết hạn hoặc lỗi)
C->>YT: Lấy link mới
C->>N: updateItem(link mới)
C->>YT: Còn ≤ 3 bài: lấy radio, nối vào hàng chờ
📂 Cấu trúc dự án
music_melo/
├── src/ # Giao diện + logic (React, TypeScript)
│ ├── pages/ # Trang chủ, Tìm kiếm, Thư viện, Album, Nghệ sĩ, Đã tải, Cài đặt
│ ├── components/ # Trình phát mini/toàn màn hình, hàng chờ, lời bài hát, menu bài
│ ├── player/ # Bộ điều khiển: hàng chờ, lấy link trước, radio, lưu/khôi phục
│ ├── downloads/ # Tải về: hàng đợi, tải song song tự điều chỉnh, lưu file
│ ├── sync/ # Đồng bộ Spotify: đăng nhập PKCE, Web API, ghép bài sang YouTube Music
│ ├── youtube/ # youtubei.js, BotGuard, chọn client, dữ liệu mẫu (mock/)
│ ├── lib/ # IndexedDB (Dexie), thư viện, lời bài hát, nhật ký lỗi
│ └── ui/ # Điều hướng theo tab, lớp phủ, thông báo
├── plugins/player/ # Plugin Swift "MeloPlayer": AVPlayer, hàng chờ native, màn hình khoá
│ └── ios/Tests/ # XCTest cho hàng chờ native
├── ios/App/ # Dự án Xcode (Capacitor), PrivacyInfo.xcprivacy
├── scripts/ # Ký Ad Hoc, tạo source SideStore, kiểm tra giao diện, chụp ảnh README
├── docs/ # Kế hoạch, hướng dẫn cài, App Store, chính sách quyền riêng tư, ảnh
└── .github/workflows/ios.yml # CI: quét bí mật → test → build IPA → Release → trang cài đặt
🛠️ Công nghệ
| Phần | Công nghệ |
|---|
| Giao diện | React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, TanStack Query |
| App iPhone | Capacitor 8, plugin Swift tự viết (AVPlayer, MediaPlayer, AVAudioSession) |
| Nguồn nhạc | youtubei.js (InnerTube), BotGuard / PO token (bgutils-js) |
| Đồng bộ Spotify | Spotify Web API, OAuth PKCE (không client secret), token trong Keychain, ghép bài sang YouTube Music |
| Lưu trên máy | IndexedDB (Dexie), file nhạc trong Library/NoCloud, File Transfer |
| Lời bài hát | LRCLIB, dự phòng bằng lời trên YouTube |
| Kiểm thử | Vitest (85 test), XCTest (15 test), Playwright (9 luồng giao diện) |
| CI/CD | GitHub Actions trên macOS: gitleaks, npm audit, build IPA, giới hạn dung lượng JS, Release, Pages |
| Phát hành | GitHub Releases + source SideStore/AltStore, trang cài Ad Hoc trên GitHub Pages |
🚀 Chạy trên máy tính (cho người phát triển)
git clone https://github.com/HoangDuc1003/music_melo.git
cd music_melo
npm install
npm run dev:mock # dữ liệu mẫu, không cần YouTube: http://localhost:5173
npm run dev # dữ liệu thật qua proxy của Vite
npm test # vitest
npm run build # kiểm tra kiểu + build
cd plugins/player && swift test # test hàng chờ native (macOS/Linux)
- Không có Mac vẫn build được: mỗi lần push, GitHub Actions build
Melo.ipa và đăng lên Releases.
- Muốn mở bản dev từ iPhone cùng Wi‑Fi:
MELO_LAN=1 npm run dev. Lưu ý lệnh này mở cả proxy dev ra mạng LAN.
- Chụp lại ảnh cho README:
scripts/readme-shots.mjs và scripts/install-illustrations.mjs.
🔒 Quyền riêng tư & bảo mật
- Không server, không thu thập dữ liệu, không quảng cáo, không theo dõi. Thư viện, lịch sử và nhạc đã tải chỉ nằm trên iPhone.
- App có Content-Security-Policy. Chỉ phát link
https hoặc file trong máy.
- Nhật ký lỗi tự ẩn IP, link nhạc và token.
- Repo public nên CI quét bí mật (gitleaks) trên toàn bộ lịch sử git. Chứng chỉ ký chỉ nằm trong GitHub Secrets.
- Chi tiết: chính sách quyền riêng tư.
⚠️ Lưu ý
Dự án dùng cho cá nhân, không phát hành lên App Store và không chia sẻ file IPA cho người khác. Nội dung nhạc thuộc YouTube và chủ sở hữu quyền. Vì sao không thể lên App Store và cách làm một phiên bản hợp lệ: docs/APP_STORE.md.
👨💻 Tác giả
Nguyễn Đức Hoàng
Nếu thấy dự án hữu ích, hãy cho một ⭐ nhé!
