WELIFE Sound Pack — Brief phối âm AI

Đối tượng: đội / agent phối âm AI (Suno · ElevenLabs · Udio · AudioCraft · …) Mục đích: tạo bộ SFX + ringtone cho Consumer · Partner · Driver · push in-app API upload: tag Swagger media · POST /api/v1/upload/single · POST /api/v1/upload/multiple Contract: local http://localhost:3000/docs (prod api.minhtien.cloud thường tắt /docs — SWAGGER_ENABLED=false)

1. Tóm tắt số lượng

Hạng mục	Số file	Ghi chú
Tổng sound pack bắt buộc	28	Đủ call + notif + UI + ride + wallet
Upload 1 lần (`POST /upload/multiple`)	tối đa 10	`MEDIA_MAX_FILES = 10`
Cách upload đủ pack	3 batch	`10 + 10 + 8` (hoặc 28× `single` / presign)
Giới hạn size API	15 MB/file	Soft target SFX: ≤ 512 KB/file
Định dạng ưu tiên	`.mp3` (`audio/mpeg`)	Thêm `.wav` nếu cần iOS push bundle

MIME audio API chấp nhận: audio/mpeg · audio/wav · audio/x-wav · audio/ogg · audio/mp4 · audio/aac · audio/webm → Prisma MediaKind = AUDIO

Lưu ý push OS: custom sound Expo/APNs/FCM phải bundle trong app (không lấy URL MinIO lúc runtime). File upload qua API dùng cho in-app playback (ringtone khi app foreground, SFX UI, CDN preview Admin). Cùng một bản master: xuất .mp3 (CDN) + optionally .caf/.wav ngắn ≤30s (bundle).

2. Brand hướng dẫn (cho AI)

Thuộc tính	Yêu cầu
Brand	WELIFE — siêu app đời sống VN, thân thiện, tin cậy
Tone	Clean · modern · soft tech · không harsh / horror / meme
Nhạc nền	Không — chỉ SFX / short motif
BPM / pitch	Trung tính; ringtone có thể có motif 2–4 nốt nhận diện
Loudness	Normalize ~ -14 LUFS (ringtone) · -16…-18 LUFS (UI micro-SFX)
Silence	Pad 30–80 ms đầu/cuối tránh click
Loop	Ringtone incoming/outgoing: seamless loop 2–4s
Ngôn ngữ	Không lời (instrumental / synthetic only)
Bản quyền	100% original / AI-generated · không sample thương mại có bản quyền

Prompt khung (copy cho AI):

Create a short clean UI sound effect for a Vietnamese lifestyle super-app named WELIFE.
Modern soft tech, warm mid tones, no lyrics, no harsh distortion, no meme sounds.
Normalize carefully, leave 40ms silence at start and end. Export stereo MP3 44.1kHz.

3. Danh sách file (28) — tên + mô tả

A. Cuộc gọi / WebRTC (`chat` · `call:ring`) — 7 file

#	Tên file	Thời lượng	Loop?	Mô tả cho AI
1	`call_ringtone_incoming.mp3`	2.5–4 s	Yes	Chuông cuộc gọi đến (callee). Motif WELIFE dễ nhận, dịu, lặp liền mạch. Play khi `call:ring` + status RINGING.
2	`call_ringtone_outgoing.mp3`	2–3.5 s	Yes	Tone gọi đi (caller) kiểu “ringback” nhẹ, không giống chuông đến.
3	`call_connecting.mp3`	1–2 s	Yes (soft)	Chờ kết nối / ice gathering — pulse rất nhẹ.
4	`call_connected.mp3`	0.4–0.8 s	No	Một lần khi `answer` / status ACTIVE — “đã nối máy”.
5	`call_ended.mp3`	0.3–0.6 s	No	Cúp máy bình thường (`ENDED`).
6	`call_busy.mp3`	0.6–1.2 s	No	Từ chối / bận (`DECLINED` · `CANCELLED`) — 2–3 beep ngắn.
7	`call_missed.mp3`	0.8–1.5 s	No	Nhỡ cuộc gọi (`MISSED`) — soft alert, dùng kèm notif.

B. Thông báo in-app / push mapping — 7 file

#	Tên file	Thời lượng	Loop?	Mô tả cho AI
8	`notif_default.mp3`	0.4–0.9 s	No	Thông báo chung (thay cảm giác `sound: 'default'`).
9	`notif_message.mp3`	0.25–0.5 s	No	Tin nhắn chat mới — soft ping.
10	`notif_order.mp3`	0.4–0.8 s	No	Đơn hàng F&B / grocery / delivery cập nhật.
11	`notif_ride.mp3`	0.5–1.0 s	No	Tài xế nhận / sắp đến — rõ hơn default, vẫn thân thiện.
12	`notif_payment.mp3`	0.5–0.9 s	No	Thanh toán / ví thành công — “cha-ching” nhẹ, không casino.
13	`notif_promo.mp3`	0.5–1.0 s	No	Khuyến mãi — vui, ngắn, không ồn.
14	`notif_urgent.mp3`	0.8–1.5 s	No	Khẩn (KYC fail, bảo mật, SOS nhẹ) — nghiêm túc hơn, không sợ hãi.

C. Tương tác UI — 6 file

#	Tên file	Thời lượng	Loop?	Mô tả cho AI
15	`ui_success.mp3`	0.3–0.6 s	No	Form OK · đặt chỗ · xác nhận.
16	`ui_error.mp3`	0.25–0.5 s	No	Lỗi validation / API fail — short negative tone.
17	`ui_send_message.mp3`	0.15–0.35 s	No	Gửi tin — whoosh rất nhẹ.
18	`ui_add_cart.mp3`	0.15–0.35 s	No	Thêm giỏ — soft pop.
19	`ui_checkout.mp3`	0.4–0.7 s	No	Đặt đơn thành công (ngắn hơn payment).
20	`ui_scan_qr.mp3`	0.15–0.3 s	No	Quét QR / barcode — crisp beep.

D. Ride / Driver — 4 file

#	Tên file	Thời lượng	Loop?	Mô tả cho AI
21	`ride_driver_assigned.mp3`	0.5–0.9 s	No	Đã ghép tài xế.
22	`ride_driver_arriving.mp3`	0.6–1.0 s	No	Tài xế sắp tới điểm đón.
23	`ride_trip_started.mp3`	0.4–0.7 s	No	Bắt đầu chuyến.
24	`ride_trip_completed.mp3`	0.6–1.0 s	No	Kết thúc chuyến — warm resolve.

E. Ví / thanh toán — 4 file

#	Tên file	Thời lượng	Loop?	Mô tả cho AI
25	`wallet_topup_success.mp3`	0.5–0.9 s	No	Nạp ví OK.
26	`wallet_transfer_sent.mp3`	0.4–0.7 s	No	Chuyển đi.
27	`wallet_transfer_received.mp3`	0.5–0.9 s	No	Nhận tiền — hơi “bright” hơn sent.
28	`wallet_payment_fail.mp3`	0.4–0.8 s	No	Thanh toán thất bại — rõ ràng, không panic.

4. Mapping sự kiện hệ thống → file

Sự kiện	Surface	File
`POST /chat/calls` + WS `call:ring` (callee)	CON	`call_ringtone_incoming`
Caller chờ trả lời	CON	`call_ringtone_outgoing`
`POST /chat/calls/:id/answer`	CON	dừng ring → `call_connected`
`end` status `ENDED`	CON	`call_ended`
`DECLINED` / `CANCELLED`	CON	`call_busy`
`MISSED` + push	CON	`call_missed` + `notif_default`
Chat message mới (foreground)	CON	`notif_message`
Order status push	CON · PAR	`notif_order`
Ride match / arrive	CON · DRV	`notif_ride` / `ride_*`
Wallet / payment OK	CON	`notif_payment` / `wallet_*`

5. Upload qua API (máy chủ)

Giới hạn

POST /api/v1/upload/multiple   → tối đa 10 file / request
POST /api/v1/upload/single     → 1 file
POST /api/v1/upload/presign    → contentType audio/*
Max size                      → 15 MB / file (khuyến nghị SFX ≤ 512 KB)
Auth                          → Bearer JWT (USER / ADMIN / PARTNER_*)

Batch đề xuất (đúng tên file)

Batch 1 (10) — Call + phần notif:

call_ringtone_incoming.mp3
call_ringtone_outgoing.mp3
call_connecting.mp3
call_connected.mp3
call_ended.mp3
call_busy.mp3
call_missed.mp3
notif_default.mp3
notif_message.mp3
notif_order.mp3

Batch 2 (10) — Notif còn lại + UI + ride đầu:

notif_ride.mp3
notif_payment.mp3
notif_promo.mp3
notif_urgent.mp3
ui_success.mp3
ui_error.mp3
ui_send_message.mp3
ui_add_cart.mp3
ui_checkout.mp3
ui_scan_qr.mp3

Batch 3 (8) — Ride + wallet:

ride_driver_assigned.mp3
ride_driver_arriving.mp3
ride_trip_started.mp3
ride_trip_completed.mp3
wallet_topup_success.mp3
wallet_transfer_sent.mp3
wallet_transfer_received.mp3
wallet_payment_fail.mp3

Ví dụ curl (local)

# 1 file
curl -X POST "http://localhost:3000/api/v1/upload/single" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@call_ringtone_incoming.mp3;type=audio/mpeg"

# Batch (≤10)
curl -X POST "http://localhost:3000/api/v1/upload/multiple" \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@call_ringtone_incoming.mp3;type=audio/mpeg" \
  -F "files=@call_ringtone_outgoing.mp3;type=audio/mpeg"

Response mỗi item: { id, objectKey, publicUrl, mimeType, sizeBytes, kind: "AUDIO", status: "READY" }.

6. Deliverable đội AI trả về

Thư mục welife-sound-pack-v1/ gồm đủ 28 file .mp3 đúng tên cột trên.
(Tuỳ chọn) bản .wav mono 16-bit cho iOS push bundle — cùng stem name.
File MANIFEST.csv: filename,duration_sec,lufs,loop,notes.
1 dòng credit: tool + model + ngày generate.

7. Checklist nghiệm thu

Đúng 28 tên file (snake_case + .mp3) — procedural synth v1 (scripts/generate-sound-pack.mjs)
Upload 3 batch qua /upload/multiple lên prod api.minhtien.cloud (2026-08-04) · kind=AUDIO ×28
Ringtone incoming/outgoing loop sạch (nghe thử tai người)
Không lời · không sample có bản quyền
Mỗi file ≤ 512 KB
Nghe thử trên tai nghe + loa điện thoại (không méo / quá lớn)
(Tuỳ chọn) thay bản AI Suno/ElevenLabs giữ đúng tên file rồi re-upload

Local pack: assets/sound-pack-v1/ · MANIFEST.csv Upload script: scripts/upload-sound-pack.sh

8. Tham chiếu code / docs

Mục	Path
ALLOWED_MIME + max files	`api/src/modules/media/media.constants.ts`
Swagger tag `media`	`api/src/modules/media/media.controller.ts` · `api/src/main.ts`
Call REST + SFX mapping notes	`api/src/modules/chat/chat.controller.ts`
Push hiện tại (`sound: 'default'`)	`api/src/modules/notifications/notifications.service.ts`
Call UI	`mobile/src/features/chat/screens/CallScreen.tsx`

Domain: D-MEDIA · D-CHAT · D-NOTIF WP: WP-MEDIA-SOUND-01 (docs + MIME audio + Swagger)