/playclara
Xin chào mọi người !
Clara muốn nghe nhạc cùng mọi người. Hãy nghe nhạc cùng nhau nhé :3

# Clara Bot - Mô tả & Hướng dẫn sử dụng

## 1. Giới thiệu tổng quan

**Clara** là một Discord bot được viết bằng ngôn ngữ C# (.NET 10), sử dụng thư viện Discord.NET. Bot được thiết kế với mục tiêu mang đến trải nghiệm giải trí âm nhạc và trò chuyện thông minh cho cộng đồng người dùng Discord.

- **Phiên bản:** 1.0.1
- **Ngôn ngữ lập trình:** C# (.NET 10)
- **Thư viện Discord:** Discord.NET
- **Thư viện âm nhạc:** Lavalink4NET
- **Tác giả:** Kim Tuấn
- **GitHub:** https://github.com/chlorinebot

## 2. Hệ thống lệnh

Tất cả lệnh của Clara đều sử dụng tiền tố `/` (slash command qua prefix `/`).

### 2.1. Lệnh hệ thống & thông tin

| Lệnh | Mô tả |
|------|-------|
| `/heyclara` hoặc `/help` | Hiển thị danh sách tất cả các lệnh hiện có của bot |
| `/infoclara` | Hiển thị thông tin về bot, phiên bản, tác giả, GitHub và liên kết donate |

### 2.2. Lệnh phát nhạc

| Lệnh | Mô tả |
|------|-------|
| `/playclara [link]` hoặc `/p [link]` | Phát nhạc từ YouTube vào kênh voice. Có thể nhập link YouTube hoặc từ khóa tìm kiếm |
| `/pauseclara` | Tạm dừng bài hát đang phát |
| `/resumeclara` | Tiếp tục phát nhạc sau khi tạm dừng |
| `/stopclara` | Dừng phát nhạc hoàn toàn và ngắt kết nối khỏi kênh voice |
| `/prevclara` | Lùi về bài trước trong playlist |
| `/nextclara` | Chuyển sang bài tiếp theo trong playlist |
| `/jumpclara [n]` | Nhảy tới bài số n trong playlist đang phát |
| `/showplaylistclara` | Hiển thị danh sách bài hát trong playlist hiện tại (phân trang, 10 bài/trang) |
| `/loopclara` hoặc `/loop` | Bật/tắt chế độ lặp lại toàn bộ playlist |
| `/infoplayclara` | Hiển thị thông tin chi tiết bài hát đang phát (tiêu đề, tác giả, thời lượng, thời gian đã phát) |

### 2.3. Lệnh kiểm tra hệ thống

| Lệnh | Mô tả |
|------|-------|
| `/pingclara` | Kiểm tra và hiển thị thông tin tài nguyên máy chủ bao gồm: CPU, RAM, độ trễ mạng (ping), tốc độ tải xuống và tốc độ tải lên. Mỗi chỉ số đi kèm đánh giá màu sắc (🟢 Tốt, 🟡 Trung bình, 🟠 Cận tệ, 🔴 Tệ) |

### 2.4. Lệnh Roleplay (Trò chuyện AI)

| Lệnh | Mô tả |
|------|-------|
| `/roleplayclara on` | Bật chế độ roleplay, cho phép trò chuyện với Clara bằng tin nhắn thường trong kênh |
| `/roleplayclara off` | Tắt chế độ roleplay cho kênh hiện tại |

Khi chế độ roleplay được bật, Clara sẽ tự động phản hồi mọi tin nhắn trong kênh (không phải lệnh bot) bằng AI, đóng vai một nhân vật fantasy dễ thương và thân thiện. Clara sử dụng Groq API với model Llama-3.3-70B-Versatile để tạo phản hồi tự nhiên bằng tiếng Việt.

## 3. Kiến trúc kỹ thuật

### 3.1. Cấu trúc module

Clara được tổ chức thành các module riêng biệt, dễ bảo trì:

- **GeneralModule** - Xử lý lệnh hệ thống, trợ giúp và thông tin bot
- **MusicModule** - Xử lý toàn bộ chức năng phát nhạc, playlist và các thao tác điều khiển phát
- **RoleplayModule** - Xử lý trò chuyện AI thông qua Groq API
- **HeartModule** - Xử lý kiểm tra tài nguyên hệ thống và tốc độ mạng
- **CommandHandler** - Quản lý tiền xử lý tin nhắn, điều phối lệnh và xử lý button tương tác

### 3.2. Các tính năng kỹ thuật nổi bật

- **Hệ thống Lavalink:** Clara kết nối tới server Lavalink (mặc định `http://127.0.0.1:2333`) để xử lý phát nhạc, đảm bảo hiệu suất cao và không gây lag cho máy chủ.
- **Tự động kết nối lại:** Bot có cơ chế tự động thử kết nối lại Discord (tối đa 500 lần retry) khi bị mất kết nối, đảm bảo uptime tối đa.
- **Xử lý playlist thông minh:** Hỗ trợ phát playlist YouTube với hàng đợi, phân trang, nhảy bài, lặp lại và tự động bỏ qua các bài bị giới hạn đăng nhập/độ tuổi.
- **Auto-disconnect:** Bot tự động ngắt kết nối khỏi voice khi playlist kết thúc hoặc gặp lỗi nghiêm trọng.
- **Rate limiting nhẹ:** Mỗi kênh roleplay có semaphore để tránh spam, đảm bảo chỉ một yêu cầu AI được xử lý tại một thời điểm.
- **Đánh giá tài nguyên thông minh:** Lệnh `/pingclara` đo CPU bằng Windows API, RAM bằng `GlobalMemoryStatusEx`, tốc độ mạng qua Cloudflare và HTTPBin.
- **Phân chia tin nhắn dài:** Nếu phản hồi AI quá dài (vượt giới hạn 1900 ký tự của Discord), tin nhắn sẽ được tự động chia nhỏ theo dòng.

## 4. Yêu cầu hệ thống

### 4.1. Phụ thuộc bắt buộc

- **.NET 10 SDK** hoặc cao hơn
- **Lavalink Server** chạy tại `http://127.0.0.1:2333` với password `youshallnotpass` (cấu hình mặc định)
- **Discord Bot Token** - được đọc từ biến môi trường `DISCORD_TOKEN`
- **Groq API Key** - cần thiết cho chức năng roleplay AI, đọc từ biến môi trường `GROQ_API_KEY` hoặc file `.env`

### 4.2. Gateway Intents được sử dụng

Clara yêu cầu các Discord Gateway Intents sau để hoạt động:

- `Guilds` - Truy cập thông tin server
- `GuildMessages` - Đọc tin nhắn trong server
- `MessageContent` - Đọc nội dung tin nhắn (cần thiết cho roleplay)
- `GuildVoiceStates` - Quản lý kênh voice

> **Lưu ý:** Intent `MessageContent` cần được bật trong Discord Developer Portal để bot có thể đọc nội dung tin nhắn.

## 5. Cấu hình & Biến môi trường

Các thông tin nhạy cảm (token, API key) được quản lý thông qua biến môi trường hoặc file `.env`:

| Biến | Mô tả | Bắt buộc |
|------|--------|----------|
| `DISCORD_TOKEN` | Token Discord Bot để xác thực với Discord API | Có |
| `GROQ_API_KEY` | API key của Groq để sử dụng AI chat (roleplay) | Có (cho roleplay) |

## 6. Cách sử dụng chi tiết

### 6.1. Phát nhạc đơn lẻ

```
/playclara https://www.youtube.com/watch?v=xxx
```
hoặc tìm kiếm bằng từ khóa:
```
/playclara tên bài hát
```

### 6.2. Phát playlist YouTube

```
/playclara https://www.youtube.com/playlist?list=xxx
```
Bot sẽ tự động tải toàn bộ playlist và phát lần lượt từng bài.

### 6.3. Điều khiển playlist

- Xem playlist: `/showplaylistclara` (có nút phân trang ⬅️ ➡️)
- Nhảy tới bài số 5: `/jumpclara 5`
- Chuyển bài tiếp: `/nextclara`
- Lùi bài trước: `/prevclara`
- Bật lặp: `/loopclara` (bật/tắt)

### 6.4. Trò chuyện với Clara

1. Bật roleplay: `/roleplayclara on`
2. Gửi tin nhắn bình thường (không có `/`) trong cùng kênh
3. Clara sẽ tự động trả lời với personality fantasy dễ thương
4. Tắt khi không cần: `/roleplayclara off`

### 6.5. Kiểm tra hệ thống

```
/pingclara
```
Bot sẽ hiển thị dashboard với các chỉ số: CPU, RAM, độ trễ ping, tốc độ tải xuống (Download), tốc độ tải lên (Upload).

## 7. Công nghệ sử dụng

| Thư viện/Công nghệ | Mục đích |
|---------------------|-----------|
| **Discord.NET** | Tương tác với Discord API |
| **Lavalink4NET** | Kết nối Lavalink để phát nhạc chất lượng cao |
| **Groq API (Llama-3.3-70B)** | Xử lý AI cho chế độ roleplay |
| **Figgle** | Hiển thị ASCII art banner khi khởi động |
| **Windows API (P/Invoke)** | Đo CPU sử dụng `GetSystemTimes` |
| **Cloudflare Speed Test** | Đo tốc độ tải xuống |
| **HTTPBin** | Đo tốc độ tải lên |
| **.NET 10** | Nền tảng runtime |

## 8. Xử lý lỗi thường gặp

### Lavalink chưa khởi động
- **Triệu chứng:** Bot online nhưng không phát được nhạc
- **Giải pháp:** Khởi động Lavalink server tại `http://127.0.0.1:2333` với password `youshallnotpass`

### YouTube yêu cầu đăng nhập/giới hạn tuổi
- **Triệu chứng:** Không phát được một số bài nhất định
- **Giải pháp:** Cấu hình youtube-plugin của Lavalink với cookies hoặc poToken + visitorData, sau đó restart Lavalink

### Roleplay không hoạt động
- **Triệu chứng:** Clara không trả lời tin nhắn thường
- **Giải pháp:** Kiểm tra biến môi trường `GROQ_API_KEY` đã được thiết lập đúng chưa

### Bot bị mất kết nối
- Bot sẽ tự động thử kết nối lại. Nếu không khôi phục sau nhiều lần thử, hãy kiểm tra token Discord và kết nối mạng.

## 9. Thông tin liên hệ & ủng hộ

- **GitHub:** https://github.com/chlorinebot
- **Tác giả:** Kim Tuấn
- **Donate:** https://i.pinimg.com/736x/1c/5c/5b/1c5c5beddb559e0f2b85b2f354ef75e1.jpg

---

> **Lưu ý bảo mật:** Không bao giờ chia sẻ Discord Token, Groq API Key hay bất kỳ thông tin nhạy cảm nào ra bên ngoài. Tất cả các API key và token nên được lưu trữ trong biến môi trường hoặc file `.env` (đã được thêm vào `.gitignore`).


Candy Lord

Clara bot nhạc hỗ trợ tiếng Việt

Vote cho Candy Lord

Bạn muốn hỗ trợ chúng tôi?