ZiPlayer Icon
ZiPlayer
Discord Audio Player

Player & Manager

Tìm hiểu cách sử dụng PlayerManager để quản lý players và Player để điều khiển phát nhạc trong Discord bot của bạn.

Multi-source Support

Hỗ trợ nhiều nguồn âm thanh thông qua hệ thống plugin

  • YouTube
  • SoundCloud
  • Spotify
  • Direct URLs
  • Playlists

Rich Configuration

Cấu hình linh hoạt cho từng player và manager

  • Volume control
  • Auto-leave
  • Queue limits
  • User data

Event-driven

Hệ thống events mạnh mẽ để tương tác với player

  • Track events
  • Queue events
  • Error handling
  • State changes

PlayerManager

PlayerManager là trung tâm quản lý tất cả players trong bot của bạn. Nó cho phép bạn tạo, cấu hình và quản lý nhiều players cho các guild khác nhau.

1import { PlayerManager } from "ziplayer";
2import { SoundCloudPlugin, YouTubePlugin, SpotifyPlugin } from "@ziplayer/plugin";
3
4const manager = new PlayerManager({
5  plugins: [
6    new SoundCloudPlugin(), 
7    new YouTubePlugin(), 
8    new SpotifyPlugin()
9  ],
10  // Cấu hình tùy chọn
11  defaultVolume: 50,
12  maxQueueSize: 100,
13  leaveOnEmpty: true,
14  leaveOnEmptyCooldown: 30000,
15});

Tính năng chính

  • Quản lý nhiều players cho các guild khác nhau
  • Tự động cleanup players không hoạt động
  • Hỗ trợ plugin system mạnh mẽ
  • Cấu hình mặc định cho tất cả players

API Methods

create(guildId, options)

Tạo player mới cho guild

get(guildId)

Lấy player theo guild ID

destroy(guildId)

Xóa player khỏi manager

Player

Player là đối tượng chính để điều khiển phát nhạc trong một guild. Mỗi guild có thể có một player riêng biệt.

Tạo Player

1const player = await manager.create(guildId, {
2  // Cấu hình player
3  leaveOnEnd: true,
4  leaveTimeout: 30000,
5  userdata: { 
6    channel: textChannel,
7    guild: guild 
8  },
9  extensions: ["voiceExt"],
10  // Cấu hình queue
11  queue: {
12    autoPlay: false,
13    shuffle: false,
14    repeat: "off"
15  }
16});

Sử dụng Player

1// Kết nối voice channel
2await player.connect(voiceChannel);
3
4// Phát nhạc
5await player.play("Never Gonna Give You Up", userId);
6await player.play("https://www.youtube.com/watch?v=dQw4w9WgXcQ", userId);
7
8// Điều khiển phát nhạc
9player.pause();
10player.resume();
11player.stop();
12player.skip();
13player.loop("off"); //"off" | "track" | "queue"
14
15// Điều khiển volume
16player.setVolume(75);
17
18// Thoát khỏi voice channel
19player.destroy(); // Ngắt kết nối hoàn toàn, không tự kết nối lại

Destroy Player

1// Destroy player - ngắt kết nối hoàn toàn
2player.destroy();
3
4// Khi destroy player:
5// 1. Dừng audio player
6// 2. Ngắt kết nối voice channel
7// 3. Xóa queue và plugins
8// 4. Gọi onDestroy() cho tất cả extensions
9// 5. Lavalink extension sẽ:
10//    - Ngắt kết nối hoàn toàn với Lavalink server
11//    - Không tự động kết nối lại
12//    - Cleanup tất cả resources
13// 6. Emit "playerDestroy" event
14// 7. Xóa tất cả event listeners
15
16// Lưu ý: Sau khi destroy, player không thể sử dụng lại
17// Cần tạo player mới nếu muốn phát nhạc lại

Events

1// Lắng nghe events
2player.on("trackStart", (player, track) => {
3  console.log("Bắt đầu phát:", track.title);
4});
5
6player.on("trackEnd", (player, track) => {
7  console.log("Kết thúc:", track.title);
8});
9
10player.on("queueEnd", (player) => {
11  console.log("Hết queue, tự động thoát...");
12});
13
14player.on("error", (player, error) => {
15  console.error("Lỗi player:", error);
16});
17
18/* Player Events
19	debug: [message: string, ...args: any[]];
20	willPlay: [track: Track, upcomingTracks: Track[]];
21	trackStart: [track: Track];
22	trackEnd: [track: Track];
23	queueEnd: [];
24	playerError: [error: Error, track?: Track];
25	connectionError: [error: Error];
26	volumeChange: [oldVolume: number, newVolume: number];
27	queueAdd: [track: Track];
28	queueAddList: [tracks: Track[]];
29	queueRemove: [track: Track, index: number];
30	playerPause: [track: Track];
31	playerResume: [track: Track];
32	playerStop: [];
33	playerDestroy: [];
34	ttsStart: [payload: { text?: string; track?: Track }];
35	ttsEnd: [];
36*/
37

Best Practices

Memory Management

  • Sử dụng leaveOnEnd để tự động thoát khi hết nhạc
  • Đặt leaveTimeout hợp lý (30-60 giây)
  • Xóa players không sử dụng bằng destroy()
  • Destroy() ngắt kết nối hoàn toàn, không tự kết nối lại

Error Handling

  • Luôn xử lý lỗi khi connect và play
  • Sử dụng try-catch cho các async operations
  • Lắng nghe error events để debug
  • Lavalink extension tự động cleanup khi destroy

Tiếp theo: Queue & Controls

Tìm hiểu cách sử dụng queue system và các điều khiển phát nhạc nâng cao.

Xem Queue & Controls