Bắt đầu nhanh

Hướng dẫn từng bước để thiết lập ZiPlayer trong dự án Discord bot của bạn. Chỉ cần vài phút để có một music bot hoàn chỉnh!

Cài đặt packages

Cài đặt các package cần thiết cho dự án của bạn

1# Cài đặt packages cơ bản
2npm install ziplayer @ziplayer/plugin @ziplayer/extension @discordjs/voice discord.js
3
4# Hoặc sử dụng yarn
5yarn add ziplayer @ziplayer/plugin @ziplayer/extension @discordjs/voice discord.js
6
7# Hoặc sử dụng pnpm
8pnpm add ziplayer @ziplayer/plugin @ziplayer/extension @discordjs/voice discord.js

Tạo PlayerManager

Khởi tạo và cấu hình PlayerManager với các plugins

1import { PlayerManager } from "ziplayer";
2import { SoundCloudPlugin, YouTubePlugin, SpotifyPlugin } from "@ziplayer/plugin";
3import { voiceExt } from "@ziplayer/extension";
4
5const manager = new PlayerManager({
6  plugins: [
7    new SoundCloudPlugin(), 
8    new YouTubePlugin(), 
9    new SpotifyPlugin()
10  ],
11  extensions: [new voiceExt(null, { lang: "vi-VN" })],
12});

Tạo và sử dụng Player

Tạo player cho guild và bắt đầu phát nhạc

1const player = await manager.create(guildId, {
2  leaveOnEnd: true,
3  leaveTimeout: 30000,
4  userdata: { channel: textChannel },
5  extensions: ["voiceExt"],
6});
7
8await player.connect(voiceChannel);
9await player.play("Never Gonna Give You Up", userId);
10
11// Auto play & playlists
12player.queue.autoPlay(true);
13await player.play("https://www.youtube.com/playlist?list=PL123", userId);

Xử lý Events

Lắng nghe và xử lý các sự kiện của player

1player.on("willPlay", (player, track) => {
2  console.log("Up next:", track.title);
3});
4
5player.on("trackStart", (player, track) => {
6  console.log("Now playing:", track.title);
7});
8
9player.on("trackEnd", (player, track) => {
10  console.log("Finished:", track.title);
11});

Bước tiếp theo

Player & Manager

Tìm hiểu chi tiết về Player và PlayerManager APIs

Xem tài liệu

Queue & Controls

Khám phá các tính năng điều khiển queue và phát nhạc

Xem tài liệu

Events

Tìm hiểu cách xử lý events và tương tác với player

Xem tài liệu

💡 Mẹo hữu ích

Sử dụng TypeScript

ZiPlayer được viết hoàn toàn bằng TypeScript, cung cấp type safety và IntelliSense tốt nhất.

Error Handling

Luôn xử lý lỗi khi kết nối voice channel và phát nhạc để tránh crash bot.

Memory Management

Sử dụng leaveOnEnd và leaveTimeout để tự động dọn dẹp player khi không cần thiết.

Performance

Chỉ load các plugins cần thiết để tối ưu hóa hiệu suất và giảm memory usage.

🔧 Troubleshooting

Bot không kết nối được voice channel

Kiểm tra các điều kiện sau:

  • • Bot có quyền kết nối voice channel
  • • Bot có quyền nói trong voice channel
  • • Voice channel không bị giới hạn
  • • Bot đã online và sẵn sàng

Lỗi "No audio source found"

Có thể do:

  • • Plugin không được cài đặt đúng cách
  • • API key không hợp lệ (YouTube, Spotify)
  • • URL không được hỗ trợ bởi plugin
  • • Kết nối mạng có vấn đề

Bot bị crash khi phát nhạc

Thử các giải pháp:

  • • Thêm try-catch cho tất cả async operations
  • • Kiểm tra memory usage và cleanup players
  • • Cập nhật dependencies lên phiên bản mới nhất
  • • Kiểm tra logs để tìm lỗi cụ thể