转载 前置/API 工具 PurpleMusic 1.0.0

[MD]
## 简介

PurpleMusic 是一款基于 Simple Voice Chat API 构建的 Paper/Folia 插件，可让管理人员向玩家串流播放真实音频文件（WAV、MP3、FLAC），创建播放队列与播放列表，并在任意位置设置持久化音乐区域。

# PurpleMusic

PurpleMusic 是一款基于 [Simple Voice Chat](https://modrinth.com/plugin/simple-voice-chat) API 构建的 Paper/Folia 插件，可让管理人员向玩家串流播放真实音频文件（WAV、MP3、FLAC），创建播放队列与播放列表，并在任意位置设置持久化音乐区域。

## 功能

- **直接播放**：向单个玩家、多名玩家或全部在线玩家播放音轨。
- **播放队列**：提供玩家个人队列和全局队列；每首音轨播放结束后会自动播放下一首。
- **播放列表**：可创建具名且持久化保存的播放列表，支持四种播放模式：
- `SEQUENTIAL`：按顺序播放一次。
- `LOOP`：无限循环整个播放列表。
- `LOOP_ONE`：无限循环当前音轨。
- `SHUFFLE`：无限随机播放列表中的音轨。
- **音乐区域**：可在指定位置创建具有可配置半径的持久化球形区域。每个区域可播放单首音轨或播放列表，并可选择持续播放，或按固定间隔播放（两次播放之间间隔 X 秒）。
- **下载音频**：管理员可通过 URL 直接下载 `.wav`、`.mp3`、`.flac` 格式的音频文件，并保存至 `plugins/PurpleMusic/musicdata/`。

## 运行要求

- Paper 1.21 或更高版本
- Simple Voice Chat（服务端与客户端）2.6.0 或更高版本

## 命令

所有命令同样可使用别名 `/pmusic` 和 `/pm`。

| 命令 | 说明 |
| --- | --- |
| `/pm download <url> <filename>` | 将音频文件下载至 `musicdata/` |
| `/pm list` | 列出 `musicdata/` 中的所有音轨 |
| `/pm play <player> <track>` | 向单个玩家播放音轨 |
| `/pm playall <track>` | 向全部在线玩家播放音轨 |
| `/pm stop <player\|all>` | 停止指定玩家或所有玩家的播放 |
| `/pm queue add <player\|all> <track>` | 将音轨加入播放队列 |
| `/pm queue clear <player\|all>` | 清空播放队列 |
| `/pm queue list <player\|all>` | 查看播放队列内容 |
| `/pm queue skip <player\|all>` | 跳过当前音轨 |
| `/pm playlist create <name>` | 创建空播放列表 |
| `/pm playlist delete <name>` | 删除播放列表 |
| `/pm playlist add <name> <track>` | 将音轨添加到播放列表 |
| `/pm playlist remove <name> <track>` | 从播放列表移除音轨 |
| `/pm playlist mode <name> <mode>` | 设置播放列表模式 |
| `/pm playlist list` | 列出所有播放列表 |
| `/pm playlist show <name>` | 查看指定播放列表中的音轨 |
| `/pm playlist play <player> <name>` | 向单个玩家播放播放列表 |
| `/pm playlist playall <name>` | 向全部在线玩家播放播放列表 |
| `/pm zone create <name> <track\|playlist> <source> <radius> <continuous\|interval> [seconds]` | 在当前位置创建音乐区域 |
| `/pm zone delete <name>` | 删除音乐区域 |
| `/pm zone list` | 列出所有音乐区域 |
| `/pm zone mode <name> <mode>` | 设置使用播放列表的音乐区域的播放模式 |
| `/pm reload` | 重载配置、播放列表和音乐区域 |

## 权限

每条命令都会检查对应的细分权限：

`purplemusic.download`、`purplemusic.play`、`purplemusic.stop`、`purplemusic.queue`、`purplemusic.playlist`、`purplemusic.zone`、`purplemusic.list`、`purplemusic.reload`。

父权限 `purplemusic.*` 可授予以上全部权限。所有权限默认值均为 `op`。

## 数据目录结构

```
plugins/PurpleMusic/
config.yml # global settings
playlists.yml # named playlists (auto-managed)
zones.yml # music zones (auto-managed)
musicdata/ # all audio files (wav / mp3 / flac)
```

配置项 `subdirectory-depth` 用于控制 `musicdata/` 内文件的最大嵌套层级，可设为 `none`、`single` 或 `unrestricted`。

## 源代码

[/MD]