subtitle-craft

Files (45)

• CHANGELOG.md
• README.md
• SKILL.md
• VALIDATION.md
• __init__.py
• icon.svg
• plugin.json
• plugin.py
• subtitle_asr_client.py
• __init__.py · subtitle_craft_inline/
• llm_json_parser.py · subtitle_craft_inline/
• parallel_executor.py · subtitle_craft_inline/
• storage_stats.py · subtitle_craft_inline/
• system_deps.py · subtitle_craft_inline/
• upload_preview.py · subtitle_craft_inline/
• vendor_client.py · subtitle_craft_inline/
• subtitle_hook_picker.py
• subtitle_models.py
• subtitle_pipeline.py
• subtitle_renderer.py
• subtitle_task_manager.py
• __init__.py · tests/
• conftest.py · tests/
• sample_long.srt · tests/fixtures/
• sample_minimal.srt · tests/fixtures/
• sample_short.srt · tests/fixtures/
• __init__.py · tests/integration/
• conftest.py · tests/integration/
• test_paraformer_smoke.py · tests/integration/
• test_qwen_plus_hook_smoke.py · tests/integration/
• test_data_layer.py · tests/
• test_hook_picker.py · tests/
• test_pipeline.py · tests/
• test_pipeline_hook.py · tests/
• test_plugin.py · tests/
• test_renderer.py · tests/
• test_skeleton.py · tests/
• test_ui_smoke.py · tests/
• bootstrap.js · ui/dist/_assets/
• i18n.js · ui/dist/_assets/
• icons.js · ui/dist/_assets/
• markdown-mini.js · ui/dist/_assets/
• styles.css · ui/dist/_assets/
• icon.svg · ui/dist/
• index.html · ui/dist/

SKILL.md (first lines)

# Subtitle Craft Skill Definition

## 1. Trigger Scenarios

Use this skill when the user wants to:

- 自动给视频/音频生成字幕(听写)
- 把已有 SRT 翻译为另一种语言(单语 or 双语字幕)
- 修复时间轴对齐 / 断行重排 / 重叠问题
- 把字幕烧入视频(软字幕 sidecar 或硬烧 in-stream)
- 区分多说话人 / 把 SPEAKER_xx 自动映射成角色名
- 估算「这段视频做字幕大概要花多少 ¥」

Keywords (zh): 字幕, 听写, 转录, 翻译字幕, 字幕修复, 字幕烧制, 双语字幕, 角色识别, 说话人分离
Keywords (en): subtitle, caption, transcribe, translate srt, burn subtitle, diarization, speaker

## 2. Command Reference (4 tools)

| Tool | Purpose |
|------|---------|
| `subtitle_craft_create` | Create a subtitle task (mode = auto_subtitle / translate / repair / burn) |
| `subtitle_craft_status` | Inspect a single task's status, pipeline step, error_kind |
| `subtitle_craft_list`   | List recent tasks (default 10) |
| `subtitle_craft_cancel` | Cooperative cancel of a running task |

> v1.0 explicitly does **NOT** declare any `subtitle_craft_handoff_*` tool —
> cross-plugin dispatch is deferred to v2.0 with schema reservation only.

## 3. Input Schema

### `subtitle_craft_create`
```json
{
  "mode": "auto_subtitle | translate | repair | burn",
  "source_path": "/abs/path/to/video.mp4",      // for auto_subtitle / burn
  "srt_path":    "/abs/path/to/input.srt",      // for translate / repair / burn
  "source_lang": "",                             // empty = auto-detect (Paraformer language_hints)
  "target_lang": "en",                           // for translate
  "translation_model": "qwen-mt-flash",          // qwen-mt-flash | qwen-mt-plus | qwen-mt-lite
  "diarization_enabled": false,                  // auto_subtitle only
  "speaker_count": 0,                            // 0 = auto
  "character_identify_enabled": false,           // requires diarization_enabled=true
  "disfluency_removal_enabled": false,           // remove um/uh/嗯/啊
  "bilingual": false,                            // translate only — keep both lines
  "subtitle_style": "default",                   // default | cinema | youtube | tiktok | tv | <custom_id>
  "burn_engine": "ass",                          // ass | html
  "burn_mode": "hard"                            // hard (in-stream) | soft (mp4 sidecar)
}
```

### `subtitle_craft_status`
```json
{ "task_id": "abc123def456" }
```

### `subtitle_craft_cancel`
```json
{ "task_id": "abc123def456" }
```

## 4. Output Schema

### Task envelope (returned by create / get / list elements)
```json
{
  "id": "abc123def456",
  "mode": "auto_subtitle",
  "status": "pending|running|succeeded|failed|canceled",
  "pipeline_step": "setup_environment|estimate_cost|prepare_assets|asr_or_load|identify_characters|translate_or_repair|render_output|burn_or_finalize",
  "progress": 0.42,
  "source_path": "...",
  "output_srt_path": "...",
  "output_vtt_path": "...",
  "output_video_path": "...",
  "error_kind": "network|timeout|auth|quota|moderation|dependency|format|duration|unknown",
  "error_message": "...",
  "error_hints": "..."
}
```

## 5. Mode Selection Heuristics (when the user is vague)

| User says | Choose mode | Notes |
|---|---|---|
| "给这段视频加字幕" / "transcribe video" | `auto_subtitle` | If the user mentions multiple people, also turn on `diarization_enabled` |
| "把字幕翻译成英文" / "translate srt to english" | `translate` | Default `translation_model=qwen-mt-flash` (best value) |
| "字幕重叠了" / "时间轴乱" / "fix overlap" | `repair` | No API cost — pure local rewrite |
| "烧制" / "硬字幕" / "burn subtitle" | `burn` | Default `burn_engine=ass` (FFmpeg native) — switch to `html` only when the user wants custom CSS |
| 提到 "区分谁在说话" / "speaker" | `auto_subtitle` + `diarization_enabled=true` | Add `character_identify_enabled=true` if the user wants character names instead of SPEAKER_xx |

## 6. Cost Hints (for setting expectations before invoking)

- Paraformer-v2: ¥0.00027 / second of audio (~¥1 / hour)
- Qwen-MT Flash:  ¥0.000007 / token (~¥0.005 / 1k tokens)
- Qwen-MT Plus:   ¥0.000016 / token
- Qwen-MT Lite:   ¥0.000003 / token
- Qwen-VL Max (character ID): one call per task, ¥0.020 typical
- Local burn (FFmpeg/Playwright): free

A 30-min YouTube → English subtitles round-trip is usually ¥0.50–¥0.80.

## 7. Error Handling Contract (9 canonical kinds)

The `error_kind` field always falls into one of these 9 values, identical
to `clip-sense`'s taxonomy:

| `error_kind` | What to tell the user |
|---|---|
| `network`    | Suggest checking VPN / DNS, then retry |
| `timeout`    | Increase Paraformer timeout in Settings, then retry |
| `auth`       | API key wrong / 4xx → open Settings |
| `quota`      | Bailian balance / quota exhausted |
| `moderation` | Content flagged → ask the user to trim sensitive parts |
| `dependency` | FFmpeg / Playwright missing — HTML burn auto-falls back to ASS |
| `format`     | Bad SRT encoding (must be UTF-8) / unsupported video container |
| `duration`   | File >2 GB or audio >12 h — ask user to split first |
| `unknown`    | Surface the raw `error_message` and link to logs |

## 8. SSE Live Updates

From LZM163126lzm/openakita, AGPL-3.0.

More from LZM163126lzm/openakita