sfx-library

Thư viện Sound Effect

834 file / 63 category / ~1 GB. Một cửa vào duy nhất: script sfx nằm cùng thư mục với file SKILL.md này. Script tự xác định đường dẫn của chính nó nên gọi được từ bất kỳ đâu bằng đường dẫn đầy đủ — các ví dụ dưới viết gọn là sfx.

Bước 0 — kiểm tra đã có dữ liệu chưa

Repo chỉ chứa code và catalog; file âm thanh nằm trong data/ (không commit).

sfx status

Báo "Chua co du lieu" thì lấy dữ liệu — một lần, ~1 GB, báo cho user trước khi tải:

sfx setup

setup tự đi theo đúng thứ tự ưu tiên, đừng đảo lại:

1. Google Drive trước — tải một file .zip (~880 MB, khoảng 1 phút), đối chiếu sha256 rồi giải nén.
2. URL có sẵn trong catalog là dự phòng — chỉ dùng khi Drive thất bại (404, file chưa chia sẻ công khai, hết hạn mức lượt tải, sha256 lệch). Khi đó setup tự chuyển sang tải từng file theo URL trong catalog/source/*.json (tuần tự, ~18 phút) và đối chiếu sha256 với catalog/meta.json.

Chỉ cần python3 (≥ 3.8), không cần cài thêm gì. Bị ngắt giữa chừng thì chạy lại sfx setup — nó tải tiếp, không tải lại từ đầu. Bước dự phòng chậm: chạy nền và báo user thời gian chờ.

Chỉ gọi thẳng sfx setup --source (bỏ qua Drive) khi user yêu cầu.

setup báo "Ca hai nguon deu that bai" thì chạy sfx doctor và báo user — đừng tự tìm nguồn âm thanh khác thay thế.

Tìm SFX — lệnh duy nhất cần nhớ

sfx find "<từ khoá>"

Gõ tiếng Việt có dấu, không dấu, hay tiếng Anh đều ra cùng kết quả — dấu được bỏ trước khi so, và mỗi category có sẵn bộ từ khoá song ngữ.

sfx find "chuyển cảnh"          # theo ý định
sfx find "thông báo" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5

Kết quả in kèm độ dài (giây) — thông tin quan trọng nhất khi khớp SFX vào timeline.

Cờ	Dùng khi
--max-dur N / --min-dur N	ràng buộc độ dài theo khe trong timeline
--group <nhóm>	duyệt cả một ý định (bảng nhóm bên dưới)
--category <slug>	đã biết chính xác category
--ext wav	chỉ lấy wav (hoặc mp3)
--paths	chỉ in đường dẫn, mỗi dòng một file — đưa thẳng vào lệnh khác
--json	đầu ra cho máy đọc, kèm duration, sha256, score
--abs	đường dẫn tuyệt đối — dùng khi gọi sfx từ thư mục khác
-n N / --all	số kết quả (mặc định 20)

Query nhiều từ mặc định là AND; không có file nào khớp đủ mọi từ thì tự nới thành OR và báo rõ trên stderr.

Không chắc dùng gì → sfx list in toàn bộ category kèm "dùng khi nào" và từ khoá.

10 nhóm theo ý định

Chọn nhóm trước, rồi mới lọc — nhanh hơn là đoán tên category.

Nhóm	Dùng để	Category tiêu biểu
transition	nối hai cảnh	fast-whoosh swoosh-swish whip zoom reverse
impact	chốt ý, hiện số liệu	hit boom impacts slam bass
ui	chữ hiện, bấm nút, gõ phím	pop click typing ui-mini tick shine
alert	thông báo, nhắc hẹn	notification ding bell alarm
tension	dẫn dắt trước cao trào	riser builder braam tension trailer
ambience	nền trải dài dưới cảnh	ambience environment
foley	vật thể thật	paper doors footsteps liquid draw camera-shutter
comedy	hài hước	comedy-cartoon memes
scifi	công nghệ, kỳ ảo	technology glitch laser magic data
horror	kinh dị	horror jumpscare

Nghe trước khi chọn

Tên slug không đủ để đoán file nghe ra sao. whoosh-fast-05 và whoosh-fast-06 có thể khác hẳn nhau về sắc thái.

afplay "$(sfx find whoosh --paths --abs -n 1)"     # macOS; Linux: ffplay -nodisp -autoexit

Không nghe được (chạy headless) thì đưa 2–3 lựa chọn kèm độ dài cho user chọn, đừng tự quyết rồi khẳng định là hợp.

Ghép SFX vào video

sfx mix video.mp4 -o co-tieng.mp4 \
    2.4:fast-whoosh/whoosh-fast-05.wav \
    5.0:ding/[email protected]

Mỗi cue là <giây>:<đường dẫn>[@âm-lượng]. Đường dẫn tính từ data/sfx/, hoặc ghi mỗi tên file nếu không trùng. Âm lượng mặc định 0.6. Cần ffmpeg.

• Tiếng sẵn có trong video được giữ và trộn cùng, không bị đè — chạy sfx mix sau khi đã ghép voiceover là an toàn.
• Dùng amix=normalize=0 + alimiter: thêm cue không làm nhỏ tiếng gốc, và không vỡ tiếng khi các nguồn chồng nhau.
• --dry-run in ra lệnh ffmpeg nếu cần ghép vào script khác.

Video dựng từ HTML (Playwright/Puppeteer/Remotion quay màn hình): thẻ <audio> hay new Audio().play() trong trang chỉ kêu khi xem trên trình duyệt — nó không đi vào file MP4 được quay. Ghép SFX ở bước ffmpeg bằng sfx mix, lấy mốc thời gian từ timeline animation.

Ba điều quyết định video nghe có chuyên nghiệp không:

1. SFX phải ngắn hơn khe timeline — lọc bằng --max-dur ngay từ đầu thay vì cắt sau.
2. Đặt SFX đúng frame của chuyển động, không phải đầu cảnh — whoosh phải nổ đúng lúc vật thể bắt đầu bay.
3. Đừng chồng SFX lên lời thoại. Có voiceover thì hạ @0.3 hoặc dùng category ui-mini.

Ba điều dễ làm sai

1. Đừng commit data/ — ~1 GB, đã gitignore, lấy lại bằng sfx setup.
2. Đừng sửa file trong data/sfx/. Đó là bản gốc; cắt/chuẩn hoá âm lượng thì xuất ra chỗ khác.
3. Đừng gọi thẳng sfx download để lấy dữ liệu lần đầu. Nó tải 834 file lẻ, chậm, và là đường dự phòng. Luôn gọi sfx setup để Google Drive được thử trước.

Kiểm tra khi nghi có vấn đề: sfx doctor (công cụ + nguồn dữ liệu), sfx verify --hash (bấm lại sha256 từng file).

Bảo trì thư viện (thêm category, đóng gói lại, đổi link Drive): xem README.md.