# tingdao.org yt-dlp 扩展器开发 - 初始分析报告

## 项目概述

本项目旨在为 yt-dlp 开发一个新的扩展器，使其能够支持从 tingdao.org 网站下载音频内容，并集成到 Metube 服务中。

## 目标网站分析

### 网站基本信息
- **网站URL**: https://www.tingdao.org/
- **测试页面**: https://www.tingdao.org/dist/#/Media?device=mobile&id=11869
- **网站类型**: 单页应用程序 (SPA)
- **内容类型**: 基督教音频内容网站
- **音频主题**: 2018年10月 柏训师生会：神永远的旨意-基督与教会

### 技术架构分析
- **前端框架**: 基于Hash路由的SPA应用
- **音频托管**: 腾讯云VOD (Video on Demand) 服务
- **URL模式**: `#/Media?device=mobile&id={媒体ID}`

### 音频源分析
测试页面中发现的音频信息：
- **当前音频URL**: `http://1256958968.vod2.myqcloud.com/20b3381avodgzp1256958968/4732b8e35285890800479422041/4fJXeW9XQvoA.mp3?t=6913eeca&us=895305ba2a&sign=4606753c5c5784116031538a27c6960d`
- **音频格式**: MP3
- **时长**: 4552.248889 秒 (约76分钟)
- **播放列表**: 共8集音频内容

### API端点发现
通过网络监控发现的API端点：
- **端点URL**: `https://www.tingdao.org/Record/is_voi`
- **请求方法**: POST
- **当前状态**: 需要参数，返回"参数不完整"错误

### 页面结构分析
- **播放控制**: 包含播放/暂停、进度条、音量控制
- **时间控制**: 支持 ±15秒 快进/快退
- **播放列表**: 显示8集完整系列
- **媒体元素**: 页面包含1个audio元素，支持实时播放

## yt-dlp 扩展器开发机制研究

### 核心概念
- **InfoExtractor**: 所有扩展器的基类
- **_VALID_URL**: 正则表达式，定义支持的URL模式
- **_real_extract**: 核心方法，负责提取媒体信息

### 开发要求
1. 继承 `InfoExtractor` 类
2. 定义 `IE_NAME` 扩展器名称
3. 设置 `_VALID_URL` 正则模式
4. 实现 `_real_extract(self, url)` 方法
5. 返回标准化的媒体信息字典

### 扩展器文件位置
- **标准位置**: `yt_dlp/extractor/` 目录
- **文件命名**: 通常以网站名命名 (如 `tingdao.py`)
- **注册方式**: 添加到 `_extractors.py` 文件

## Metube 集成分析

### 项目架构理解
- **后端**: Python + aiohttp + Socket.IO
- **下载引擎**: `app/ytdl.py` - 管理下载队列和yt-dlp集成
- **主入口**: `app/main.py` - Web服务器和API路由
- **前端**: Angular应用，位于 `ui/` 目录

### yt-dlp 集成方式
- **配置方法**: 通过 `YTDL_OPTIONS` 环境变量或配置文件
- **扩展加载**: yt-dlp 自动加载安装的扩展器
- **无需修改**: Metube 无需代码修改即可支持新扩展器

### 配置选项
```python
# 在 app/main.py 中的配置加载
YTDL_OPTIONS = json.loads(os.environ.get('YTDL_OPTIONS', '{}'))
```

## 当前挑战和待解决问题

### 1. API结构不明确
- 需要深入分析获取音频列表的完整API
- 了解参数结构和认证机制
- 确定如何获取播放列表中所有音频的信息

### 2. 音频URL获取机制
- 当前音频URL包含签名参数 (`?t=&us=&sign=`)
- 需要了解签名生成机制
- 确定URL的有效期和刷新机制

### 3. 播放列表支持范围
- 单个音频下载 vs 完整播放列表下载
- 如何处理系列音频的批量下载
- 是否支持网站全站音频搜索

## 下一步计划

### 阶段1: 深入API分析
1. 使用浏览器开发者工具深入分析页面JavaScript
2. 逆向工程API调用方式和参数结构
3. 理解音频URL生成和认证机制
4. 测试不同媒体ID的API响应

### 阶段2: 扩展器开发
1. 基于API分析结果设计扩展器架构
2. 实现URL模式匹配和参数提取
3. 开发音频信息提取逻辑
4. 支持单个和播放列表下载

### 阶段3: 集成测试
1. 在本地环境集成新扩展器
2. 配置Metube使用本地yt-dlp
3. 使用浏览器进行功能测试
4. 验证下载流程和错误处理

### 阶段4: 优化完善
1. 添加错误处理和重试机制
2. 优化性能和用户体验
3. 考虑反爬虫对策
4. 编写测试用例和文档

## 技术决策点

### 待决策问题
1. **获取范围**: 单个音频 vs 播放列表 vs 全站下载
2. **API复杂度**: 是否需要处理登录认证
3. **反爬虫策略**: 用户代理模拟、请求延迟等
4. **部署方式**: 本地扩展 vs fork yt-dlp 项目

### 推荐方案
- **优先级**: 先支持单个音频，再扩展到播放列表
- **集成方式**: 本地yt-dlp扩展器，便于测试和调试
- **开发策略**: 增量开发，逐步完善功能

## 风险评估

### 技术风险
- API可能有复杂的认证机制
- 音频URL签名可能难以逆向
- 网站可能有反爬虫保护

### 法律合规
- 确保仅用于合法的个人使用
- 遵守网站的使用条款
- 不用于商业用途或大规模爬取

---

**报告生成时间**: 2025-09-23
**分析范围**: 初步技术可行性分析
**下一步**: 深入API结构分析