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

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 } from "@ziplayer/extension";
2
3const lrc = new lyricsExt(null, {
4	includeSynced: true,
5	autoFetchOnTrackStart: true,
6	sanitizeTitle: true,
7});
8
9const manager = new PlayerManager({
10  extensions: [
11  lrc,
12   new voiceExt(null, { client, lang: "en-US", minimalVoiceMessageDuration: 1 })
13  ]
14});
15
16const player = manager.create(message.guild.id, {
17	userdata: {
18		channel: message.channel,
19	},
20	extensions: ["lyricsExt","voiceExt"],
21});
22
23manager.on("lyricsCreate", (_player, track, result) => {
24	if (result.synced) {
25		console.log("[LRC]
26" + result.synced.slice(0, 256) + (result.synced.length > 256 ? "..." : ""));
27	} else if (result.text) {
28		console.log("[TEXT]
29" + result.text.slice(0, 256) + (result.text.length > 256 ? "..." : ""));
30	} else {
31		console.log("No lyrics found");
32	}
33});
34
35manager.on("lyricsChange", async (_player, track, result) => {
36	// Per-line update when synced lyrics available
37	if (result.current) {
38		console.log(`[LINE ${result.lineIndex}] ${result.current}`);
39	} else if (result.text) {
40		// Fallback plain text chunk
41	}
42});
43manager.on("voiceCreate", async (plr, evt) => {
44	const userTag = evt.user?.tag || evt.userId;
45	const lowerContent = evt.content.toLowerCase();
46	console.log(lowerContent);
47});
48

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

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