Tài Liệu Hướng Dẫn Kỹ Thuật & Tích Hợp VSNX
Hướng dẫn toàn diện từ đóng gói mã hóa video bằng CLI/GUI đến tích hợp Web Player không lộ link gốc vào mọi nền tảng web (HTML5, React, WordPress LMS).
Tổng Quan Định Dạng VSNX & Kiến Trúc Bảo Mật
VSNX (Video Stream Native eXclusive) là định dạng container video độc quyền được thiết kế đặc biệt nhằm giải quyết triệt để vấn đề tải trộm video trên môi trường Web, LMS và các nền tảng đào tạo số.
Cấu Trúc Đóng Gói Nhị Phân
Không tuân theo MP4 Box hay TS HLS. Header chứa metadata được ký số hóa, phân vùng audio/video chunk riêng biệt.
Mã Hóa AES-256 CTR/GCM
Mỗi khối khung hình (frame block) được mã hóa bằng vector khởi tạo (IV) riêng, ngăn chặn triệt để tấn công replay attack.
Vẽ Trực Tiếp Qua Canvas GPU
Không dùng thẻ <video> hay Blob URL lộ stream. Giải mã trực tiếp trong RAM và vẽ ra Canvas.
Sử Dụng VSNX CLI Converter (vsnx2_converter.exe)
Bộ nhị phân độc lập vsnx2_converter.exe (C++ Native, đa luồng OpenMP bounded) cho phép đóng gói, mã hóa và xuất ngược tệp tin video tự động hóa trên máy chủ CI/CD, Windows Server và Linux worker.
Cú Pháp Lệnh Thực Tế (CLI Terminal):
Bảng Tổng Hợp Đầy Đủ 13 Cờ Tham Số Kỹ Thuật (CLI Flags):
| Tham Số / Cờ | Kiểu | Ý Nghĩa & Chức Năng Kỹ Thuật | Mặc Định |
|---|---|---|---|
| encode <in> <out> | Chế độ | Đóng gói & mã hóa video nguồn (MP4, MOV ProRes, MKV, FLV) sang tệp nhị phân .vsnx. |
Bắt buộc |
| decode <in> <out> | Chế độ | Giải mã tệp .vsnx và xuất trở lại container MP4 tiêu chuẩn (yêu cầu mật khẩu nếu có). |
Tùy chọn |
| --password <str> | Chuỗi | Mật khẩu mã hóa AES-256 CTR phân đoạn nhị phân. Nếu không cấp, tệp ở chế độ Public Zero-Leak. | None (Public) |
| --vfr | Cờ bật | Kích hoạt Variable Frame Rate thích ứng, tối ưu kích thước bài giảng slide tĩnh lên đến 60%. | false |
| --gabor | Cờ bật | Tiêm vi vân kết cấu Gabor (Micro-texture noise) ngẫu nhiên, vô hiệu hóa thuật toán nén của app quay màn hình. | false |
| --fast-start | Cờ bật | Đưa siêu dữ liệu Header nhị phân lên đầu tệp, cho phép Web Player phát ngay lập tức không cần tải hết tệp. | false |
| --cclc | Cờ bật | Nén thích ứng đường cong màu sắc & độ sáng (Color Curve & Luminance Compression). | false |
| --watermark <str> | Chuỗi | Nhúng Watermark pháp y tàng hình (Steganography Tier 2) vào ma trận DCT/pixel, truy vết kẻ rò rỉ. | None |
| --quality <1-100> | Số nguyên | Mức chất lượng nén lượng tử hóa (CRF). Giá trị từ 1 (nén cao nhất) đến 100 (ProRes lossless). | 80 |
| --gop <frames> | Số nguyên | Khoảng cách khung hình chính (Group of Pictures / Keyframe Interval) cho khả năng tua tức thì. | 30 |
| --audio-preset <p> | Chuỗi | Cấu hình tiền xử lý âm thanh: standard (128k), voice (64k lọc ồn), high (256k), lossless. |
standard |
| --audio-codec <c> | Chuỗi | Bộ mã hóa âm thanh đích: aac, opus, pcm. |
aac |
| --threads <n> | Số nguyên | Số luồng CPU xử lý đồng thời (OpenMP Bounded, có cơ chế chặn tràn tài nguyên an toàn). | 4 |
Studio GUI Converter (gui_converter.exe)
Ứng dụng đồ họa Win32 C++ nguyên bản dành cho giảng viên và biên tập viên nội dung. Khởi chạy tức thì trong 0.1 giây, tiêu thụ dưới 20MB RAM và cung cấp đầy đủ các tùy chọn mã hóa chuyên sâu bằng thao tác kéo thả chuột trực quan.
Bảng Điều Khiển Nâng Cao (Win32 Controls):
- • Thanh trượt chất lượng (Quality Slider 1 - 100): Kéo thả mượt mà điều chỉnh tỷ lệ nén trực quan theo thời gian thực.
- • Khoảng cách GOP (Keyframe Distance): Ô nhập spin-box tùy biến chu kỳ I-Frame tối ưu độ trễ tua video.
-
•
Bộ 4 hộp kiểm công nghệ độc quyền: Checkbox bật tắt linh hoạt
VFR Mode,Gabor Noise Injection,Web Fast-Start, vàCCLC Optimization. - • Tùy biến Audio Preset & Watermark Pháp Y: Chọn cấu hình âm thanh bài giảng và nhập mã định danh bản quyền ẩn (Steganography Tier 2).
Kiểm Thử Tức Thì Với Desktop Player:
Tích hợp nút kiểm thử 1-chạm "Mở trong Player". Ngay sau khi chuyển đổi hoàn tất, ứng dụng sẽ tự động kích hoạt trình phát nội bộ vsnx2_player_gui.exe để kiểm tra chất lượng hình ảnh, phụ đề và watermark trực tiếp trong RAM mà không cần tải lên máy chủ web.
Nhúng VSNX Web Player Vào Ứng Dụng
Thư viện vsnx2-player.js là một tệp JavaScript thuần độc lập, không có dependency nào khác ngoài trình duyệt.
Các Thẻ HTML & Mã Nguồn Nhúng Trực Quan:
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
Kiến Trúc Bảo Mật Watermark 2 Lớp (2-Tier Watermarking)
Hệ thống VSNX kết hợp sức mạnh bảo vệ kép: Lớp 1 (Visual Dynamic Canvas) răn đe thị giác trên trình duyệt, và Lớp 2 (Invisible Forensic Steganography) truy vết pháp lý tàng hình ăn sâu vào điểm ảnh video.
Lớp 1: Thủy Vân Động Canvas (Dynamic Watermark)
Client WebGLRender trực tiếp qua WebGL Canvas GPU theo thời gian thực. Tọa độ nhảy ngẫu nhiên trên màn hình mỗi vài giây. Không tồn tại trong DOM HTML, miễn nhiễm 100% với DevTools và tiện ích chặn quảng cáo.
Lớp 2: Thủy Vân Ẩn Pháp Y (Forensic Steganography)
Điểm Ảnh Gốc C++Thủy vân pháp y vô hình nhúng vĩnh viễn vào ma trận biến đổi DCT trong quá trình chuyển đổi. Mắt người không thấy được nhưng sống sót hoàn hảo trước các tác vụ quay trộm bằng điện thoại, cắt cúp (crop) hay nén lại.
Cấu Hình Thủy Vân Động Lớp 1 (Visual Dynamic WebGL):
Trích Xuất Dấu Vết Pháp Y Lớp 2 (vsnx2_forensic_extract.exe):
Khi phát hiện video bị quay lén bằng điện thoại và rao bán lậu, sử dụng công cụ pháp y để bóc tách mã định danh ẩn:
Xác Thực Backend API & Cấp Khóa Giải Mã Theo Phiên
Để đạt cấp độ bảo mật doanh nghiệp cao nhất, mật khẩu giải mã không bao giờ được hard-code trên Frontend. Thay vào đó, Backend sinh token có hạn dùng dựa trên User Session.
decryption_key chỉ tồn tại trong closure phạm vi của Web Worker / Canvas Render Engine. Ngay khi video kết thúc hoặc đóng tab, khóa này sẽ bị hủy ngay lập tức mà không để lại bất kỳ dấu vết nào trong Browser Cache.
JavaScript API Reference & Phím Tắt
Tài liệu tham chiếu lập trình toàn diện của VSNX Web Player SDK v2.4. Hệ thống cung cấp đầy đủ 10 nhóm phương thức điều khiển Canvas giải mã trực tiếp trong RAM, hỗ trợ quản lý khóa AES-256 động, danh sách phát mini, phụ đề đa ngôn ngữ, chụp ảnh canvas 1:1 và hệ thống phím tắt chuyên nghiệp.
7.1 Khởi Tạo Player (Constructor & Options)
Cú pháp khởi tạo đối tượng new VsnxPlayer(options) nhận đối tượng cấu hình toàn diện để kiểm soát canvas, nguồn video, giải mã và hiển thị watermark.
| Tùy Chọn | Kiểu Dữ Liệu | Mặc Định | Mô Tả Chi Tiết |
|---|---|---|---|
| container | string | HTMLElement | Bắt buộc | CSS Selector (ví dụ "#vsnx-viewport") hoặc phần tử DOM chứa Canvas Player. |
| src | string | Bắt buộc | Đường dẫn URL trực tiếp hoặc tương đối tới tệp nhị phân .vsnx đã mã hóa. |
| credentials | string | "" | Mật khẩu hoặc chuỗi SHA-256 dùng để giải mã luồng AES-256 CTR trực tiếp trong RAM. |
| autoplay | boolean | false | Tự động bắt đầu phát ngay khi phân tích xong Header nhị phân (tuân thủ chính sách trình duyệt). |
| loop | boolean | false | Tự động tua lại khung hình đầu tiên và tiếp tục phát khi đến cuối video. |
| volume | number | 1.0 | Mức âm lượng khởi tạo ban đầu trong khoảng từ 0.0 (câm) đến 1.0 (lớn nhất). |
| playbackRate | number | 1.0 | Tốc độ phát ban đầu (hỗ trợ dải tốc độ từ 0.25x đến 3.0x). |
| watermark | object | null | Cấu hình Watermark động chống quay màn hình: { text, dynamic, interval, opacity, fontSize }. |
| subtitles | Array<Track> | [] | Mảng các track phụ đề khởi tạo: [{ id, label, lang, default, cues }]. |
| playlist | Array<Item> | [] | Danh sách các bài giảng đa video trong khóa học: [{ title, src, credentials }]. |
| controls | object | defaultConfig | Tùy biến hiển thị/ẩn các nút trên thanh điều khiển giao diện. |
const player = new VsnxPlayer({
container: '#video-container',
src: 'https://cdn.example.com/courses/bai_01.vsnx',
credentials: 'M4tKh4uGiaiMa2026',
autoplay: false,
loop: false,
volume: 0.85,
playbackRate: 1.0,
watermark: {
text: 'HV: Nguyễn Văn A • ID: 10892',
dynamic: true,
interval: 4000,
opacity: 0.3
}
});
7.2 Danh Mục Phương Thức Điều Khiển Chi Tiết (10 Nhóm API)
1. Điều Khiển Phát & Tua (Playback & Seeking)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.play() | None | Promise<void> | Bắt đầu giải mã nhị phân và phát luồng video/audio trên Canvas. |
| player.pause() | None | void | Tạm dừng phát, giữ nguyên khung hình Canvas và ngừng audio context. |
| player.togglePlay() | None | void | Đảo trạng thái phát giữa Play và Pause. |
| player.seek(seconds) | seconds: number | void | Tua chính xác đến thời điểm seconds với độ trễ siêu thấp dưới 8ms. |
| player.skip(offset) | offset: number | void | Nhảy tới hoặc lùi một khoảng thời gian cụ thể (ví dụ +10, -10, +5, -5 giây). |
2. Điều Khiển Âm Thanh (Audio Controls)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.setVolume(level) | level: number (0.0 - 1.0) | void | Đặt mức âm lượng tuyến tính cho Web Audio GainNode. |
| player.getVolume() | None | number | Lấy giá trị âm lượng hiện hành trong khoảng 0.0 đến 1.0. |
| player.toggleMute() | None | boolean | Chuyển đổi trạng thái bật/tắt tiếng. Trả về true nếu đang tắt tiếng. |
3. Tốc Độ Phát & Hiển Thị Canvas (Playback Rate & Canvas)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.setPlaybackRate(rate) | rate: number (0.25 - 3.0) | void | Điều chỉnh tốc độ phát mượt mà từ 0.25x đến 3.0x, giữ nguyên cao độ âm thanh (pitch preservation). |
| player.getPlaybackRate() | None | number | Lấy giá trị tốc độ phát hiện thời của luồng video (mặc định: 1.0). |
| player.toggleFlip() | None | void | Lật ngang khung hình video Canvas theo chiều gương (Mirror Flip), tối ưu cho tập luyện thể thao / múa / giảng dạy. |
4. Phụ Đề Đa Ngôn Ngữ & Quản Lý Track (Subtitles API)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.addSubtitleTrack(track) | track: object | void | Thêm track phụ đề động dạng { id, label, lang, cues: [{ start, end, text }] }. |
| player.setSubtitleTrack(trackId) | trackId: string | void | Kích hoạt track phụ đề theo ID (ví dụ 'vi', 'en') hoặc truyền 'none' để tắt. |
| player.getSubtitleTracks() | None | Array<Track> | Lấy danh sách tất cả các track phụ đề đã được đăng ký trong player. |
| player.getCurrentSubtitleTrack() | None | Track | null | Lấy đối tượng track phụ đề hiện đang được kích hoạt vẽ trên Canvas. |
| player.toggleSubtitles() | None | void | Bật hoặc tắt nhanh hiển thị phụ đề hiện hành. |
5. Danh Sách Phát Mini Đa Bài Giảng (Playlist API)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.setPlaylist(items) | items: Array<Item> | void | Thiết lập danh sách phát đa bài giảng kèm thông tin mã hóa: [{ title, src, credentials }]. |
| player.next() | None | void | Chuyển sang phát bài giảng kế tiếp trong danh sách phát hiện tại. |
| player.prev() | None | void | Quay lại bài giảng liền trước trong danh sách phát. |
| player.playIndex(index) | index: number | void | Phát bài giảng tại chỉ mục chỉ định index (chỉ số tính từ 0). |
| player.togglePlaylist() | None | void | Đóng hoặc mở ngăn trượt hiển thị danh sách bài giảng (Playlist Overlay Drawer). |
6. Mật Khẩu Giải Mã & Bộ Đệm Nhị Phân (Security & Buffer)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.setCredentials(key) | key: string | void | Truyền mật khẩu giải mã AES-256 động vào RAM để giải phóng luồng đang bị khóa. |
| player.load(src, credentials) | src: string, key?: string | Promise<void> | Nạp luồng video .vsnx mới kèm mật khẩu giải mã tùy chọn mà không cần reload trang. |
| player.getLoadedProgress() | None | number (0.0 - 1.0) | Lấy tỷ lệ phần trăm khối nhị phân video đã được tải vào RAM đệm. |
| player.setLoadedProgress(pct) | pct: number (0.0 - 1.0) | void | Cập nhật vị trí thanh tiến độ tải đệm trên thanh timeline người dùng. |
7. Tiện Ích Giao Diện, Snapshot & PiP (UI, Snapshot & Utilities)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.takeSnapshot() | None | string (DataURL) | Trích xuất khung hình Canvas hiện tại thành tệp ảnh PNG độ phân giải gốc 1:1, tự động kích hoạt tải xuống. |
| player.togglePip() | None | Promise<void> | Bật hoặc thoát chế độ xem thu nhỏ hình trong hình (Picture-in-Picture). |
| player.toggleFullscreen() | None | void | Chuyển đổi chế độ toàn màn hình (Fullscreen) của phần tử container Canvas. |
| player.toggleLoop() | None | boolean | Bật hoặc tắt chế độ phát lặp lại vô tận (Loop), trả về trạng thái lặp mới. |
| player.toggleStats() | None | void | Hiển thị hoặc ẩn bảng thông số kỹ thuật thời gian thực HUD (FPS, Drop frames, Bitrate, RAM). |
| player.setLanguage(lang) | lang: 'vi' | 'en' | void | Thay đổi ngôn ngữ hiển thị của tooltip và menu thanh điều khiển. |
8. Tùy Biến Nút Điều Khiển (Controls Configuration)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.setControlVisibility(name, show) | name: string, show: boolean | void | Ẩn hoặc hiện từng nút điều khiển cụ thể ('play', 'volume', 'speed', 'subtitles', 'snapshot', 'pip', 'fullscreen', 'flip'). |
| player.setControlsConfig(config) | config: object | void | Cập nhật hàng loạt trạng thái bật/tắt của tất cả các nút điều khiển trên thanh công cụ. |
| player.getControlsConfig() | None | object | Lấy đối tượng cấu hình hiển thị hiện tại của thanh điều khiển. |
| player.resetControlsConfig() | None | void | Khôi phục hiển thị đầy đủ tất cả các nút điều khiển về trạng thái chuẩn ban đầu. |
9. Hủy & Giải Phóng Tài Nguyên (Lifecycle & Cleanup)
| Phương Thức | Tham Số | Trả Về | Mô Tả Chức Năng |
|---|---|---|---|
| player.destroy() | None | void | Dừng toàn bộ luồng Web Worker, giải phóng WebGL / 2D Canvas context, xóa khóa AES-256 khỏi RAM và gỡ bỏ tất cả Event Listeners. |
7.3 Sự Kiện & Callbacks (Player Events)
Lắng nghe các sự kiện vòng đời và trạng thái phát bằng phương thức player.on(eventName, callback) hoặc truyền trực tiếp trong options.
| Tên Sự Kiện | Tham Số Callback | Thời Điểm Kích Hoạt |
|---|---|---|
| onReady | None | Kích hoạt khi Header VSNX được giải mã thành công và khung hình đầu tiên đã sẵn sàng. |
| onPlay | None | Kích hoạt khi luồng phát bắt đầu chạy hoặc tiếp tục phát sau khi pause. |
| onPause | None | Kích hoạt khi người dùng hoặc hệ thống tạm dừng phát video. |
| onTimeUpdate | (currentTime, duration) | Kích hoạt liên tục theo thời gian thực (tối đa 60 FPS) khi vị trí phát thay đổi. |
| onProgress | (bufferedRatio) | Kích hoạt khi một khối chunk dữ liệu nhị phân mới được nạp vào RAM (giá trị 0.0 đến 1.0). |
| onEnded | None | Kích hoạt khi phát đến khung hình cuối cùng của video (nếu không bật thuộc tính loop). |
| onError | (error: { code, message }) | Kích hoạt khi xảy ra lỗi giải mã sai khóa, lỗi mạng kết nối hoặc tệp tin bị hỏng. |
7.4 Danh Mục Phím Tắt Bàn Phím Toàn Diện (Keyboard Shortcuts)
VSNX Web Player tích hợp sẵn hệ thống phím tắt chuyên nghiệp theo tiêu chuẩn phát video quốc tế, giúp người học thao tác cực nhanh mà không cần chạm chuột:
| Phím Tắt | Tên Thao Tác | Mô Tả Hành Động Chi Tiết |
|---|---|---|
| Space hoặc K | Phát / Tạm dừng | Bắt đầu hoặc tạm dừng phát video tức thời mà không giật lag khung hình. |
| ← / → | Tua ±5 giây | Tua lùi hoặc tiến 5 giây với độ trễ phản hồi dưới 8ms. |
| J / L | Tua ±10 giây | Tua nhanh lùi 10 giây (J) hoặc tiến 10 giây (L). |
| ↑ / ↓ | Âm lượng ±5% | Tăng hoặc giảm âm lượng từng bước 5% với thông báo HUD trực quan. |
| M | Bật / Tắt âm thanh | Tắt tiếng (Mute) hoặc mở lại âm thanh ở mức âm lượng trước đó. |
| F | Toàn màn hình | Chuyển đổi phóng to toàn màn hình Canvas hoặc trở về chế độ khung nhỏ. |
| P | Cửa Sổ Nổi (Picture-in-Picture) | Bật/tắt chế độ xem thu nhỏ nổi trên mọi cửa sổ làm việc khác. |
| S | Chụp ảnh màn hình | Chụp khung hình Canvas hiện tại và tải xuống tệp PNG siêu nét tức thì. |
| > / < | Tốc độ phát ±0.25x | Tăng hoặc giảm tốc độ phát (Shift + . hoặc Shift + ,) trong dải 0.25x - 3.0x. |
| D | Chuyển đổi phụ đề | Luân chuyển nhanh qua các ngôn ngữ phụ đề hoặc tắt phụ đề. |
| I | HUD Thống kê kỹ thuật | Hiển thị thông số FPS render thực tế, tỷ lệ dropped frames và bộ đệm RAM. |
| 0 – 9 | Nhảy theo % thời lượng | Nhảy trực tiếp đến vị trí từ 0% (đầu video) đến 90% tổng thời lượng. |
| Home / End | Đầu / Cuối video | Tua về khung hình đầu tiên hoặc nhảy đến khung hình kết thúc video. |
| Chuột phải | Menu chống tải trộm | Chặn hoàn toàn menu mặc định của trình duyệt; hiển thị menu bảo mật VSNX bản quyền. |
Bảng Mã Lỗi & Xử Lý Sự Cố (Troubleshooting)
Tệp tin không phải định dạng VSNX hợp lệ hoặc tệp đã bị hư hỏng trong quá trình tải xuống từ máy chủ CDN.
Mật khẩu hoặc Session Token giải mã không đúng. Vui lòng kiểm tra lại chuỗi khóa truyền vào player.load(url, key).
Đảm bảo máy chủ Cloudflare / S3 cấu hình Header: Access-Control-Allow-Origin: * và Access-Control-Allow-Headers: Range.