metube/部署使用说明.md

# Tingdao.org yt-dlp Extractor 部署使用指南

这是一个为 yt-dlp 开发的扩展器，用于下载 tingdao.org 网站的音频内容。

## 🎯 功能特性

- ✅ 支持单个音频下载
- ✅ 支持完整播放列表下载（共8集）
- ✅ 备用音频源机制确保下载可靠性
- ✅ 完整元数据支持（标题、时间戳、作者等）
- ✅ 与 Metube 完全兼容
- ✅ 健壮的错误处理

## 📋 支持的URL格式

```
https://www.tingdao.org/dist/#/Media?device=mobile&id=11869
https://www.tingdao.org/dist/#/Media?id=11868
```

## 🚀 部署方式

### 方式一：Metube 插件系统（推荐）

这是最简单的部署方式，适合已有 Metube 环境的用户。

#### 1. 准备插件目录

```bash
# 在你的 Metube 目录中创建插件目录
mkdir -p plugins/tingdao
```

#### 2. 复制插件文件

```bash
# 复制插件到指定目录
cp -r metube_plugin/yt_dlp_plugins plugins/tingdao/
```

#### 3. 修改 Docker Compose 配置

在你的 `docker-compose.yml` 文件中添加 volume 映射：

```yaml
services:
  metube:
    image: alexta69/metube
    ports:
      - "8081:8081"
    volumes:
      - "./downloads:/downloads"
      - "./plugins:/app/.config/yt-dlp/plugins"  # 添加这行
    environment:
      - DOWNLOAD_DIR=/downloads
      - AUDIO_DOWNLOAD_DIR=/downloads/audio
```

#### 4. 重启 Metube

```bash
docker-compose down
docker-compose up -d
```

#### 5. 验证安装

在 Metube Web 界面中测试 tingdao.org 链接：
```
https://www.tingdao.org/dist/#/Media?device=mobile&id=11869
```

### 方式二：本地 yt-dlp 开发安装

适合开发者或需要自定义 yt-dlp 的用户。

#### 1. 克隆 yt-dlp 仓库

```bash
git clone https://github.com/yt-dlp/yt-dlp.git
cd yt-dlp
```

#### 2. 安装扩展器

```bash
# 复制扩展器文件
cp yt_dlp_extractor/tingdao.py yt_dlp/extractor/

# 注册扩展器
echo "from .tingdao import TingdaoIE" >> yt_dlp/extractor/_extractors.py
```

#### 3. 安装开发版本

```bash
pip install -e .
```

#### 4. 测试安装

```bash
yt-dlp --list-extractors | grep -i tingdao
```

## 📖 使用方法

### 在 Metube 中使用

1. 打开 Metube Web 界面 (通常是 http://localhost:8081)
2. 在 URL 输入框中粘贴 tingdao.org 链接
3. 选择音频格式和质量
4. 点击 "Add" 开始下载

### 在命令行中使用

#### 下载单个音频

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869"
```

#### 下载整个播放列表

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" --yes-playlist
```

#### 仅提取信息（不下载）

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" --dump-json
```

#### 选择备用源

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" -f backup
```

## 🔧 高级配置

### 自定义输出模板

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" \
  -o "%(uploader)s/%(playlist)s/%(playlist_index)02d - %(title)s.%(ext)s"
```

### 限制下载速度

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" \
  --limit-rate 1M
```

## 🐛 故障排除

### 常见问题

#### 1. 插件未被识别（重要）

**症状**: yt-dlp 提示 "Unsupported URL" 或 "Falling back on generic information extractor"

**原因**: yt-dlp 插件系统在某些环境下可能无法正确加载插件

**解决方案**: 使用直接安装方法

```bash
# 方法1: 直接复制到 yt-dlp 安装目录（推荐）
# 1. 找到 yt-dlp 安装位置
python -c "import yt_dlp; print(yt_dlp.__file__)"

# 2. 复制扩展器文件（替换为实际路径）
cp yt_dlp_extractor/tingdao.py /path/to/yt_dlp/extractor/

# 3. 注册扩展器
echo "from .tingdao import TingdaoIE" >> /path/to/yt_dlp/extractor/_extractors.py

# 4. 验证安装
yt-dlp --list-extractors | grep -i tingdao
```

**Metube 环境下的解决方案**:

```bash
# 在 Metube 目录下执行
# 1. 找到 pipenv 环境中的 yt-dlp 位置
pipenv run python -c "import yt_dlp; print(yt_dlp.__file__)"

# 2. 复制扩展器
cp yt_dlp_extractor/tingdao.py $(pipenv run python -c "import yt_dlp; import os; print(os.path.dirname(yt_dlp.__file__))")/extractor/

# 3. 注册扩展器
echo "from .tingdao import TingdaoIE" >> $(pipenv run python -c "import yt_dlp; import os; print(os.path.dirname(yt_dlp.__file__))")/extractor/_extractors.py
```

#### 2. "参数不完整" 错误

这通常表示网络问题或 API 暂时不可用。解决方法：
- 检查网络连接
- 稍后重试
- 检查 URL 是否正确

#### 3. 下载失败

```bash
# 增加详细输出查看错误
yt-dlp "URL" --verbose

# 或者启用调试模式
yt-dlp "URL" --debug
```

#### 4. Metube 中无法使用

检查以下步骤：
1. 首先尝试上述直接安装方法
2. 确认插件目录正确映射到容器中
3. 重启 Metube 容器
4. 检查容器日志：`docker logs metube_container_name`

### 调试模式

启用详细输出和调试信息：

```bash
yt-dlp "https://www.tingdao.org/dist/#/Media?device=mobile&id=11869" \
  --verbose --debug --write-info-json
```

## 📊 技术详情

### API 架构

扩展器使用以下 API 端点：
- **主要端点**: `https://www.tingdao.org/Record/exhibitions`
- **参数格式**: `ypid={media_id}&userid=`
- **响应格式**: JSON，包含 `mediaList` 和 `authorMsg`

### 数据结构

```json
{
  "status": 1,
  "list": {
    "mediaList": [
      {
        "id": "11869",
        "title": "音频标题",
        "video_url": "主要音频源",
        "videos_url": "备用音频源",
        "add_time": "2020-03-28 19:45:26"
      }
    ],
    "authorMsg": {
      "id": "1190",
      "title": "播放列表标题",
      "author": "作者姓名"
    }
  }
}
```

### 备用源机制

当主要音频源 (`video_url`) 不可用时，扩展器会自动尝试备用源 (`videos_url`)，确保下载成功率。

## ⚠️ 重要说明

本扩展器仅用于合法的个人学习和研究目的，请遵守相关网站的使用条款。