good-TTvideo2text

good-TTvideo2text

从抖音/TikTok 视频中提取音频，并使用 ASR 服务转录为文本。

任务目标

将抖音/TikTok 视频音频转换为带时间戳的文本，支持交互式 UI 和命令行工作流。

功能： 视频解析、音频提取、ASR 转录、时间戳生成

触发条件： 用户提供抖音/TikTok URL 并请求转录

使用方式

模式 1：Web UI（推荐）

用于转录管理的可视化界面：

# Install dependencies
cd skills/good-TTvideo2text
pip install -r requirements.txt

# Start service (default port 8000)
python app/main.py

# Browser access
http://localhost:8000

功能：

• 粘贴视频 URL，即可立即转录
• 查看带时间戳的结果
• 管理受限视频所需的 Cookie
• 实时更新进度

模式 2：脚本（命令行）

适用于自动化和 AI 工作流集成：

# Basic usage
python scripts/transcribe.py "https://v.douyin.com/xxx"

# Extract URL from share text
python scripts/transcribe.py "7.47 复制打开抖音，看看【用户名】的作品 https://v.douyin.com/xxx"

# JSON output
python scripts/transcribe.py "https://v.douyin.com/xxx" --output json

# Text output (default)
python scripts/transcribe.py "https://v.douyin.com/xxx" --output text

输出格式（文本）：

=== Video Info ===
Title: Video title
Author: Author name
Duration: 30s

=== Transcription ===
Full Text:
Complete transcription text...

Sentences with Timestamps:
[00:00-00:03] First sentence
[00:03-00:06] Second sentence

输出格式（JSON）：

{
  "success": true,
  "video_info": {
    "title": "Video title",
    "author": "Author name",
    "duration": 30,
    "create_time": 1234567890
  },
  "transcription": {
    "text": "Complete transcription...",
    "sentences": [
      {
        "start_ms": 0,
        "end_ms": 3000,
        "text": "First sentence"
      }
    ]
  }
}

前置条件

依赖项：

• fastapi>=0.120.3、uvicorn>=0.35.0、httpx>=0.28.1
• TikTokDownloader 依赖项（参见 requirements.txt）

ASR 配置：

• Goodable 平台会自动注入环境变量
• GOODABLE_ASR_SUBMIT_URL - ASR 任务提交端点
• GOODABLE_ASR_QUERY_URL_TEMPLATE - ASR 结果查询端点（带有 {task_id} 占位符）

Cookie 配置（可选）：

• 某些视频需要登录 Cookie
• 可通过 Web UI 的 Settings 配置，或编辑 TikTokDownloader/settings.json
• Cookie 格式：抖音 Web Cookie 字符串

标准工作流（AI 使用）

用户提供 URL 时

1. 从输入中提取 URL：

   • 用户可能会提供原始 URL，或包含 URL 的分享文本
   • 使用正则表达式提取实际的视频 URL

2. 调用转录脚本：

   python scripts/transcribe.py "USER_PROVIDED_TEXT"
   

3. 处理结果：

   • 成功：展示转录文本和时间戳
   • 错误：查看错误消息以排查问题

常见错误处理

错误	原因	解决方案
视频 URL 无效	URL 格式不正确	请用户提供有效的抖音/TikTok URL
未找到视频	视频已删除或需要登录	请用户检查视频，或提供 Cookie
未找到音频	视频没有背景音乐	告知用户此视频没有音轨
未配置 ASR	缺少环境变量	通过 Goodable 平台运行（平台会自动注入变量）
ASR 超时	音频较长或服务响应缓慢	重试，或使用 Web UI 监控

资源索引

• app/main.py - FastAPI 应用入口
• scripts/transcribe.py - 命令行转录脚本
• TikTokDownloader/ - 视频解析库（源代码）
• TikTokDownloader/settings.json - Cookie 和配置
• static/index.html - Web UI 界面
• requirements.txt - Python 依赖项
• downloads/ - 临时文件目录

重要说明

1. Cookie 要求： 公开视频无需 Cookie；受限视频需要登录 Cookie
2. ASR 平台： 此技能需要集成 Goodable 平台的 ASR 服务
3. 支持的 URL 格式：
   • 短链接：https://v.douyin.com/xxx
   • 完整 URL：https://www.douyin.com/video/1234567890
   • TikTok：https://vm.tiktok.com/xxx、https://www.tiktok.com/@user/video/xxx
4. 音频提取： 直接提取背景音乐 URL，无需下载
5. ASR 处理时间： 通常为 5-30 秒，具体取决于音频长度

AI 使用示例

User: "帮我转写这个抖音视频 7.47 复制打开抖音 https://v.douyin.com/abc123"

AI: Let me transcribe this video for you.

[Calls transcribe.py script with the provided text]

Based on the transcription:

Video: "视频标题"
Author: 作者名

Transcription:
[00:00-00:03] 第一句话内容
[00:03-00:08] 第二句话内容
...

Full text:
完整的转写文本内容...