name: good-TTvideo2text
displayName: Good抖音短视频转文字Skills
description: "Extract audio from short videos (Douyin/TikTok) and transcribe to text with timestamps. Use when user provides video URL and needs audio transcription."

good-TTvideo2text

Extract audio from Douyin/TikTok videos and transcribe to text using ASR service.

Task Objective

Convert Douyin/TikTok video audio to text with timestamps, supporting both interactive UI and command-line workflow.

Capabilities: Video parsing, audio extraction, ASR transcription, timestamp generation

Trigger: User provides Douyin/TikTok URL and requests transcription

Usage Modes

Mode 1: Web UI (Recommended)

Visual interface for transcription management:

# 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

Features:
- Paste video URL for instant transcription
- View results with timestamps
- Cookie management for restricted videos
- Real-time progress updates

Mode 2: Script (Command Line)

Suitable for automation, AI workflow integration:

# 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

Output Format (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

Output Format (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"
      }
    ]
  }
}

Prerequisites

Dependencies:
- fastapi>=0.120.3, uvicorn>=0.35.0, httpx>=0.28.1
- TikTokDownloader dependencies (see requirements.txt)

ASR Configuration:
- Environment variables auto-injected by Goodable platform
- GOODABLE_ASR_SUBMIT_URL - ASR task submission endpoint
- GOODABLE_ASR_QUERY_URL_TEMPLATE - ASR result query endpoint (with {task_id} placeholder)

Cookie Configuration (Optional):
- Some videos require login cookies
- Configure via Web UI Settings or edit TikTokDownloader/settings.json
- Cookie format: Douyin web cookie string

Standard Workflow (AI Usage)

When User Provides URL

1. Extract URL from input:
2. User may provide raw URL or share text with URL

3. Use regex to extract actual video URL

4. Call transcribe script:
   bash python scripts/transcribe.py "USER_PROVIDED_TEXT"

5. Handle results:

6. Success: Present transcription text and timestamps
7. Error: Check error message for troubleshooting

Common Error Handling

Resource Index

• app/main.py - FastAPI application entry
• scripts/transcribe.py - Command-line transcription script
• TikTokDownloader/ - Video parsing library (source code)
• TikTokDownloader/settings.json - Cookie and configuration
• static/index.html - Web UI interface
• requirements.txt - Python dependencies
• downloads/ - Temporary file directory

Important Notes

1. Cookie Requirement: Public videos work without cookies, restricted videos need login cookies
2. ASR Platform: This skill requires Goodable platform's ASR service integration
3. URL Formats Supported:
4. Short URL: https://v.douyin.com/xxx
5. Full URL: https://www.douyin.com/video/1234567890
6. TikTok: https://vm.tiktok.com/xxx, https://www.tiktok.com/@user/video/xxx
7. Audio Extraction: Extracts background music URL directly (no download needed)
8. ASR Processing Time: Typically 5-30 seconds depending on audio length

Example AI Usage

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:
完整的转写文本内容...