---
name: "async-mediaprocess"
description: "视频/音频转码与AI媒体处理命令行工具。支持提交VOD转码任务、调用16种已验证AI媒体处理操作（视频裁剪、拼接、变速、静音、倒放、旋转、转GIF、配音、混音、调音量、音频裁剪、变速、质量评估等）。通过 /intf.php API 与 transcode_api_v2 服务交互。"
triggers:
  - "视频裁剪"
  - "视频拼接"
  - "视频转码"
  - "视频处理"
  - "音频处理"
  - "音频提取"
  - "视频变速"
  - "视频静音"
  - "视频倒放"
  - "视频旋转"
  - "视频转GIF"
  - "视频配音"
  - "视频混音"
  - "调整音量"
  - "音频裁剪"
  - "音频变速"
  - "视频质量评估"
  - "视频转场"
  - "transcode video"
  - "video clip"
  - "media processing"
  - "transcode_api_v2"
  - "提交转码任务"
  - "查询任务状态"
---

# async-mediaprocess

视频/音频转码与AI媒体处理命令行工具，封装了 `transcode_api_v2` PHP API 的所有接口。

安装命令：`pip install async-mediaprocess`

## 安装

```bash
pip install async-mediaprocess
```

## 前置准备：注册与开通服务

在使用本工具前，需要先在 **360智汇云** 完成注册和服务开通。

**1. 注册登录**
访问 https://zyun.360.cn/index 注册账号并完成实名认证。

**2. 开通媒体处理服务**
登录后进入控制台，开通媒体处理服务，并创建项目：
- **项目名称**：支持字母/数字/下划线，最长32位，即 `TRANSCODE_API_SNAME`
- **回调设置**：用于接收转码/截图任务完成通知（可选）
- **bucket 设置**：输出文件存储位置，即 `TRANSCODE_API_MEDIA_BUCKET`，**调用 API 前必须在控制台填写**

**3. 开通云存储并创建 bucket**
支持 360云存储（推荐）或兼容 AWS 的第三方存储。
使用 360云存储需先开通并创建**公有 bucket**：https://zyun.360.cn/developer/doc?did=czsc

**4. 获取 AK/SK**
在用户中心 → AK/SK 管理页面查看：https://zyun.360.cn/usercenter/user/accesskey

| 控制台参数 | 对应环境变量 |
|-----------|------------|
| AK | `TRANSCODE_API_AK` / `TRANSCODE_API_OSS_AK` |
| SK | `TRANSCODE_API_SK` / `TRANSCODE_API_OSS_SK` |
| 项目名称 | `TRANSCODE_API_SNAME` |
| bucket 名 | `TRANSCODE_API_MEDIA_BUCKET` |

## 环境变量配置（推荐）

使用前先设置环境变量，避免每次重复输入认证参数：

```bash
# 基础认证（所有命令必填）
export TRANSCODE_API_BASE_URL=http://your-server:8090   # API服务地址
export TRANSCODE_API_SNAME=your_sname                   # 服务命名空间
export TRANSCODE_API_AK=your_access_key                 # AccessKey（32位hex）
export TRANSCODE_API_SK=your_secret_key                 # SecretAccessKey

# Media模块专用（使用 media 子命令时必填）
export TRANSCODE_API_MEDIA_SERVICE=your_service         # 媒体服务名称
export TRANSCODE_API_MEDIA_BUCKET=your_bucket           # 输出OSS bucket名
export TRANSCODE_API_OSS_HOST=http://your-oss-host/     # OSS服务地址
export TRANSCODE_API_OSS_AK=your_oss_ak                 # OSS AccessKey
export TRANSCODE_API_OSS_SK=your_oss_sk                 # OSS SecretKey
export TRANSCODE_API_OSS_REGION=your_region             # OSS区域
```

设置完环境变量后，命令中无需再写 `--base-url`、`--ak`、`--sk` 等参数。

## 全局参数

```
async-mediaprocess [全局参数] <命令组> <子命令> [参数]

全局参数：
  --base-url TEXT   API地址         (环境变量 TRANSCODE_API_BASE_URL)
  --sname    TEXT   服务命名空间     (环境变量 TRANSCODE_API_SNAME)
  --ak       TEXT   AccessKey       (环境变量 TRANSCODE_API_AK)
  --sk       TEXT   SecretAccessKey (环境变量 TRANSCODE_API_SK)
  --json            输出JSON格式（供程序处理）
  --repl            启动交互REPL模式
```

## 认证说明

CLI 自动使用 HMAC-SHA1 计算签名，无需手动处理：
```
Authorization: <AK>:<base64(HMAC-SHA1(AK+"\n"+timestamp+"\n"+rand, SK))>
```

---

## 命令组一览

| 命令组 | 功能 |
|--------|------|
| `task` | VOD转码任务管理（提交/查询/停止/等待） |
| `media` | AI媒体处理（16种已验证操作，视频/音频） |

---

## task — VOD转码任务

```bash
# 提交任务
async-mediaprocess task add \
  --service <服务名> \
  --args '<JSON参数>' \
  --bucket <输出桶> \
  --weight low|normal|high \
  --save-as <别名>

# 查询单个任务（成功时自动输出文件链接）
async-mediaprocess task get <TID>

# 查询多个任务
async-mediaprocess task get-many <TID1> <TID2> ...

# 停止任务
async-mediaprocess task stop <TID>

# 轮询等待完成（推荐用这个代替手动轮询）
async-mediaprocess task wait <TID> --timeout 300 --interval 5
```

### 任务状态码

| 状态码 | 含义 |
|--------|------|
| 0 | 排队中（queued） |
| 1 | 完成（done） |
| 2 | 失败（failed） |
| 3 | 发送中（sending） |
| 6 | 处理中（processing） |

---

## media — AI媒体处理

### media组公共参数

```bash
async-mediaprocess media \
  --service <媒体服务名>   (环境变量 TRANSCODE_API_MEDIA_SERVICE)
  --bucket <bucket名>      (环境变量 TRANSCODE_API_MEDIA_BUCKET)
  --oss-host <OSS地址>     (环境变量 TRANSCODE_API_OSS_HOST)
  --oss-ak <OSS AK>        (环境变量 TRANSCODE_API_OSS_AK)
  --oss-sk <OSS SK>        (环境变量 TRANSCODE_API_OSS_SK)
  --oss-region <区域>      (环境变量 TRANSCODE_API_OSS_REGION)
  <子命令> [参数]
```

### 查询媒体任务结果

```bash
# 查询任务（完成时自动输出文件下载链接）
async-mediaprocess media get <TID>

# JSON格式输出（output_urls字段包含文件链接列表）
async-mediaprocess --json media get <TID>

# 停止任务
async-mediaprocess media stop <TID>

# 列出所有支持的Action名称
async-mediaprocess media actions
```

---

## media 子命令详情

### 视频处理

#### video-clip — 视频裁剪（按时间段）
按指定起止时间截取视频片段。
```bash
async-mediaprocess media video-clip \
  --input <视频URL> \        # 必填
  --output <输出文件名> \    # 必填
  --format mp4 \             # 必填，输出格式
  --filmtitle 10 \           # 开始时间（秒），默认0
  --filmendpoint 30 \        # 结束时间（秒），默认0
  --width 0 \                # 输出宽度，0=保持原始
  --height 0                 # 输出高度，0=保持原始
```

#### video-cut-by-ratio — 视频按比例裁切
将视频裁切到指定宽高比（如9:16竖屏），自动裁去多余边缘。
```bash
async-mediaprocess media video-cut-by-ratio \
  --input-video <视频URL> \    # 必填
  --output <输出文件名> \      # 必填
  --format mp4 \               # 必填
  --cut-ratio-width 9 \        # 目标宽高比宽，默认16
  --cut-ratio-height 16        # 目标宽高比高，默认9
```

#### video-mute — 视频静音
移除视频音轨，输出无声视频。
```bash
async-mediaprocess media video-mute \
  --video-url <视频URL> \    # 必填
  --output <输出文件名>      # 必填
```

#### video-reverse — 视频倒放
将视频帧逆序排列，实现"倒带"播放效果。
```bash
async-mediaprocess media video-reverse \
  --video-url <视频URL> \    # 必填
  --output <输出文件名>      # 必填
```

#### video-rotate — 视频旋转/翻转
对视频进行旋转或镜像翻转。
```bash
async-mediaprocess media video-rotate \
  --video-url <视频URL> \    # 必填
  --output <输出文件名> \    # 必填
  --flip cw                  # 必填：ccw逆时针90°/cw顺时针90°/hflip水平镜像/vflip垂直镜像
```

#### video-stretch — 视频变速
改变视频播放速度，实现慢动作或快进效果。
```bash
async-mediaprocess media video-stretch \
  --input-video <视频URL> \    # 必填
  --output <输出文件名> \      # 必填
  --format mp4 \               # 必填
  --speed-level 0.5            # 速度倍数，0.5=半速慢动作，2.0=2倍快进，默认0.5
```

#### video-cut-gif — 视频转GIF
将视频某一段转换为动态GIF图片。
```bash
async-mediaprocess media video-cut-gif \
  --input <视频URL> \        # 必填
  --output <输出GIF文件名> \ # 必填
  --gif-starttime 5 \        # 开始时间（秒），默认0
  --duration 3 \             # 截取时长（秒），0=全部，默认0
  --fps 15                   # GIF帧率，默认25
```

#### video-fade — 视频转场拼接
将两段视频通过转场动画连接，支持多种过渡效果。
```bash
async-mediaprocess media video-fade \
  --first-video-url <第一段视频URL> \    # 必填
  --second-video-url <第二段视频URL> \   # 必填
  --output <输出文件名> \                # 必填
  --transition vertclose \               # 转场效果：vertclose/circleopen/fade等，默认vertclose
  --fade-duration 2                      # 转场时长（秒），默认2
```

#### concat-video — 多视频拼接
将多个视频按顺序首尾拼接为一个完整视频。
```bash
async-mediaprocess media concat-video \
  --datasets <视频URL1> \    # 必填，可重复传入多个
  --datasets <视频URL2> \
  --output <输出文件名> \    # 必填
  --format mp4 \             # 必填
  --vbitrate 2500 \          # 视频码率kbps，默认2500
  --abitrate 64 \            # 音频码率kbps，默认64
  --fps 25 \                 # 帧率，默认25
  --crf 27                   # 质量因子，越小越清晰，默认27
```

#### video-add-dub — 视频配音
用指定音频替换视频原始音轨，实现配音效果。
```bash
async-mediaprocess media video-add-dub \
  --video-url <视频URL> \    # 必填
  --audio-url <音频URL> \    # 必填，配音音频
  --output <输出文件名> \    # 必填
  --mix-by-audio <URL>       # 可选，第二路混音音频
```

#### video-add-audio — 视频混音
将音频轨道混入视频（与原音轨叠加）。
```bash
async-mediaprocess media video-add-audio \
  --video-url <视频URL> \    # 必填
  --audio-url <音频URL> \    # 必填，混入的音频
  --output <输出文件名> \    # 必填
  --audio-adapt              # 可选flag，自动循环/裁剪音频以适配视频时长
```

#### video-add-bgm — 添加背景音乐
为视频添加背景音乐，支持音量控制。
```bash
async-mediaprocess media video-add-bgm \
  --input-video <视频URL> \    # 必填
  --output <输出文件名> \      # 必填
  --format mp4 \               # 必填
  --audio <背景音乐URL> \      # 背景音乐地址
  --volume 50                  # 音量，默认0
```

#### video-add-mask — 叠加WebM蒙层
将含透明通道的WebM视频（特效/蒙层）叠加到目标视频上。
```bash
async-mediaprocess media video-add-mask \
  --video-url <底层视频URL> \    # 必填
  --webm-url <WebM蒙层URL> \     # 必填，需含透明通道的WebM文件
  --output <输出文件名>          # 必填
```

#### video-quality-assessment — 视频质量评估
对比目标视频与参考视频，计算VMAF、PSNR等质量评分。
```bash
async-mediaprocess media video-quality-assessment \
  --media-url <待评估视频URL> \    # 必填
  --bash-url <参考基准视频URL>     # 必填
```

---

### 音频处理

#### audio-extract — 提取音频
从视频文件中提取音轨，支持指定编码格式、采样率等。
```bash
async-mediaprocess media audio-extract \
  --input <视频URL> \        # 必填
  --output <输出文件名> \    # 必填
  --format mp3 \             # 输出格式
  --acodec mp3 \             # 编码：copy/aac/pcm/mp3，默认copy
  --achannel 2 \             # 声道数，1=单声道，2=立体声，默认1
  --abitrate 128 \           # 音频码率kbps，默认64
  --filmtitle 0 \            # 开始时间（秒）
  --filmendpoint 0           # 结束时间（秒）
```

#### audio-cut-by-time — 音频裁剪
按起止时间裁剪音频文件。
```bash
async-mediaprocess media audio-cut-by-time \
  --input <音频URL> \        # 必填
  --output <输出文件名> \    # 必填
  --filmtitle 30 \           # 开始时间（秒），默认0
  --filmendpoint 90          # 结束时间（秒），默认0
```

#### audio-concat — 多音频拼接
将多个音频文件首尾拼接为一个音频文件。
```bash
async-mediaprocess media audio-concat \
  --datasets <音频URL1> \    # 必填，可重复传入多个
  --datasets <音频URL2> \
  --output <输出文件名> \    # 必填
  --format mp3 \             # 必填
  --abitrate 64 \            # 音频码率，默认64
  --achannel 1               # 声道数，默认1
```

#### audio-stretch — 音频变速（不变调）
改变音频播放速度，同时保持音调不变（时间拉伸）。
```bash
async-mediaprocess media audio-stretch \
  --audio-url <音频URL> \    # 必填
  --output <输出文件名> \    # 必填
  --speed-level 1.5          # 必填，速度倍数：0.5=半速，1.5=1.5倍，2.0=双速
```

#### media-adjust-volume — 调整音量
调整音频或视频文件中的音量大小。
```bash
async-mediaprocess media media-adjust-volume \
  --media-url <媒体URL> \    # 必填（音频或视频均可）
  --output <输出文件名> \    # 必填
  --volume 2.0               # 音量倍数：1.0=原始，2.0=两倍，0.5=一半，默认1.0
```

#### media-separati-voice — 人声/伴奏分离
使用AI将音频/视频中的人声与背景音乐（伴奏）分离。
```bash
# 提取人声
async-mediaprocess media media-separati-voice \
  --media-url <媒体URL> \    # 必填
  --output <输出文件名> \    # 必填
  --is-vocals                # 加此flag=输出人声，不加=输出伴奏
```

---

### 图片处理

#### pic-to-video — 图片序列转视频
将多张图片按顺序合成为视频。
```bash
async-mediaprocess media pic-to-video \
  --datasets <图片URL1> \    # 必填，可重复
  --datasets <图片URL2> \
  --output <输出文件名> \    # 必填
  --format mp4 \             # 必填
  --width 1920 \             # 必填，输出宽度
  --height 1080 \            # 必填，输出高度
  --duration 3 \             # 每张图片显示时长（秒），默认10
  --audio <背景音频URL>      # 可选
```

#### pic-to-special-effects-video — 图片特效视频
将单张图片配合特效动画生成一段特效视频。
```bash
async-mediaprocess media pic-to-special-effects-video \
  --input-pic <图片URL> \      # 必填
  --output <输出文件名> \      # 必填
  --format mp4 \               # 必填
  --image-trans-type 1 \       # 特效类型索引，默认1
  --duration 10 \              # 视频时长（秒），默认10
  --audio <背景音频URL>        # 可选
```

#### image-enlargement-to-video — 图片缩放动效视频
将静态图片配合Ken Burns缩放平移动画生成视频。
```bash
async-mediaprocess media image-enlargement-to-video \
  --pic-url <图片URL> \      # 必填
  --output <输出文件名> \    # 必填
  --duration 8               # 视频时长（秒），默认5
```

#### image-to-video — 图片+音频合成视频
将静态图片和音频合并为视频（图片作为静态画面）。
```bash
async-mediaprocess media image-to-video \
  --pic-url <图片URL> \      # 必填
  --audio-url <音频URL> \    # 必填
  --output <输出文件名> \    # 必填
  --zoompan-view 0           # Ken Burns样式索引，默认0
```

---

### AI增强处理

#### watermark — 添加水印
为视频添加图片水印或文字水印（硬编码烧录）。
```bash
async-mediaprocess media watermark \
  --input <视频URL> \            # 必填
  --output <输出文件名> \        # 必填
  --format mp4 \                 # 必填
  --watermark-url <水印图片URL>  # 图片水印URL
  --drawtext "版权所有 2025"     # 文字水印内容
```

#### subtitles — 添加硬字幕
将字幕文件（SRT/ASS）硬编码烧录进视频画面。
```bash
async-mediaprocess media subtitles \
  --input <视频URL> \        # 必填
  --output <输出文件名> \    # 必填
  --format mp4 \             # 必填
  --subfile <字幕文件URL>    # 字幕文件URL（SRT/ASS）
```

#### auto-subtitles — AI自动字幕
使用语音识别自动生成字幕并烧录到视频，无需提供字幕文件。
```bash
async-mediaprocess media auto-subtitles \
  --input <视频URL> \        # 必填
  --output <输出文件名> \    # 必填
  --format mp4               # 必填
```

#### ai-remove-watermark — AI去水印
使用AI算法自动识别并去除视频中的水印。
```bash
# 按关键词检测
async-mediaprocess media ai-remove-watermark \
  --video-url <视频URL> \      # 必填
  --output <输出文件名> \      # 必填
  --detect-type keyword \      # 检测方式：keyword或area，默认keyword
  --keyword "某某平台"         # 水印关键词

# 按区域坐标检测
async-mediaprocess media ai-remove-watermark \
  --video-url <视频URL> \
  --output <输出文件名> \
  --detect-type area \
  --detect-area "10,10,200,60"  # 格式：x,y,w,h
```

#### content-summary — AI内容摘要
使用AI分析视频/音频内容，生成文字摘要。
```bash
async-mediaprocess media content-summary \
  --input <媒体URL> \        # 必填
  --output <输出文件名>      # 必填
```

---

## 输出格式

**默认（人类可读）：**
```
  tid: 337117566
output:
  https://beijing2.xstore.qihu.com/test2025ttl30/clip.mp4
```

**JSON模式（`--json`，适合程序处理）：**
```json
{
  "tid": 337117566,
  "status": 1,
  "progress": 100,
  "errno": 1,
  "output_urls": ["https://beijing2.xstore.qihu.com/test2025ttl30/clip.mp4"]
}
```

> 任务完成（status=1）时，`output_urls` 字段自动包含所有输出文件的完整下载链接。

---

## 典型工作流

### 提交媒体任务并获取结果

```bash
# 第一步：提交任务
async-mediaprocess media video-clip \
  --input https://example.com/video.mp4 \
  --output clip.mp4 \
  --format mp4 \
  --filmtitle 10 \
  --filmendpoint 30
# 返回: tid: 337117566

# 第二步：查询结果（完成后自动显示文件链接）
async-mediaprocess media get 337117566
# 输出:
#   tid: 337117566
# output:
#   https://your-oss/bucket/clip.mp4
```

### 使用 --save-as 保存任务ID

```bash
# 提交任务并保存tid到别名
async-mediaprocess media video-clip \
  --input https://example.com/video.mp4 \
  --output clip.mp4 --format mp4 \
  --filmtitle 10 --filmendpoint 30 \
  --save-as step1

# 之后直接用别名查询
async-mediaprocess media get step1
```

### REPL交互模式

```bash
async-mediaprocess --repl

transcode-api-v2> media get 337117566
transcode-api-v2> task get 12345
transcode-api-v2> exit
```

---

## 大模型调用指南

1. 使用 `--json` 获取结构化输出，`errno` 非零表示错误，读取 `errmsg` 了解原因。
2. 任务状态：0=排队中，1=完成，2=失败，3=发送中，6=处理中。
3. 任务成功（status=1）时，`output_urls` 字段直接包含可下载的文件链接。
4. media子命令需要设置 `--service`、`--bucket`、OSS参数，建议通过环境变量统一配置。
5. 查看所有支持的Media操作：`async-mediaprocess media actions`
7. 查看所有支持的Media操作：`async-mediaprocess media actions`
