tencent-mps

腾讯云 MPS 媒体处理服务。只要用户的请求涉及音视频或图片的处理、生成、增强、用量查询、内容理解、媒体质检，必须使用此 Skill。覆盖：转码/压缩/格式转换、画质增强/老片修复/超分、字幕提取/翻译/语音识别、去字幕/擦除水印/人脸模糊、图片超分/美颜/降噪、音频分离/人声提取/伴奏提取、AI生图/生视频（含分镜）、大模型音视频理解、媒体质检、用量统计。视频增强支持专用模板（真人/漫剧/抖动优化/细节最强/人脸保真，720P至4K）。无论是视频转码、去水印、提取人声、画质修复、内容理解、质量检测，还是AI生成图片视频，都应调用此 Skill。

# 腾讯云媒体处理服务（MPS）

> 💰 **费用提示**：本 Skill 调用腾讯云 MPS 服务会产生相应费用，包括转码费、AI 处理费、存储费等。具体计费标准请参考 [腾讯云 MPS 定价](https://cloud.tencent.com/document/product/862/36180)。每次使用MPS的媒体处理/图片处理/生图/生视频功能，一定要给出提示。

通过腾讯云官方 Python SDK 调用 MPS API，所有脚本位于 `scripts/` 目录，均支持 `--help` 和 `--dry-run`。

> **详细参数**：见 [`references/params.md`](references/params.md)
> **完整示例集**：见 [`references/scripts-detail.md`](references/scripts-detail.md)

## 环境配置

检查环境变量：
```bash
python scripts/load_env.py --check-only
```

配置（`~/.profile` 或 `~/.bashrc`）：
```bash
# 必须（所有脚本）
export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"

# 以下场景必须配置 COS 变量：
#   1. 输入源为 --cos-object（即 COS 对象路径，非 URL）
#   2. 使用 mps_cos_upload.py / mps_cos_download.py 上传/下载本地文件
#   3. 脚本需要将处理结果写回 COS（OutputStorage）
export TENCENTCLOUD_COS_BUCKET="your-bucket"        # COS 存储桶名
export TENCENTCLOUD_COS_REGION="your-bucket-region" # 存储桶地域，如 ap-guangzhou
```

安装依赖：
```bash
pip install tencentcloud-sdk-python cos-python-sdk-v5
```

## 本地文件处理流程

MPS 只接受 URL 或 COS 对象作为输入，**本地文件必须先上传**。

### 用户输入本地文件时的自动处理流程

当用户请求涉及本地文件路径（如 `./video.mp4`、`/path/to/image.jpg`）时，按以下步骤**自动处理**：

**步骤 1：上传文件到 COS**
```bash
python scripts/mps_cos_upload.py --local-file <本地文件路径> --cos-key <目标路径>
```
- 使用 `--cos-key` 指定合理的存储路径（默认路径 `input/`）
- 记录上传返回的 COS 信息：bucket、region、key

**步骤 2：使用 COS 路径参数执行脚本**
根据脚本类型，使用各个脚本中 传递 COS 路径的方式，如下：
| 脚本 | COS 路径参数方式 | 示例 |
|------|----------------|------|
| `mps_transcode.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_enhance.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_erase.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_subtitle.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_imageprocess.py` | `--cos-object <key>` | `--cos-object input/image.jpg` |
| `mps_qualitycontrol.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_av_understand.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_vremake.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_narrate.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_highlight.py` | `--cos-object <key>` | `--cos-object input/video.mp4` |
| `mps_aigc_image.py` | `--cos-input-bucket <b> --cos-input-region <r> --cos-input-key <k>` | `--cos-input-bucket xxx --cos-input-region ap-guangzhou --cos-input-key input/img.jpg` |
| `mps_aigc_video.py` | `--cos-input-bucket <b> --cos-input-region <r> --cos-input-key <k>` | `--cos-input-bucket xxx --cos-input-region ap-guangzhou --cos-input-key input/img.jpg` |

> **注意**：使用 `--cos-object` 的脚本依赖环境变量 `TENCENTCLOUD_COS_BUCKET` 和 `TENCENTCLOUD_COS_REGION`；AIGC 类脚本需要显式传递完整的 COS 信息。

**步骤 3：下载处理结果（如需要）**
```bash
python scripts/mps_cos_download.py --cos-key <输出key> --local-file <本地保存路径>
```

### 输入方式说明

根据输入来源不同，支持两种方式：

#### 方式一：COS 路径方式（推荐用于本地上传文件）
使用 `--cos-object <key>` 参数（或 `--cos-input-bucket/--cos-input-region/--cos-input-key`）

- 适用场景：用户上传本地文件到 COS 后处理
- 原因：本地上传的文件可能没有公开读取权限，直接使用 URL 可能会失败
- 示例：`--cos-object input/video.mp4`

#### 方式二：URL 方式（适用于已有 URL）
使用 `--url <url>` 参数

- 适用场景：用户直接提供文件 URL（包括其他账号/来源的 COS URL、外部链接等）
- 要求：URL 必须可公开访问或已携带有效签名
- 示例：`--url https://example-bucket.cos.ap-guangzhou.myqcloud.com/video.mp4`

> ⚠️ **注意**：如果 URL 来自本地上传的 COS 文件且没有公开权限，请使用方式一（COS 路径方式），脚本会自动生成带签名的 URL。

### 手动处理示例

如需手动执行，完整流程如下：
```bash
# 1. 上传
python scripts/mps_cos_upload.py --local-file ./video.mp4 --cos-key input/video.mp4
# 2. 执行任务（使用 COS 路径）
python scripts/mps_transcode.py --cos-object input/video.mp4
# 3. 下载结果
python scripts/mps_cos_download.py --cos-key output/result.mp4 --local-file ./result.mp4
```

返回结果含链接时，用 Markdown 格式返回给用户：`[文件名](URL)`

## 异步任务说明

所有脚本默认自动轮询等待完成。
- 只提交不等待：加 `--no-wait`，脚本返回 TaskId
- 手动查询：音视频用 `mps_get_video_task.py`，图片用 `mps_get_image_task.py`

## 脚本功能映射（职责边界）

> 💰 以下操作将调用腾讯云 MPS 服务并产生费用。

选择脚本时必须严格按照映射关系，**不得混用**：

| 用户需求类型 | 使用脚本 | 说明 |
|---|---|---|
| 检查画面质量、检测模糊/花屏 | `mps_qualitycontrol.py` | **唯一质检脚本**，`--definition 60`（默认） |
| 检测播放兼容性、卡顿、播放异常 | `mps_qualitycontrol.py` | **唯一质检脚本**，`--definition 70` |
| 音频质量检测、音频事件检测 | `mps_qualitycontrol.py` | **唯一质检脚本**，`--definition 50` |
| 去除字幕、擦除水印、人脸/车牌模糊 | `mps_erase.py` | 仅用于画面内容擦除/遮挡 |
| 画质增强、老片修复、超分辨率 | `mps_enhance.py` | 视频画质提升 |
| 转码、压缩、格式转换 | `mps_transcode.py` | 编码格式处理 |
| 字幕提取、翻译、字幕类语音识别 | `mps_subtitle.py` | 字幕相关 |
| 图片处理（超分/美颜/降噪） | `mps_imageprocess.py` | 图片增强 |
| AI 生图（文生图/图生图） | `mps_aigc_image.py` | AIGC 图片生成 |
| AI 生视频（文生视频/图生视频/分镜生成） | `mps_aigc_video.py` | AIGC 视频生成，**Kling 模型支持分镜功能** |
| 音视频内容理解（场景/摘要/分析/语音识别） | `mps_av_understand.py` | 大模型理解，**必须提供 `--mode` 和 `--prompt`** |
| 视频去重（画中画/视频扩展/换脸/换人等） | `mps_vremake.py` | VideoRemake，**必须提供 `--mode`** |
| 用量统计查询 | `mps_usage.py` | 调用次数/时长查询 |
| AI解说二创 / 短剧解说 / 自动生成短剧解说视频 / 短剧解说混剪 | `mps_narrate.py` | 必须从预设 `--scene` 中选择；不支持输入自定义脚本；多集视频按顺序通过 `--extra-urls` 追加 |
| 精彩集锦 / 高光提取 / 自动剪辑精彩片段 / 足球进球集锦 / 篮球集锦 / 短剧高光 | `mps_highlight.py` | 必须从预设 `--scene` 中选择，禁止自拼 ExtendedParameter；不支持直播流 |
| 查询音视频处理任务状态 | `mps_get_video_task.py` | ProcessMedia 任务查询 |
| 查询图片处理任务状态 | `mps_get_image_task.py` | ProcessImage 任务查询 |
| 上传本地文件到 COS | `mps_cos_upload.py` | 本地→COS 前置步骤 |
| 从 COS 下载文件 | `mps_cos_download.py` | COS→本地 后置步骤 |
| 列出 COS Bucket 文件 | `mps_cos_list.py` | 查看 COS 文件列表，支持路径过滤和文件名搜索 |

> **重要**：`mps_erase.py` 职责是**擦除/遮挡画面视觉元素**，不涉及质量检测。
> "画质检测"、"模糊"、"花屏"、"播放兼容性"、"音频质检" → 必须用 `mps_qualitycontrol.py`。

## 生成命令的强制规则

1. **脚本路径前缀**：所有生成的 python 命令必须包含 `scripts/` 路径前缀，格式为 `python scripts/mps_xxx.py ...`。禁止生成 `python mps_xxx.py ...`（缺少 scripts/ 前缀）的命令。

2. **禁止占位符**：所有参数值必须是真实值。若用户未提供必需值，**先询问**，不得用 `<视频URL>`、`YOUR_URL` 等占位符。

3. **`mps_qualitycontrol.py` 必须含 `--definition`**：
   - 音频质检：`--definition 50`
   - 画面质检（默认）：`--definition 60`
   - 播放兼容性：`--definition 70`

4. **`mps_av_understand.py` 必须含 `--mode` 和 `--prompt`**：
   - `--mode video`（理解视频画面）或 `--mode audio`（仅音频，视频自动提取音频）
   - `--prompt` 控制大模型理解侧重点，缺失时结果可能为空

5. **`mps_narrate.py` 必须含 `--scene`**：
   - 值必须是预设枚举之一：`short-drama` | `short-drama-no-erase`
   - 用户说"有字幕"/"带硬字幕"时默认选含擦除场景（`short-drama`）
   - 用户说"没有字幕"/"原片无字幕"/"不擦除"时选 `-no-erase` 场景（`short-drama-no-erase`）
   - 多集视频时，第一集用 `--url`/`--cos-object`，后续集用 `--extra-urls` 按顺序追加
   - 禁止传入 `scriptUrls` 相关参数（本次不支持输入自定义脚本）

6. **`mps_highlight.py` 必须含 `--scene`**：
   - 值必须是预设枚举之一：`vlog` | `vlog-panorama` | `short-drama` | `football` | `basketball` | `custom`
   - 用户提到"篮球"/"足球"/"短剧"/"VLOG"等关键词时直接映射到对应 `--scene`，无需二次询问
   - `--prompt` 和 `--scenario` 仅在 `--scene custom` 时生效，但二者非必填
   - `--top-clip` 仅允许在 `vlog` / `vlog-panorama` / `custom` 场景下使用
   - 禁止生成预设表以外的 ExtendedParameter 字段或值
   - 用户请求处理直播流集锦时，告知当前 skill 不支持直播流，需使用 MPS API 直接调用

## 关键脚本说明

### 视频增强 (`mps_enhance.py`)

大模型增强模板（`--template`），按场景+目标分辨率选择：

| 场景 | 720P | 1080P | 2K | 4K |
|------|------|-------|----|----|
| 真人（Real） | 327001 | 327003 | 327005 | 327007 |
| 漫剧（Anime） | 327002 | 327004 | 327006 | 327008 |
| 抖动优化 | 327009 | 327010 | 327011 | 327012 |
| 细节最强 | 327013 | 327014 | 327015 | 327016 |
| 人脸保真 | 327017 | 327018 | 327019 | 327020 |

### 去字幕擦除 (`mps_erase.py`)

预设模板：`101` 去字幕 | `102` 去字幕+OCR | `201` 去水印高级版 | `301` 人脸模糊 | `302` 人脸+车牌模糊

### 大模型音视频理解 (`mps_av_understand.py`)

通过 `AiAnalysisTask.Definition=33` + `ExtendedParameter(mvc.mode + mvc.prompt)` 控制。

```bash
# 视频内容理解
python scripts/mps_av_understand.py \
    --url https://example.com/video.mp4 \
    --mode video \
    --prompt "请分析这个视频的主要内容、场景和关键信息"

# 音频模式（视频自动提取音频）
python scripts/mps_av_understand.py \
    --url https://example.com/video.mp4 \
    --mode audio \
    --prompt "请进行语音识别，输出完整文字内容"

# 对比分析（两段音视频）
python scripts/mps_av_understand.py \
    --url https://example.com/v1.mp4 \
    --extend-url https://example.com/v2.mp4 \
    --mode audio \
    --prompt "对比两段音频，分析差异"

# 查询任务
python scripts/mps_av_understand.py --task-id 2600011633-WorkflowTask-xxxxx --json
```

### 媒体质检 (`mps_qualitycontrol.py`)

脚本支持以下 3 种系统预设模板（`--definition` 参数）：

**预设模板：**
- `60`（默认）：格式质检-Pro版，检测画面模糊、花屏、画面受损等内容问题
- `50`：Audio Detectio