alibabacloud-video-forge

阿里云视频工坊

通过阿里云媒体处理服务（MPS）一站式处理视频，包括生成封面、多分辨率转码、内容审核等。

前提条件

预检查：需要 Aliyun CLI >= 3.3.3 运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 查看安装说明。

预检查：需要更新 Aliyun CLI 插件 [MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保现有插件始终保持最新。

预检查：需要配置 AI-Mode [MUST] 使用 aliyun CLI 命令前，配置 AI-Mode：

• aliyun configure ai-mode enable
• aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"
• aliyun configure ai-mode disable

预检查：需要 Python >= 3.10 运行 python3 --version 进行验证。

预检查：需要阿里云凭证

运行 aliyun configure list 检查凭证状态。如果没有有效的配置文件，请通过 aliyun configure 进行配置。 凭证安全规则请参阅 references/security-guidelines.md。

🚀 快速开始

最简单的方式 - 一键处理视频：

# Method 1: Use end-to-end workflow script (Recommended)
python scripts/video_workflow.py --input /path/to/video.mp4

# Method 2: Check environment first
python scripts/health_check.py

# Method 3: Execute steps manually
python scripts/oss_upload.py --local-file video.mp4 --oss-key input/video.mp4
python scripts/mps_transcode.py --oss-object input/video.mp4 --preset multi
python scripts/mps_audit.py --oss-object input/video.mp4

常见场景

场景 1：发布哔哩哔哩视频

python scripts/video_workflow.py \
  --input my_video.mov \
  --preset 720p \
  --generate-cover \
  --scenes porn terrorism ad

场景 2：审核 UGC 内容

python scripts/mps_audit.py --oss-object /input/user_uploaded.mp4

场景 3：多分辨率转码

python scripts/mps_transcode.py \
  --oss-object /input/course_video.mp4 \
  --preset multi \
  --output-prefix output/course_2024/

---

场景说明

此技能支持视频分发场景：

1. 转码 — 使用窄带高清压缩进行多分辨率转码
2. 内容审核 — 自动检测敏感内容（色情、恐怖主义、广告）
3. 截图 — 生成封面图和雪碧图
4. 反盗版 — 配置加密以保护内容

架构

OSS Bucket + MPS Pipeline + Transcoding Templates + Moderation Service

组件：

• OSS：存储视频和输出内容
• MPS Pipeline：管理任务队列
• 转码模板：窄带高清、标准预设
• 审核：自动进行内容安全检查

目标用户：视频平台、内容创作者、企业培训机构、教育平台

功能概览

详细的功能树和自动化流水线管理说明，请参阅 references/capability-overview.md。

环境变量

必需的环境变量：

• ALIBABA_CLOUD_REGION - 服务区域（默认：cn-shanghai）
• ALIBABA_CLOUD_OSS_BUCKET - OSS Bucket 名称
• ALIBABA_CLOUD_OSS_ENDPOINT - OSS endpoint
• ALIBABA_CLOUD_MPS_PIPELINE_ID - MPS Pipeline ID（可选，未设置时自动选择）

**安全提示：**凭证通过阿里云默认凭证链进行管理。使用 aliyun configure 命令配置凭证。切勿在脚本或命令中直接处理 AK/SK。

🔒 安全指南

完整的安全指南和凭证管理最佳实践，请参阅 references/security-guidelines.md。

SDK 安装

详细的安装指南和故障排除说明，请参阅 references/sdk-installation.md。

运行 python3 --version 进行验证。某些脚本在较旧的 Python 版本下可能无法运行。

RAM 权限

[MUST] RAM 权限预检查： 执行前，请确认当前用户拥有以下 RAM 权限。 完整权限列表和详情请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 执行期间，如果任何命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能，引导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可自定义参数（例如输入视频路径、输出存储桶、模板 ID 等）。未经用户明确批准，不得假设或使用默认值。

参数	必填/可选	描述	默认值
input-url	必填	输入视频 URL 或本地路径	-
output-bucket	可选	输出 OSS Bucket	环境变量值
output-path	可选	输出路径前缀	output/
template-id	可选	转码模板 ID	系统预设模板
resolutions	可选	转码分辨率列表	720p,1080p
audit	可选	是否执行内容审核	true
pipeline-id	可选	MPS Pipeline ID	自动选择

核心工作流

场景 1：一站式视频标准化

完整工作流：用户提供视频 → 上传至 OSS → 媒体信息探测 → 封面生成（截图）→ 多分辨率转码 → 内容审核 → 汇总结果（含下载链接）

步骤 0：自动选择 Pipeline（可选）

此技能支持自动管理 Pipeline，通常无需手动配置 Pipeline ID。脚本会根据任务类型自动选择合适的 Pipeline。

手动指定：

# Method 1: Set environment variable (highest priority)
export ALIBABA_CLOUD_MPS_PIPELINE_ID="your-pipeline-id"

# Method 2: Command line parameter
python scripts/mps_transcode.py --oss-object /input/video.mp4 --pipeline-id your-pipeline-id

# Method 3: Use script auto-selection
export ALIBABA_CLOUD_MPS_PIPELINE_ID=$(python scripts/mps_pipeline.py --select)

步骤 1：将视频上传至 OSS

source .venv/bin/activate
python scripts/oss_upload.py --local-file /path/to/video.mp4 --oss-key input/video.mp4

步骤 2：探测媒体信息

python scripts/mps_mediainfo.py --oss-object /input/video.mp4

步骤 3：生成封面（截图）

使用截图功能在指定时间生成视频封面：

python scripts/mps_snapshot.py --oss-object /input/video.mp4 --mode normal --time 5000

步骤 4：自适应转码（自动选择最佳分辨率和窄带高清模板）

# Adaptive mode: Auto-detect source video resolution, select best quality, use Narrowband HD template
python scripts/mps_transcode.py --oss-object /input/video.mp4

# Or manually specify multi-stream transcoding
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset multi

步骤 5：内容审核

python scripts/mps_audit.py --oss-object /input/video.mp4

步骤 6：轮询任务状态

python scripts/poll_task.py --job-id <job-id-from-step-4> --job-type transcode --region cn-shanghai

完整示例

# 1. Activate virtual environment
source .venv/bin/activate

# 2. Upload video
python scripts/oss_upload.py --local-file ./my_video.mp4 --oss-key input/my_video.mp4

# 3. Get media info
python scripts/mps_mediainfo.py --oss-object /input/my_video.mp4

# 4. Cover generation (snapshot at 5 seconds)
python scripts/mps_snapshot.py --oss-object /input/my_video.mp4 --mode normal --time 5000

# 5. Submit transcoding job (adaptive mode: auto-select best resolution)
python scripts/mps_transcode.py \
  --oss-object /input/my_video.mp4
# Save the returned job-id

# 6. Poll transcoding job status
python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai --interval 10

# 7. Content moderation
python scripts/mps_audit.py --oss-object /input/my_video.mp4

# 8. Download processed video to local
python scripts/oss_download.py --oss-key output/transcode/transcoded.mp4 --local-file ./output_video.mp4

其他场景

场景 2：仅转码

仅执行转码，不进行截图和内容审核：

source .venv/bin/activate
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset 1080p \
  --template-id "your-template-id"

场景 3：内容审核

仅执行内容审核：

source .venv/bin/activate
python scripts/mps_audit.py \
  --oss-object /input/video.mp4 \
  --scenes porn terrorism ad

成功验证

视频处理完成后，请检查结果：

1. 脚本退出代码为 0
2. 输出包含已处理的媒体信息（OSS 路径）
3. 转码任务状态为 “Success”
4. 内容审核未发现违规内容
5. 已将产物下载到本地（使用 oss_download.py）

产物获取说明：

• OSS 文件需要签名才能在线访问，直接访问 URL 会返回 403 错误
• 建议使用 oss_download.py 将结果下载到本地
• 如需在线预览，请使用 --sign-url 参数生成临时预签名 URL

# Verify transcoding success
python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai
# Expected output: Status: Success

# Verify moderation result
python scripts/mps_audit.py --query-job-id <audit-job-id>
# Expected output: Moderation passed, no violations

故障排除

完整的故障排除指南请参阅 references/troubleshooting.md。

---

清理

此技能的中间文件和输出文件存储在 OSS 中。清理方法如下：

# Delete single file
python scripts/oss_delete.py --oss-key output/transcode/video.mp4

# Delete all files under directory (recursive delete)
python scripts/oss_delete.py --prefix output/ --recursive

# Force delete (skip confirmation, for script automation)
python scripts/oss_delete.py --oss-key output/video.mp4 --force

# Preview mode (view files to be deleted without actually deleting)
python scripts/oss_delete.py --prefix output/ --recursive --dry-run

注意：删除操作不可撤销。执行前请确认。请先使用 --dry-run 预览。

可用脚本

脚本	描述
scripts/load_env.py	环境变量加载器，自动扫描并加载 Alibaba Cloud 凭证
scripts/poll_task.py	MPS 异步任务轮询器，查询任务状态
scripts/oss_upload.py	将本地文件上传到 OSS
scripts/oss_download.py	将 OSS 中的文件下载到本地
scripts/oss_list.py	列出 OSS Bucket 中的文件
scripts/oss_delete.py	删除 OSS 文件或目录（支持递归删除）
scripts/mps_mediainfo.py	获取媒体文件信息（分辨率、比特率、时长等）
scripts/mps_snapshot.py	生成截图和雪碧图（支持普通模式和雪碧图模式）
scripts/mps_transcode.py	视频转码（支持自适应窄带高清、多分辨率预设、自定义参数）
scripts/mps_audit.py	内容安全审核（支持多种审核场景）
scripts/mps_pipeline.py	查询并自动选择 Pipeline（获取 Pipeline ID）

最佳实践

1. 始终先检查环境变量 — 每次会话开始时运行 python scripts/load_env.py --check-only
2. 使用轮询而非等待 — 提交任务后，使用 poll_task.py 自动轮询状态
3. 合理选择分辨率 — 根据目标用户设备选择适当的转码分辨率
4. 启用内容审核 — 对于 UGC 内容，始终启用自动审核
5. 使用虚拟环境 — 确保依赖隔离，避免版本冲突
6. 自动管理 Pipeline — 无需手动配置 Pipeline ID，脚本会根据任务类型自动选择合适的 Pipeline

参考文档

文档	描述
references/ram-policies.md	完整的 RAM 权限策略列表
references/params.md	脚本参数文档
references/scripts-detail.md	详细的脚本用法示例
references/verification-method.md	成功验证方法
references/related-commands.md	相关 CLI 命令
references/cli-installation-guide.md	Aliyun CLI 安装指南
references/acceptance-criteria.md	测试验收标准

AI-Mode 配置

[MUST] Aliyun CLI 的 AI-Mode 设置 — 使用 aliyun CLI 命令前，必须配置 AI-Mode，以启用正确的跟踪和插件管理。

启用 AI-Mode

启用 AI-Mode 以增强功能：

aliyun configure ai-mode enable

配置 User-Agent

设置 User-Agent，以正确识别技能：

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"

禁用 AI-Mode

不再需要时，禁用 AI-Mode：

aliyun configure ai-mode disable

注意：执行任何 aliyun CLI 命令前都必须启用 AI-Mode，以确保正确跟踪功能并兼容插件。

CLI 命令规范

重要：User-Agent 会通过 AI-Mode 配置自动应用。运行 aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge" 后，后续所有 aliyun CLI 命令都会自动包含正确的 User-Agent。无需为每条命令添加 --user-agent 参数。