mvsep-cli 0.1.4

# MVSEP CLI

命令行工具，用于与 MVSEP (Music Vocal Separation) API 交互，进行音轨分离。

## 安装

```bash
# 编译
cargo build --release

# 或直接运行
./run.sh <command>
```

## 快速开始

```bash
# 1. 设置 API Token
./target/release/mvsep-cli config set-token <your_token>

# 2. 设置代理（可选，如需翻墙）
./target/release/mvsep-cli config set-proxy-port 7897

# 3. 测试连接
./target/release/mvsep-cli test

# 4. 搜索想用的算法
./target/release/mvsep-cli create audio.wav -l karaoke

# 5. 查看算法模型选项
./target/release/mvsep-cli models -i 49

# 6. 创建任务（指定算法和模型）
./target/release/mvsep-cli create audio.wav -t 49 --opt1 5 --opt2 0 --wait -o ./output
```

## 命令

### 常用命令

| 命令 | 说明 |
|------|------|
| `test` | 测试 API 连接 |
| `version` | 显示版本信息 |
| `create <file>` | 创建分离任务 |
| `run <file>` | 完整流程（创建 + 等待 + 下载） |
| `status <hash>` | 查看任务状态 |
| `wait <hash>` | 等待任务完成 |
| `download <hash>` | 下载结果 |
| `queue` | 查看队列信息 |
| `history` | 查看任务历史 |

### 查询命令

| 命令 | 说明 |
|------|------|
| `list` | 列出所有算法和格式 |
| `list --search <keyword>` | 搜索算法 |
| `list --popular` | 显示热门算法 |
| `list --formats` | 显示输出格式 |
| `list --models <id>` | 查看算法的模型选项 |
| `list --start <level>` | 设置搜索起始层级 |
| `list --depth <N>` | 设置递归深度 |
| `list --match <positive\|negative>` | 设置匹配模式 |
| `algorithms` | 列出算法 |
| `algorithms -i <id>` | 查看算法详情 |
| `models -i <id>` | 查看算法模型选项 |
| `models -l [keyword]` | 列出算法（可选搜索） |

### 配置命令

| 命令 | 说明 |
|------|------|
| `config show` | 显示配置 |
| `config set-token <token>` | 设置 API Token |
| `config set-mirror <main\|mirror>` | 设置镜像服务器 |
| `config set-proxy-mode <system\|manual\|none>` | 设置代理模式 |
| `config set-proxy-host <host>` | 设置代理主机 |
| `config set-proxy-port <port>` | 设置代理端口 |
| `config set-output-dir <dir>` | 设置输出目录 |
| `config set-output-format <id>` | 设置默认输出格式 |
| `config set-interval <seconds>` | 设置轮询间隔 |

## 使用示例

### 查找算法

```bash
# 列出所有算法
mvsep-cli list

# 显示热门算法
mvsep-cli list --popular

# 搜索特定算法
mvsep-cli list --search karaoke
mvsep-cli list --search frazer
mvsep-cli list --search "vocal remover"

# 查看算法模型选项
mvsep-cli list --models 49
mvsep-cli models -i 49
```

### 搜索系统

本工具采用层级搜索系统：

#### 层级结构
- **Level 1**: 算法组 (如 "Vocals / Instrumental", "Drums, Bass and Synth")
- **Level 2**: 具体算法 (如 "MVSep Karaoke", "MDX-B Karaoke")
- **Level 3**: 模型选项 (add_opt1, add_opt2, add_opt3 - 平行选项)

#### 搜索参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--start` | 起始点 | `0` (当前层级) |
| `--depth` | 递归深度 | `1` |
| `--match` | 匹配模式 | `positive` |

#### 起始点 (`--start`)

| 值 | 含义 |
|----|------|
| `0` 或 `.` | 当前层级 |
| `-1` | 父级 |
| `+1` | 子级 |
| `$root` | 根层级 (算法组) |
| `1`, `2`, `3` | 具体层级号 |

#### 递归深度 (`--depth`)

| 值 | 含义 |
|----|------|
| `1` | 仅当前层级 |
| `+N` | 向下展开 N 层 |
| `-N` | 向上展开 N 层 |
| `+inf` | 无限向下 |
| `-inf` | 无限向上 |

#### 匹配模式 (`--match`)

| 模式 | 行为 |
|------|------|
| `positive` | 模糊匹配 (包含匹配项) |
| `negative` | 精准匹配 (排除匹配项) |

#### 搜索示例

```bash
# 搜索算法 (默认显示算法)
mvsep-cli list --search karaoke

# 搜索并展开模型选项 (显示 Level 2 + Level 3)
mvsep-cli list --search karaoke --depth +2

# 从根目录开始搜索，展开所有层级
mvsep-cli list --search karaoke --start $root --depth +2

# 排除关键词
mvsep-cli list --search karaoke --match negative

# 只显示算法组
mvsep-cli list --start 1

# 显示算法组和算法 (depth 2)
mvsep-cli list --start 1 --depth +2
```

### 创建任务

```bash
# 基本用法（需要指定 --opt1 模型）
mvsep-cli create audio.wav -t 49 --opt1 5

# 完整参数
mvsep-cli create audio.wav \
  -t 49 \           # 算法 ID
  --opt1 5 \        # 模型类型
  --opt2 0 \        # 额外选项
  --opt3 0 \        # 额外选项 3
  -f 1 \            # 输出格式 (1=WAV)
  -o ./output       # 输出目录

# 发布到演示页面
mvsep-cli create audio.wav -t 49 --opt1 5 --demo

# 设置超时时间（秒）
mvsep-cli create audio.wav -t 49 --opt1 5 --timeout 600 --wait
```

### 等待完成并下载

```bash
# 方式1: 使用 --wait
mvsep-cli create audio.wav -t 49 --opt1 5 --wait -o ./output

# 方式2: 使用 run 命令
mvsep-cli run audio.wav -t 49 --opt1 5 -o ./output

# 方式3: 分步执行
mvsep-cli wait <hash>
mvsep-cli download <hash> -o ./output

# 指定等待超时
mvsep-cli wait <hash> --timeout 600
```

### 下载特定文件

```bash
# 下载所有结果
mvsep-cli download <hash> -o ./output

# 下载指定索引的文件
mvsep-cli download <hash> -o ./output --index 0
```

### 便捷功能

在 `create` 或 `run` 命令中，使用 `-l` 或 `--list` 可以直接搜索算法，无需另开命令：

```bash
mvsep-cli create audio.wav -l              # 列出所有算法
mvsep-cli create audio.wav -l karaoke   # 搜索 karaoke
mvsep-cli run audio.wav -l frazer       # 搜索 frazer
```

## 输出格式

| ID | 格式 |
|----|------|
| 0 | MP3 (320 kbps) |
| 1 | WAV (16 bit) |
| 2 | FLAC (16 bit) |
| 3 | M4A (lossy) |
| 4 | WAV (32 bit) |
| 5 | FLAC (24 bit) |

## 配置优先级

环境变量 > 配置文件 (~/.mvsep_cli_config)

### 环境变量

- `MVSEP_API_TOKEN` - API Token
- `MVSEP_API_URL` - API 地址
- `MVSEP_OUTPUT_DIR` - 输出目录
- `MVSEP_POLL_INTERVAL` - 轮询间隔
- `PROXY_HOST` - 代理主机
- `HTTP_PROXY_PORT` / `HTTPS_PROXY_PORT` - 代理端口

### 代理模式

本工具支持三种代理模式：

| 模式 | 说明 |
|------|------|
| `system` | 使用系统代理 (默认) |
| `manual` | 使用手动设置的代理 |
| `none` | 不使用代理 |

设置代理模式：
```bash
mvsep-cli config set-proxy-mode system   # 使用系统代理 (默认)
mvsep-cli config set-proxy-mode manual  # 使用手动代理
mvsep-cli config set-proxy-mode none    # 不使用代理
```

手动代理配置：
```bash
mvsep-cli config set-proxy-host 127.0.0.1
mvsep-cli config set-proxy-port 7897
```

## 注意事项

1. **必须指定模型**: 使用 `--opt1` 指定模型，否则任务会失败
2. 使用 `list --models <id>` 或 `models -i <id>` 查看可用模型
3. 某些算法没有额外选项，不需要指定 `--opt1`

## 构建

```bash
cargo build --release
# 输出: target/release/mvsep-cli-test
```

## License

MIT