metube/API分析修正报告.md

tingdao.org API分析修正报告

审核员反馈确认

根据审核员对提交 167a843 的审核意见，我承认初步分析存在以下重大遗漏：

❌ 初步分析的错误和遗漏

1. API端点识别错误

   • ❌ 错误：认为 /Record/is_voi 是获取音频信息的主要API
   • ✅ 正确：/Record/exhibitions 负责返回系列信息
   • ✅ 正确：/Record/is_voi 仅用于标记收藏状态（需cookie uid，但可留空）

2. 数据结构分析不足

   • ❌ 遗漏：没有发现 mediaList 播放列表结构
   • ❌ 遗漏：未分析重要字段含义
   • ✅ 需补充：videos_url（备用源）、add_time（发布时间）等字段

3. yt-dlp开发规范不完整

   • ❌ 遗漏：_TESTS 测试用例定义
   • ❌ 遗漏：_extractors.py 更新要求
   • ❌ 遗漏：POST请求的headers/data格式规范

4. Metube部署方案不具体

   • ❌ 模糊：部署自定义extractor的具体方式
   • ✅ 需明确：升级/自编译yt-dlp vs 插件目录方案

重新调研发现

🔍 正在进行的深入API分析

当前已确认信息：

• 测试页面：https://www.tingdao.org/dist/#/Media?device=mobile&id=11869
• 媒体ID：11869
• 播放列表：包含8个音频项目
• 当前音频URL：http://1256958968.vod2.myqcloud.com/.../音频.mp3?签名参数

页面结构分析：

播放列表结构：
1. 2018年10月 柏训师生会：神永远的旨意-基督与教会 01 于宏洁
2. 2018年10月 柏训师生会：神永远的旨意-基督与教会 02 于宏洁
3. 2018年10月 柏训师生会：神永远的旨意-基督与教会 03 我们的使命：称为耶稣基督道成肉身的见证人 于宏洁
4. 2018年10月 柏训师生会：神永远的旨意-基督与教会 04 异象与使命的落实：VIP模式 于宏洁
5. 2018年10月 柏训师生会：神永远的旨意-基督与教会 05 异象与使命的落实：本于祂，倚靠祂，归于祂 于宏洁
6. 2018年10月 柏训师生会：神永远的旨意-基督与教会 06 异象与使命的落实：同一心灵，同一脚踪 于宏洁
7. 2018年10月 柏训师生会：神永远的旨意-基督与教会 07 异象与使命的落实：成全圣徒，各尽其职 于宏洁
8. 2018年10月 柏训师生会：神永远的旨意-基督与教会 08 异象与使命的落实：凡事长进，连于元首基督 于宏洁

网络请求监控结果：

• 已设置全面的 Fetch 和 XHR 监控
• 正在测试 /Record/exhibitions 端点
• 同时验证 /Record/is_voi 的收藏功能

修正后的技术方案框架

1. 正确的API调用逻辑

# 主要API：获取播放列表信息
exhibitions_url = 'https://www.tingdao.org/Record/exhibitions'
exhibitions_data = self._download_json(
    exhibitions_url,
    media_id,
    data=f'id={media_id}'.encode(),
    headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

# 解析 mediaList 结构
for item in exhibitions_data.get('mediaList', []):
    # 提取完整字段信息
    entry = {
        'id': item['id'],
        'title': item['title'],
        'url': item['video_url'],        # 主要音频源
        'alt_url': item['videos_url'],   # 备用音频源
        'timestamp': item['add_time'],   # 发布时间
        'thumbnail': item.get('img_url'),
        'ext': 'mp3'
    }

2. yt-dlp开发Checklist

基于官方CONTRIBUTING.md：

✅ 必需组件：

• _VALID_URL 正则匹配
• _TESTS 至少一个测试用例
• _real_extract() 核心提取方法
• 更新 yt_dlp/extractor/_extractors.py
• 通过 hatch test TingdaoIE 测试
• 通过 hatch fmt --check 代码检查

✅ _TESTS 标准格式：

_TESTS = [{
    'url': 'https://www.tingdao.org/dist/#/Media?device=mobile&id=11869',
    'info_dict': {
        'id': '11869',
        'title': '2018年10月 柏训师生会：神永远的旨意-基督与教会',
        'ext': 'mp3',
    },
    'playlist_count': 8,
    'params': {
        'skip_download': True,  # 用于CI测试
    }
}]

3. Metube部署方案

方案A：yt-dlp插件系统（推荐）

# 1. 创建插件目录结构
~/.config/yt-dlp/plugins/tingdao_plugin/
└── yt_dlp_plugins/
    └── extractor/
        └── tingdao.py

# 2. Docker volume挂载
volumes:
  - "./plugins:/app/.config/yt-dlp/plugins"

方案B：自编译yt-dlp

• Fork yt-dlp仓库
• 添加extractor到官方目录
• 重新构建Metube Docker镜像

方案C：升级yt-dlp版本

• 等待官方接受PR
• 使用标准yt-dlp更新

下一步深入调研计划

阶段1：完成API端点验证

• 确认 /Record/exhibitions 完整响应格式
• 验证 mediaList 数据结构和所有字段
• 测试 /Record/is_voi 收藏功能机制
• 分析音频URL签名和有效期机制

阶段2：extractor实现设计

• 基于真实API设计URL匹配规则
• 实现单音频和播放列表支持
• 添加备用源和错误处理
• 编写完整的测试用例

阶段3：集成测试验证

• 本地yt-dlp测试
• Metube集成测试
• 浏览器功能验证
• 性能和稳定性测试

待审核员确认的问题

1. API调研重点：是否重点关注exhibitions端点的完整响应结构？
2. 实现优先级：单音频支持 vs 完整播放列表支持的开发顺序？
3. 部署策略：更倾向于插件方式还是官方PR方式？
4. 测试范围：除了当前测试URL，是否需要发现更多测试用例？

---

报告时间：2025-09-23 状态：API深入调研进行中 下一步：基于审核员指导继续API端点验证