Add new audio file: nhac-phat-giao.mp3 to media directory

2026-06-25 14:28:46 +07:00
parent 8ad9c7113b
commit 6fa8a6016a
16 changed files with 179 additions and 18 deletions
@@ -0,0 +1,95 @@
+# Lồng tiếng thuyết minh + nhạc nền — Tour Chùa Thái Lạc
+
+Ngày: 2026-06-25
+
+## Mục tiêu
+
+Gắn âm thanh thuyết minh (lồng tiếng) cho từng cảnh trong tour VR360 Chùa Thái Lạc,
+và thêm nhạc nền chạy liên tục trên toàn bộ tour với âm lượng nhỏ nhẹ để không lấn lời thuyết minh.
+
+## Bối cảnh kỹ thuật
+
+Engine `src/app/components/VirtualTour.tsx` đã hỗ trợ đầy đủ, **không cần sửa logic**:
+
+- `backgroundAudio: string` — một track nhạc nền phát lặp (`loop`). Âm lượng nền
+  `AUDIO_TARGET_VOLUME = 0.16`, tự động hạ xuống `BACKGROUND_DUCK_VOLUME = 0.045`
+  khi đang phát thuyết minh (ducking). Chuỗi rỗng `""` → engine bỏ qua, không render audio.
+- `sceneNarration: Map<SceneId, string[]>` — mỗi cảnh có một MẢNG nguồn âm thanh,
+  phát tuần tự (hàng đợi). Âm lượng thuyết minh `NARRATION_TARGET_VOLUME = 0.7`.
+- `continuousNarrationGroups: SceneId[][]` — các cảnh trong cùng nhóm dùng chung file
+  sẽ phát LIỀN MẠCH (không tua lại) khi khách di chuyển giữa chúng.
+
+Đây là việc cấu hình DỮ LIỆU trong `src/app/tours/chua-thai-lac.ts` + đổi tên file âm thanh.
+
+## Yêu cầu
+
+### 1. Đổi tên 13 file âm thanh sang ASCII
+
+Theo convention dự án (tránh lỗi URL-encode + phân biệt hoa/thường khi deploy lên Linux/Vercel).
+Hai file `.MP3` (chữ hoa) được chuẩn hóa thành `.mp3`.
+
+| File hiện tại | Tên mới |
+|---|---|
+| `public/media/chua-thai-lac/Lời chào.mp3` | `loi-chao.mp3` |
+| `public/media/chua-thai-lac/Tam quan.mp3` | `tam-quan.mp3` |
+| `public/media/chua-thai-lac/Sân Tịnh An.mp3` | `san-tinh-an.mp3` |
+| `public/media/chua-thai-lac/Hồ Di Lặc.MP3` | `ho-di-lac.mp3` |
+| `public/media/chua-thai-lac/Tiền sảnh.mp3` | `tien-sanh.mp3` |
+| `public/media/chua-thai-lac/Tôn Đài Đức Phật Thích Ca.mp3` | `ton-dai-duc-phat.mp3` |
+| `public/media/chua-thai-lac/Vườn tháp cổ.mp3` | `vuon-thap-co.mp3` |
+| `public/media/chua-thai-lac/Khách xá.mp3` | `khach-xa.mp3` |
+| `public/media/chua-thai-lac/Khách đường.mp3` | `khach-duong.mp3` |
+| `public/media/chua-thai-lac/Hữu Vu La Hán- Tả Vu La Hán.MP3` | `huu-vu-ta-vu-la-han.mp3` |
+| `public/media/chua-thai-lac/Nhà Tổ.mp3` | `nha-to.mp3` |
+| `public/media/chua-thai-lac/Tiền Đường.mp3` | `tien-duong.mp3` |
+| `public/media/nhac-nen/Nhạc Phật Giáo sâu lắng.mp3` | `nhac-phat-giao.mp3` |
+
+### 2. Cấu hình `src/app/tours/chua-thai-lac.ts`
+
+**a) Nhạc nền:** `backgroundAudio: ""` → `"/media/nhac-nen/nhac-phat-giao.mp3"`.
+Giữ nguyên âm lượng mặc định của engine (nền 0.16, ducking 0.045 khi thuyết minh).
+
+**b) Bảng thuyết minh `narrationGroups`** — mở rộng kiểu trường `audio` thành `string | string[]`
+để cảnh 1-3 phát nối tiếp hai file (lời chào rồi Tam quan):
+
+```
+[loi-chao, tam-quan] → cảnh 1, 2, 3
+san-tinh-an          → cảnh 4, 5
+ho-di-lac            → cảnh 6
+tien-sanh            → cảnh 7, 8        (MỚI)
+ton-dai-duc-phat     → cảnh 9           (MỚI)
+vuon-thap-co         → cảnh 10          (MỚI)
+(không thuyết minh)  → cảnh 11
+khach-xa             → cảnh 12, 13, 14
+khach-duong          → cảnh 15
+huu-vu-ta-vu-la-han  → cảnh 16, 18
+nha-to               → cảnh 17
+tien-duong           → cảnh 19, 20, 21
+```
+
+Vòng lặp build `sceneNarration` phải chuẩn hóa `audio` (string hoặc string[]) thành mảng nguồn
+qua `audioForName` cho mỗi cảnh.
+
+**c) `continuousNarrationGroups`** — thêm `["scene-7", "scene-8"]` (hai cảnh kề nhau dùng chung
+`tien-sanh`). Các nhóm hiện có giữ nguyên. Cảnh 16 & 18 vẫn KHÔNG gom (cách nhau bởi cảnh 17)
+nên sẽ phát lại — đúng hành vi mong muốn.
+
+## Hành vi đã thống nhất
+
+- Cảnh 1: phát `loi-chao` rồi tự động phát `tam-quan`; di chuyển 1→2→3 không tua lại.
+- Rời cảnh 1-3 rồi quay lại → "lời chào" phát lại từ đầu (hành vi mặc định, chấp nhận được).
+- Nhạc nền nhỏ nhẹ và tự hạ thấp hơn nữa khi có thuyết minh.
+
+## Kiểm chứng
+
+1. `npm run lint` / `npm run build` không lỗi type.
+2. `npm run dev`, vào tour và xác nhận:
+   - Nhạc nền chạy nhẹ liên tục mọi cảnh.
+   - Mỗi cảnh phát đúng file thuyết minh theo bảng trên.
+   - Cảnh 1 nghe "lời chào → tam quan" nối tiếp.
+   - Nhạc nền tự nhỏ lại khi đang có lời thuyết minh.
+
+## Ngoài phạm vi
+
+- Không sửa logic engine `VirtualTour.tsx`.
+- Không thay đổi nội dung popup info markers, hướng mũi tên, hay sơ đồ mini-map.