Extensions & Add-ons

Mở rộng chức năng player với hệ thống extensions mạnh mẽ. Thêm TTS, lyrics, và các tính năng tùy chỉnh.

Voice Extension

Speech recognizers với nhiều ngôn ngữ và giọng nói

Multi-language TTS
Voice selection
Ignore Bots
Auto attach connection

Lyrics Extension

Hiển thị lyrics tự động cho bài hát

Auto-fetch lyrics
Multiple sources
Language support
Embed display

Lavalink Extension

Kết nối với Lavalink server cho chất lượng âm thanh cao

High quality audio
Auto cleanup on destroy
No auto-reconnect
Resource management

Custom Extensions

Tạo extensions tùy chỉnh cho chức năng riêng

Custom logic
Event handling
API integration
Database support

Voice Extension

Thêm khả năng Text-to-Speech vào player để thông báo và tương tác với người dùng.

1import { voiceExt, lyricsExt, lavalinkExt } from "@ziplayer/extension";
2
3const lrc = new lyricsExt(null, {
4	includeSynced: true,
5	autoFetchOnTrackStart: true,
6	sanitizeTitle: true,
7});
8
9const lavalink = new lavalinkExt(null, {
10	// Lavalink configuration
11});
12
13const manager = new PlayerManager({
14  extensions: [
15    lrc,
16    new voiceExt(null, { client, lang: "en-US", minimalVoiceMessageDuration: 1 }),
17    lavalink
18  ]
19});
20
21const player = await manager.create(message.guild.id, {
22	userdata: {
23		channel: message.channel,
24	},
25	extensions: ["lyricsExt", "voiceExt", "lavalinkExt"],
26});
27
28// Khi destroy player, lavalink extension sẽ:
29// 1. Ngắt kết nối hoàn toàn với Lavalink server
30// 2. Không tự động kết nối lại
31// 3. Cleanup tất cả resources
32// 4. Gọi onDestroy() lifecycle method
33
34player.destroy(); // Lavalink extension tự động cleanup
35
36manager.on("lyricsCreate", (_player, track, result) => {
37	if (result.synced) {
38		console.log("[LRC]
39" + result.synced.slice(0, 256) + (result.synced.length > 256 ? "..." : ""));
40	} else if (result.text) {
41		console.log("[TEXT]
42" + result.text.slice(0, 256) + (result.text.length > 256 ? "..." : ""));
43	} else {
44		console.log("No lyrics found");
45	}
46});
47
48manager.on("lyricsChange", async (_player, track, result) => {
49	// Per-line update when synced lyrics available
50	if (result.current) {
51		console.log(`[LINE ${result.lineIndex}] ${result.current}`);
52	} else if (result.text) {
53		// Fallback plain text chunk
54	}
55});
56
57manager.on("voiceCreate", async (plr, evt) => {
58	const userTag = evt.user?.tag || evt.userId;
59	const lowerContent = evt.content.toLowerCase();
60	console.log(lowerContent);
61});
62

Configuration Options

lang - Ngôn ngữ TTS
voice - Giọng nói cụ thể
speed - Tốc độ nói (0.5-2.0)
pitch - Cao độ (-20 đến 20)

Use Cases

Thông báo bài hát mới
Hướng dẫn sử dụng
Thông báo lỗi
Tương tác với người dùng

Lavalink Extension

Lavalink extension cung cấp chất lượng âm thanh cao và quản lý kết nối tự động.

1import { voiceExt, lyricsExt, lavalinkExt } from "@ziplayer/extension";
2
3const lrc = new lyricsExt(null, {
4	includeSynced: true,
5	autoFetchOnTrackStart: true,
6	sanitizeTitle: true,
7});
8
9const lavalink = new lavalinkExt(null, {
10	// Lavalink configuration
11});
12
13const manager = new PlayerManager({
14  extensions: [
15    lrc,
16    new voiceExt(null, { client, lang: "en-US", minimalVoiceMessageDuration: 1 }),
17    lavalink
18  ]
19});
20
21const player = await manager.create(message.guild.id, {
22	userdata: {
23		channel: message.channel,
24	},
25	extensions: ["lyricsExt", "voiceExt", "lavalinkExt"],
26});
27
28// Khi destroy player, lavalink extension sẽ:
29// 1. Ngắt kết nối hoàn toàn với Lavalink server
30// 2. Không tự động kết nối lại
31// 3. Cleanup tất cả resources
32// 4. Gọi onDestroy() lifecycle method
33
34player.destroy(); // Lavalink extension tự động cleanup
35
36manager.on("lyricsCreate", (_player, track, result) => {
37	if (result.synced) {
38		console.log("[LRC]
39" + result.synced.slice(0, 256) + (result.synced.length > 256 ? "..." : ""));
40	} else if (result.text) {
41		console.log("[TEXT]
42" + result.text.slice(0, 256) + (result.text.length > 256 ? "..." : ""));
43	} else {
44		console.log("No lyrics found");
45	}
46});
47
48manager.on("lyricsChange", async (_player, track, result) => {
49	// Per-line update when synced lyrics available
50	if (result.current) {
51		console.log(`[LINE ${result.lineIndex}] ${result.current}`);
52	} else if (result.text) {
53		// Fallback plain text chunk
54	}
55});
56
57manager.on("voiceCreate", async (plr, evt) => {
58	const userTag = evt.user?.tag || evt.userId;
59	const lowerContent = evt.content.toLowerCase();
60	console.log(lowerContent);
61});
62

Tính năng chính

Chất lượng âm thanh cao
Tự động cleanup khi destroy
Không tự động kết nối lại
Quản lý resources hiệu quả

Destroy Behavior

Ngắt kết nối hoàn toàn với Lavalink server
Cleanup tất cả players và connections
Không tự động kết nối lại
Gọi onDestroy() lifecycle method

Tạo Custom Extension

Tạo extension tùy chỉnh để thêm chức năng riêng cho player.

1import { BaseExtension } from "@ziplayer/extension";
2
3export class CustomExtension extends BaseExtension {
4  name = "custom-extension";
5  
6  async active({ manager, player }) {
7    // Khởi tạo extension khi player được tạo
8    console.log("Custom extension activated for player:", player.guildId);
9    
10    // Lắng nghe events
11    player.on("trackStart", (track) => {
12      this.handleTrackStart(track);
13    });
14  }
15  
16  async inactive() {
17    // Cleanup khi extension bị vô hiệu hóa
18    console.log("Custom extension deactivated");
19  }
20  
21  private handleTrackStart(track) {
22    // Logic tùy chỉnh khi bắt đầu phát nhạc
23    console.log("Custom logic for track:", track.title);
24  }
25}

Tiếp theo: Examples

Xem các ví dụ thực tế và best practices để sử dụng ZiPlayer hiệu quả.

Xem Examples