KietStation (Mood-based-Recommender)

title	KietStation - Mood-Based AI Recommender & Streaming Platform
short_description	AI Music Studio, Stream, Watch Party & Mood Detection
sdk	docker
app_port	7860

KietStation (Mood-based-Recommender)

KietStation là ứng dụng giải trí chạy trên trình duyệt. Camera nhận diện cảm xúc trên khuôn mặt, rồi app gợi ý nhạc và phim hợp với tâm trạng. Ngoài ra có rạp chiếu chung nhiều người, studio tạo nhạc bằng AI, phòng học tập trung, DJ Radio và Photo Booth tách nền.

Bản chạy online: https://huggingface.co/spaces/kietvohcb/MoodBasedRecommender
Mã nguồn: https://github.com/giakietkevin/Mood-based-Recommender

App chạy được trên máy tính, điện thoại (cài như ứng dụng PWA), TV (Samsung Tizen, LG webOS, Android TV) và có bản cài đặt Windows riêng.

1. Tính năng

Khu vực	Mô tả ngắn
Tâm trạng	Quét khuôn mặt qua webcam, nhận diện cảm xúc và phát playlist phù hợp. Có thống kê tâm trạng theo tuần.
Phim	Tìm và xem phim (luồng HLS), có trợ lý AI tư vấn phim.
Rạp	Phòng chiếu chung theo thời gian thực: chọn ghế, xem đồng bộ, chat, xem sảnh 3D.
Khám phá	Tìm nhạc, video, podcast và xem bài đang thịnh hành.
Thư viện	Bài yêu thích, playlist cá nhân, playlist công khai, lịch sử nghe.
Phòng học	Chế độ tập trung với hẹn giờ, phòng học chung qua WebRTC.
DJ Radio	Đài phát nhạc liên tục theo tâm trạng, có giọng DJ đọc lời dẫn.
Studio	Tạo beat từ mô tả, ghép lời và giọng hát ảo thành bài hoàn chỉnh.
Photo Booth	Chụp ảnh, tách nền bằng AI, thay phông ảo ngay trên trình duyệt.

2. Hướng dẫn sử dụng

2.1 Điều hướng

Máy tính (màn hình từ 1280px): thanh điều hướng nằm ở giữa phía trên. Các mục ít dùng (DJ Radio, Photo Booth) nằm trong nút Thêm.
Điện thoại và máy tính bảng: thanh điều hướng nằm ở cạnh dưới màn hình với 5 mục: Tâm trạng, Phim, Rạp, Thư viện, Thêm. Bấm Thêm để mở danh sách các mục còn lại: Khám phá, Phòng học, DJ Radio, Photo Booth, Game, Giới thiệu, Hồ sơ cá nhân.
Đổi ngôn ngữ: bấm nút VI / EN ở góc trên bên phải.

2.2 Đăng nhập

Bấm Đăng nhập để tạo tài khoản bằng email và mật khẩu. Tài khoản cần để lưu bài yêu thích, playlist, lịch sử và hồ sơ.
Muốn dùng thử thì bấm dấu X trên hộp đăng nhập để vào chế độ khách. Chế độ khách vẫn nghe nhạc, xem phim và quét tâm trạng được, nhưng không lưu dữ liệu.

2.3 Tâm trạng (gợi ý theo cảm xúc)

Mở mục Tâm trạng.
Bấm bật camera và cho phép trình duyệt dùng webcam.
Nhìn thẳng vào camera vài giây. App nhận diện cảm xúc (vui, buồn, bình thản, ngạc nhiên, giận dữ...) và hiện mức năng lượng.
Playlist hợp với cảm xúc đó tự phát. Bạn có thể lưu thành playlist, thêm tất cả vào hàng đợi hoặc hẹn giờ tắt.

Ảnh từ camera chỉ được gửi lên server để phân tích, không được lưu lại.

2.4 Nghe nhạc

Thanh Đang phát ở cuối màn hình có các nút phát/dừng, chuyển bài, hàng đợi và lời bài hát.
Trên điện thoại, nhạc vẫn điều khiển được từ màn hình khoá hoặc tai nghe (Media Session).
Bấm biểu tượng trái tim để thêm vào bài yêu thích. Mọi bài đã thích và playlist đều nằm trong Thư viện.

2.5 Phim

Mở mục Phim, chọn phim từ danh sách hoặc tìm theo tên.
Chọn tập hoặc server rồi bấm phát. Video phát theo chuẩn HLS, chất lượng tự điều chỉnh theo mạng.
Hỏi trợ lý AI (khung chat trong mục Phim) kiểu "phim tình cảm Hàn nhẹ nhàng". Tên phim trong câu trả lời bấm vào được để mở luôn.

2.6 Rạp (xem chung)

Mở mục Rạp. Có 3 phòng chiếu sẵn, bạn cũng có thể tạo phòng mới.
Chọn một ghế trống trên sơ đồ. Ghế đang được người khác giữ sẽ bị khoá tạm.
Chủ phòng chọn phim hoặc nhạc. Mọi người trong phòng xem cùng một thời điểm: khi chủ phòng dừng, tua hay đổi phim, máy của tất cả cùng đổi theo.
Dùng khung chat bên cạnh để nói chuyện. Có thể chuyển sang góc nhìn sảnh 3D.
Phòng do người dùng tạo sẽ tự xoá sau 10 phút không còn ai.

Server chỉ giữ trạng thái phòng (ai ngồi ghế nào, đang chiếu gì, ở giây thứ mấy). Mỗi máy tự tải video từ nguồn gốc.

2.7 Phòng học

Mở mục Phòng học để bật hẹn giờ tập trung kiểu Pomodoro, kèm nhạc nền.
Tạo phòng học chung và gửi mã phòng cho bạn bè. Mọi người bật camera và mic cùng học qua WebRTC (kết nối trực tiếp giữa các máy).

2.8 Studio (tạo nhạc AI)

Nhập mô tả beat, ví dụ "lofi chill piano, mưa nhẹ", chọn tốc độ và tâm trạng.
Viết lời bài hát và chọn giọng (Nữ, Nam, Soprano, Bass, Chipmunk).
Bấm tạo. Server sinh beat, chuyển lời thành giọng hát, mix và master thành một file hoàn chỉnh.
Bài đã tạo nằm trong danh sách bài của bạn ở Studio. Bạn nghe lại, tải về hoặc xoá được.

2.9 Photo Booth

Mở Photo Booth và cho phép camera.
Chọn phông nền. AI tách người khỏi nền ngay trên trình duyệt, không cần phông xanh.
Chụp theo bộ khung nhiều ảnh rồi tải ảnh về.

2.10 Cài như ứng dụng (PWA)

Android / Chrome: mở menu trình duyệt và chọn Cài đặt ứng dụng, hoặc bấm nút Cài ứng dụng trong app.
iPhone / Safari: bấm nút Chia sẻ rồi chọn Thêm vào Màn hình chính.

2.11 Dùng trên TV

Mở app trên trình duyệt của TV. Trên TV, app tự bật chế độ điều khiển bằng remote:

Phím mũi tên: di chuyển giữa các nút (nút đang chọn có viền xanh).
OK: bấm nút đang chọn.
Back: đóng hộp thoại đang mở.
Phát/Dừng, Tua tới, Tua lui: điều khiển video và nhạc, mỗi lần tua 10 giây.

Trên máy tính, thêm ?tv=1 vào cuối địa chỉ để thử chế độ này.

3. Công nghệ sử dụng

Frontend

HTML, CSS, JavaScript thuần: ứng dụng một trang (SPA), không dùng framework nặng.
Tailwind CSS: dựng giao diện và responsive.
HLS.js: phát video .m3u8 cho mục Phim và Rạp.
MediaPipe Selfie Segmentation: tách nền theo thời gian thực trong Photo Booth.
WebRTC (SimplePeer): gọi video giữa các máy trong Phòng học.
WebGL: dựng sảnh rạp 3D.
Service Worker và Web App Manifest: cài như ứng dụng, lưu sẵn giao diện để mở nhanh.

Backend

Python, FastAPI, Uvicorn: REST API, WebSocket cho Rạp và phòng xem chung.
MongoDB Atlas (motor): tài khoản, yêu thích, lịch sử. Mật khẩu băm bằng bcrypt, phiên đăng nhập dùng JWT.
yt-dlp, ytmusicapi, YouTube Data API: tìm kiếm và phát nhạc, video.
Node.js (trong Docker): yt-dlp dùng để giải các thử thách JavaScript của YouTube.

AI và xử lý âm thanh

DeepFace (TensorFlow/Keras): nhận diện cảm xúc khuôn mặt.
Hugging Face (MusicGen): sinh beat từ mô tả.
Edge-TTS, gTTS: chuyển lời thành giọng.
RVC: đổi giọng hát (tuỳ chọn, bật bằng HQ_SINGING).
FFmpeg, pydub, librosa, pedalboard: cắt ghép, mix, thêm reverb và delay, master.
Pollinations: mô hình ngôn ngữ cho trợ lý tư vấn phim.

4. Cấu trúc thư mục

main.py              Ứng dụng FastAPI chính: trang, API nhạc/phim/studio, WebSocket xem chung
config.py            Cấu hình giọng, hiệu ứng theo tâm trạng, tốc độ beat
auth.py              Băm mật khẩu và tạo JWT
routers/
  auth_router.py     Đăng ký, đăng nhập, hồ sơ
  favorites_router.py  Bài yêu thích
  recommend_router.py  Gợi ý theo tương tác
  media_router.py    Lời bài hát, lịch sử, gợi ý theo tâm trạng
  cinema.py          Rạp: phòng, ghế, đồng bộ phát, chat
services/            Logic gợi ý
hf_music_gen.py      Gọi Hugging Face để sinh beat
rvc_engine.py        Đổi giọng hát RVC
voices.py            Danh sách giọng đọc
index.html           Toàn bộ giao diện
css/                 app.css, station.css, cinema.css và các file giao diện khác
js/                  app.js (điều hướng, nhạc, phim), cinema.js, cinema-gl.js, study-room.js,
                     tv-remote.js, i18n.js, queue.js, now-playing.js...
assets/              Ảnh, hoạ tiết cho Rạp
beats/               Beat mẫu có sẵn
models/rvc/          Mô hình giọng RVC
generated_music/     Bài do Studio tạo ra (tự sinh khi chạy)
sw.js, manifest.json Service Worker và manifest cho PWA
scripts/legacy_build.cjs  Hạ cấp JavaScript cho TV đời cũ (chạy trong Docker)
desktop/             Đóng gói bản cài Windows
tizen-tv/            Dự án ứng dụng Samsung Tizen TV
tests/               Kiểm thử
torrent_server.js    Máy chủ WebTorrent phụ (không bắt buộc)

5. Cài đặt và chạy trên máy

5.1 Yêu cầu

Phần mềm	Phiên bản	Ghi chú
Python	3.11 (từ 3.10 trở lên)	yt-dlp không còn hỗ trợ Python cũ hơn
FFmpeg	bản mới	Phải nằm trong biến PATH
Node.js	18 trở lên	Không bắt buộc, giúp yt-dlp ổn định hơn
Git LFS	bản mới	Để tải beat mẫu và mô hình giọng

Cài FFmpeg trên Windows: winget install Gyan.FFmpeg. Trên Ubuntu: sudo apt install ffmpeg. Trên macOS: brew install ffmpeg.

5.2 Tải mã nguồn

git lfs install
git clone https://github.com/giakietkevin/Mood-based-Recommender.git
cd Mood-based-Recommender

5.3 Tạo môi trường ảo và cài thư viện

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -r requirements.txt

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Lần cài đầu khá lâu vì có TensorFlow. Lần đầu quét tâm trạng, DeepFace sẽ tải thêm trọng số mô hình (khoảng vài trăm MB).

5.4 Tạo file `.env`

cp .env.example .env

Sau đó điền các giá trị (xem mục 6). Không có MongoDB thì app vẫn chạy, nhưng không đăng nhập được.

5.5 Chạy server

python main.py

Hoặc chạy bằng uvicorn, có tự tải lại khi sửa code:

uvicorn main:app --host 0.0.0.0 --port 7860 --reload

Mở trình duyệt tại http://localhost:7860.

Camera chỉ hoạt động trên localhost hoặc HTTPS. Muốn thử trên điện thoại cùng mạng Wi-Fi, bạn cần một đường dẫn HTTPS (ví dụ dùng tunnel như cloudflared hoặc ngrok).

5.6 Máy chủ WebTorrent (không bắt buộc)

npm install
node torrent_server.js

Máy chủ này chạy ở cổng 8001. Các tính năng chính không cần nó.

6. Biến môi trường

Biến	Bắt buộc	Dùng cho
`MONGODB_URL`	Có, nếu cần đăng nhập	Chuỗi kết nối MongoDB Atlas
`SECRET_KEY`	Có, nếu cần đăng nhập	Khoá ký JWT. Tạo bằng `openssl rand -hex 32`
`HF_TOKEN`	Không	Token Hugging Face để sinh beat trong Studio
`YOUTUBE_API_KEY`	Không, nhưng nên có	Tìm kiếm vẫn chạy khi YouTube chặn IP của server. Hạn mức miễn phí 10.000 đơn vị/ngày, mỗi lần tìm tốn 100
`YTDLP_COOKIES`	Không	Nội dung file `cookies.txt` của một tài khoản Google phụ, giúp yt-dlp tải được audio
`YTDLP_COOKIES_FILE`	Không	Đường dẫn tới file `cookies.txt`, thay cho biến ở trên
`HQ_SINGING`	Không	`true` để bật giọng hát chất lượng cao bằng RVC (chậm hơn)

Không đưa file .env lên Git. Trên Hugging Face, khai báo các biến này trong Settings > Variables and secrets của Space.

7. Chạy bằng Docker

docker build -t kietstation .
docker run --env-file .env -p 7860:7860 kietstation

Image dựa trên python:3.11 và có sẵn FFmpeg, rubberband, Node.js 20. Lúc build, Docker còn tạo bản giao diện tương thích với TV đời cũ (Tizen 5.0). Nếu bước này lỗi, build vẫn tiếp tục.

8. Triển khai lên Hugging Face Spaces

Space dùng sdk: docker và cổng 7860 (khai báo ở phần đầu file này).

Lưu ý quan trọng: nhánh main của Space có lịch sử riêng, khác với GitHub. Nó không chứa desktop/, tizen-tv/, file .exe và hai icon 512px (Space từ chối các file nhị phân này). Vì vậy:

git push huggingface main sẽ luôn bị từ chối (non-fast-forward).
Không dùng --force, vì sẽ xoá lịch sử của Space.

Cách đẩy bản mới:

Tạo một worktree từ huggingface/main.
Chép code từ main sang, bỏ desktop/, tizen-tv/ và hai icon 512px. Giữ nguyên manifest.json và .gitattributes của Space.
Gỡ hai icon 512px khỏi SHELL trong sw.js và khỏi _ROOT_ICONS trong main.py.
Ảnh mới (ví dụ assets/cinema/*.jpg) phải đi qua Git LFS. Kiểm tra bằng git show :đường/dẫn thấy dòng version https://git-lfs... là đúng.
Commit, kiểm tra đây là fast-forward rồi đẩy: git push huggingface <commit>:refs/heads/main.

Đăng nhập Git với Hugging Face bằng token có quyền Write:

hf auth login --add-to-git-credential

Nếu push báo "You are not authorized to push to this repo", token đã lưu bị hết hạn hoặc đã thu hồi. Chạy lại lệnh trên với token mới.

9. Bản Windows và bản TV

Windows: thư mục desktop/ đóng gói app thành bộ cài .exe (Tauri và WebView2), có sẵn Python và backend chạy cục bộ. Hướng dẫn build xem desktop/README.md.
Samsung Tizen TV: thư mục tizen-tv/ là dự án Tizen Studio, mở app trong một khung trên TV. Build và cài lên TV bằng Tizen Studio.

10. Kiểm thử

python tests/test_cinema.py -v

Bộ test kiểm tra logic Rạp: giữ ghế, giới hạn tốc độ gửi tin, đồng bộ trạng thái phát và WebSocket.

11. Xử lý sự cố thường gặp

Hiện tượng	Cách xử lý
Không bật được camera	Chỉ dùng được trên `localhost` hoặc HTTPS. Kiểm tra quyền camera của trình duyệt.
Nhạc không phát, tìm kiếm trống	YouTube có thể chặn IP của server. Thêm `YOUTUBE_API_KEY`, và `YTDLP_COOKIES` nếu cần. Cập nhật yt-dlp: `pip install -U yt-dlp`.
Lỗi `ffmpeg not found`	Cài FFmpeg và thêm vào PATH, rồi mở lại terminal.
Quét tâm trạng lần đầu rất chậm	DeepFace đang tải trọng số mô hình. Những lần sau sẽ nhanh.
Không đăng nhập được	Kiểm tra `MONGODB_URL`, `SECRET_KEY` và danh sách IP được phép trên MongoDB Atlas.
Giao diện cũ sau khi cập nhật	Service Worker còn giữ bản cũ. Tải lại cứng bằng Ctrl+Shift+R hoặc xoá dữ liệu trang.
TV hiện màn hình đen	TV đời cũ cần bản giao diện đã hạ cấp. Chạy bằng Docker để bước build này được thực hiện.

12. Pháp lý và giới hạn

Đây là dự án mã nguồn mở phục vụ nghiên cứu các mảng WebRTC, chuyển văn bản thành giọng nói, phát video trực tuyến và thị giác máy tính.
Nội dung phim lấy từ các API công khai. Ứng dụng không lưu file MP4 hay m3u8 trên server. Vui lòng tôn trọng bản quyền của nơi sở hữu nội dung.
Nhạc phát từ YouTube thuộc quyền của chủ sở hữu tương ứng.

Name		Name	Last commit message	Last commit date
.claude		.claude
assets/cinema		assets/cinema
beats		beats
css		css
desktop		desktop
js		js
models/rvc		models/rvc
routers		routers
scripts		scripts
services		services
tizen-tv		tizen-tv
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
COMMIT_CLEAN.bat		COMMIT_CLEAN.bat
Dockerfile		Dockerfile
README.md		README.md
Reprompt.txt		Reprompt.txt
STUDY_ROOM_FEATURES.md		STUDY_ROOM_FEATURES.md
android-chrome-192x192.png		android-chrome-192x192.png
android-chrome-512x512.png		android-chrome-512x512.png
apple-touch-icon.png		apple-touch-icon.png
auth.py		auth.py
config.py		config.py
convert_to_b64.py		convert_to_b64.py
favicon-16x16.png		favicon-16x16.png
favicon-32x32.png		favicon-32x32.png
favicon.ico		favicon.ico
fix_dj_focus.js		fix_dj_focus.js
fix_extract_vid.js		fix_extract_vid.js
hf_music_gen.py		hf_music_gen.py
index.html		index.html
main.py		main.py
manifest.json		manifest.json
maskable-512x512.png		maskable-512x512.png
package-lock.json		package-lock.json
package.json		package.json
patch_discover.py		patch_discover.py
patch_discover_html.py		patch_discover_html.py
patch_discover_music.py		patch_discover_music.py
patch_dj_cam.py		patch_dj_cam.py
patch_index.py		patch_index.py
patch_library.py		patch_library.py
patch_loadfavorites.py		patch_loadfavorites.py
patch_loadfavorites2.py		patch_loadfavorites2.py
patch_music_fetch.py		patch_music_fetch.py
patch_supabase.js		patch_supabase.js
patch_yt_error.py		patch_yt_error.py
plan_study_room.md		plan_study_room.md
plan_study_room_webrtc.md		plan_study_room_webrtc.md
requirements.txt		requirements.txt
rvc_engine.py		rvc_engine.py
sw.js		sw.js
test.html		test.html
tmp_vip_modal.html		tmp_vip_modal.html
torrent_server.js		torrent_server.js
trending_songs.json		trending_songs.json
user_films.json		user_films.json
user_playlists.json		user_playlists.json
voices.py		voices.py

Latest commit

History

Folders and files

Repository files navigation

KietStation (Mood-based-Recommender)

Mục lục

1. Tính năng

2. Hướng dẫn sử dụng

2.1 Điều hướng

2.2 Đăng nhập

2.3 Tâm trạng (gợi ý theo cảm xúc)

2.4 Nghe nhạc

2.5 Phim

2.6 Rạp (xem chung)

2.7 Phòng học

2.8 Studio (tạo nhạc AI)

2.9 Photo Booth

2.10 Cài như ứng dụng (PWA)

2.11 Dùng trên TV

3. Công nghệ sử dụng

Frontend

Backend

AI và xử lý âm thanh

4. Cấu trúc thư mục

5. Cài đặt và chạy trên máy

5.1 Yêu cầu

5.2 Tải mã nguồn

5.3 Tạo môi trường ảo và cài thư viện

5.4 Tạo file .env

5.5 Chạy server

5.6 Máy chủ WebTorrent (không bắt buộc)

6. Biến môi trường

7. Chạy bằng Docker

8. Triển khai lên Hugging Face Spaces

9. Bản Windows và bản TV

10. Kiểm thử

11. Xử lý sự cố thường gặp

12. Pháp lý và giới hạn

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

5.4 Tạo file `.env`