Back to Details

alibabacloud-video-forge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Alibaba Cloud Video Forge

阿里云Video Forge

One-stop video processing through Alibaba Cloud Media Processing Service (MPS), including cover generation, multi-resolution transcoding, content moderation, and more.
基于阿里云媒体处理服务（MPS）的一站式视频处理能力，包含封面生成、多分辨率转码、内容审核等功能。

🚀 Quick Start

🚀 快速开始

Easiest Way - One-click video processing:
bash
undefined
最简单的方式 - 一键视频处理：
bash
undefined

Method 1: Use end-to-end workflow script (Recommended)

Method 1: Use end-to-end workflow script (Recommended)

python scripts/video_workflow.py --input /path/to/video.mp4
python scripts/video_workflow.py --input /path/to/video.mp4

Method 2: Check environment first

Method 2: Check environment first

python scripts/health_check.py
python scripts/health_check.py

Method 3: Execute steps manually

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
undefined
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
undefined

Common Scenarios

常见场景

Scenario 1: Bilibili Video Publishing

场景1：B站视频发布

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

Scenario 2: UGC Content Moderation

场景2：UGC内容审核

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

Scenario 3: Multi-Resolution Transcoding

场景3：多分辨率转码

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

Scenario Description

场景说明

This skill supports video distribution scenarios:
  1. Transcoding — Multi-resolution transcoding with Narrowband HD compression
  2. Content Moderation — Auto-detect sensitive content (pornography, terrorism, advertising)
  3. Snapshot — Generate cover images and sprite sheets
  4. Anti-piracy — Configure encryption for content protection
本工具支持以下视频分发场景：
  1. 转码 — 搭载窄带高清压缩能力的多分辨率转码
  2. 内容审核 — 自动检测敏感内容（色情、暴恐、广告）
  3. 截图 — 生成封面图和雪碧图
  4. 反盗版 — 支持配置加密实现内容保护

Architecture

架构

OSS Bucket + MPS Pipeline + Transcoding Templates + Moderation Service
Components:
  • OSS: Store videos and outputs
  • MPS Pipeline: Task queue management
  • Transcoding Templates: Narrowband HD, Standard presets
  • Moderation: Auto content safety checks
Target Users: Video platforms, content creators, corporate training, education platforms
OSS Bucket + MPS Pipeline + Transcoding Templates + Moderation Service
组件：
  • OSS：存储视频和输出产物
  • MPS Pipeline：任务队列管理
  • 转码模板：窄带高清、标准预设
  • 审核：自动内容安全检测
目标用户：视频平台、内容创作者、企业培训、教育平台

Capability Overview

能力概览

See references/capability-overview.md for detailed feature tree and automatic pipeline management.
查看 references/capability-overview.md 了解详细的功能树和自动流水线管理说明。

Prerequisites

前置要求

Pre-check: Aliyun CLI >= 3.3.1 required Run 
aliyun version
to verify >= 3.3.1. If not installed, see 
references/cli-installation-guide.md
. Then [MUST] run 
aliyun configure set --auto-plugin-install true
to enable automatic plugin installation.
Pre-check: Python >= 3.10 required Run 
python3 --version
to verify.
Pre-check: Alibaba Cloud Credentials Required
Run 
aliyun configure list
to check credential status. If no valid profile, configure via 
aliyun configure
. See references/security-guidelines.md for credential security rules.
预检查：要求Aliyun CLI版本 >= 3.3.1 运行 
aliyun version
验证版本符合要求，若未安装可参考 
references/cli-installation-guide.md
。 之后【必须】运行 
aliyun configure set --auto-plugin-install true
开启自动插件安装功能。
预检查：要求Python版本 >= 3.10 运行 
python3 --version
验证版本符合要求。
预检查：需要阿里云凭证
运行 
aliyun configure list
检查凭证状态，若无有效配置文件可通过 
aliyun configure
进行配置。 凭证安全规则可参考 references/security-guidelines.md。

Environment Variables

环境变量

Required environment variables:
  • ALIBABA_CLOUD_REGION
    - Service region (default: cn-shanghai)
  • ALIBABA_CLOUD_OSS_BUCKET
    - OSS Bucket name
  • ALIBABA_CLOUD_OSS_ENDPOINT
    - OSS endpoint
  • ALIBABA_CLOUD_MPS_PIPELINE_ID
    - MPS Pipeline ID (optional, auto-selected if not set)
Security Note: Credentials are managed via the Alibaba Cloud default credential chain. Configure credentials using 
aliyun configure
command. NEVER handle AK/SK directly in scripts or commands.
必填环境变量：
  • ALIBABA_CLOUD_REGION
    - 服务区域（默认：cn-shanghai）
  • ALIBABA_CLOUD_OSS_BUCKET
    - OSS Bucket名称
  • ALIBABA_CLOUD_OSS_ENDPOINT
    - OSS接入端点
  • ALIBABA_CLOUD_MPS_PIPELINE_ID
    - MPS Pipeline ID（可选，未设置时自动选择）
安全提示： 凭证通过阿里云默认凭证链管理，请使用 
aliyun configure
命令配置凭证，切勿在脚本或命令中直接处理AK/SK。

🔒 Security Guidelines

🔒 安全指南

See references/security-guidelines.md for complete security guidelines and credential management best practices.
查看 references/security-guidelines.md 了解完整的安全指南和凭证管理最佳实践。

SDK Installation

SDK安装

See references/sdk-installation.md for detailed installation guide and troubleshooting.
Run 
python3 --version
to verify. Some scripts may fail with older Python versions.
查看 references/sdk-installation.md 了解详细的安装指南和问题排查方法。
运行 
python3 --version
验证Python版本，旧版本Python可能导致部分脚本运行失败。

RAM Permissions

RAM权限

[MUST] RAM Permission Pre-check: Verify that the current user has the following RAM permissions before execution. See 
references/ram-policies.md
for complete permission list and details.
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
  1. Read 
    references/ram-policies.md
    to get the full list of permissions required by this SKILL
  2. Use 
    ram-permission-diagnose
    skill to guide the user through requesting the necessary permissions
  3. Pause and wait until the user confirms that the required permissions have been granted
【必须】RAM权限预检查： 执行前请确认当前用户拥有以下RAM权限。 完整的权限列表和说明可参考 
references/ram-policies.md
。
【必须】权限失败处理： 执行过程中任意阶段的命令或API调用因权限错误失败时，请遵循以下流程：
  1. 查看 
    references/ram-policies.md
    获取本工具所需的完整权限列表
  2. 使用 
    ram-permission-diagnose
    工具引导用户申请所需权限
  3. 暂停执行，直到用户确认已授予所需权限

Parameter Confirmation

参数确认

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., input video path, output bucket, template ID, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
ParameterRequired/OptionalDescriptionDefault
input-urlRequiredInput video URL or local path-
output-bucketOptionalOutput OSS BucketEnvironment variable value
output-pathOptionalOutput path prefixoutput/
template-idOptionalTranscoding template IDSystem preset template
resolutionsOptionalTranscoding resolution list720p,1080p
auditOptionalWhether to perform content moderationtrue
pipeline-idOptionalMPS Pipeline IDAuto-select
重要提示：参数确认 — 执行任何命令或API调用前，所有用户可自定义参数（例如输入视频路径、输出Bucket、模板ID等）必须与用户确认。未经用户明确许可，请勿假设参数值或使用默认值。
参数必填/可选描述默认值
input-url必填输入视频URL或本地路径-
output-bucket可选输出OSS Bucket环境变量值
output-path可选输出路径前缀output/
template-id可选转码模板ID系统预设模板
resolutions可选转码分辨率列表720p,1080p
audit可选是否执行内容审核true
pipeline-id可选MPS Pipeline ID自动选择

Core Workflow

核心工作流

Scenario 1: One-stop Video Standardization

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

Complete workflow: User provides video → Upload to OSS → Media info probe → Cover generation (snapshot) → Multi-resolution transcoding → Content moderation → Summary results (with download links)
完整工作流：用户提供视频 → 上传到OSS → 媒体信息探测 → 封面生成（截图）→ 多分辨率转码 → 内容审核 → 结果汇总（含下载链接）

Step 0: Automatic Pipeline Selection (Optional)

步骤0：自动流水线选择（可选）

This skill supports automatic pipeline management, typically no manual Pipeline ID configuration needed. Scripts automatically select appropriate pipelines based on task type.
To manually specify:
bash
undefined
本工具支持自动流水线管理，通常无需手动配置Pipeline ID，脚本会根据任务类型自动选择合适的流水线。
如需手动指定：
bash
undefined

Method 1: Set environment variable (highest priority)

Method 1: Set environment variable (highest priority)

export ALIBABA_CLOUD_MPS_PIPELINE_ID="your-pipeline-id"
export ALIBABA_CLOUD_MPS_PIPELINE_ID="your-pipeline-id"

Method 2: Command line parameter

Method 2: Command line parameter

python scripts/mps_transcode.py --oss-object /input/video.mp4 --pipeline-id your-pipeline-id
python scripts/mps_transcode.py --oss-object /input/video.mp4 --pipeline-id your-pipeline-id

Method 3: Use script auto-selection

Method 3: Use script auto-selection

export ALIBABA_CLOUD_MPS_PIPELINE_ID=$(python scripts/mps_pipeline.py --select)
undefined
export ALIBABA_CLOUD_MPS_PIPELINE_ID=$(python scripts/mps_pipeline.py --select)
undefined

Step 1: Upload Video to OSS

步骤1：上传视频到OSS

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

Step 2: Media Info Probe

步骤2：媒体信息探测

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

Step 3: Cover Generation (Snapshot)

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

Use snapshot function to generate video cover at specified time:
bash
python scripts/mps_snapshot.py --oss-object /input/video.mp4 --mode normal --time 5000
使用截图功能在指定时间点生成视频封面：
bash
python scripts/mps_snapshot.py --oss-object /input/video.mp4 --mode normal --time 5000

Step 4: Adaptive Transcoding (Auto-select best resolution and Narrowband HD template)

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

bash
undefined
bash
undefined

Adaptive mode: Auto-detect source video resolution, select best quality, use Narrowband HD template

自适应模式：自动检测源视频分辨率，选择最佳画质，使用窄带高清模板

python scripts/mps_transcode.py --oss-object /input/video.mp4
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
undefined
python scripts/mps_transcode.py
--oss-object /input/video.mp4
--preset multi
undefined

Step 5: Content Moderation

步骤5：内容审核

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

Step 6: Poll Task Status

步骤6：轮询任务状态

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

Complete Example

完整示例

bash
undefined
bash
undefined

1. Activate virtual environment

1. 激活虚拟环境

source .venv/bin/activate
source .venv/bin/activate

2. Upload video

2. 上传视频

python scripts/oss_upload.py --local-file ./my_video.mp4 --oss-key input/my_video.mp4
python scripts/oss_upload.py --local-file ./my_video.mp4 --oss-key input/my_video.mp4

3. Get media info

3. 获取媒体信息

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

4. Cover generation (snapshot at 5 seconds)

4. 封面生成（第5秒截图）

python scripts/mps_snapshot.py --oss-object /input/my_video.mp4 --mode normal --time 5000
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)

5. 提交转码任务（自适应模式：自动选择最佳分辨率）

python scripts/mps_transcode.py
--oss-object /input/my_video.mp4
python scripts/mps_transcode.py
--oss-object /input/my_video.mp4

Save the returned job-id

保存返回的job-id

6. Poll transcoding job status

6. 轮询转码任务状态

python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai --interval 10
python scripts/poll_task.py --job-id <job-id> --job-type transcode --region cn-shanghai --interval 10

7. Content moderation

7. 内容审核

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

8. Download processed video to local

8. 下载处理后的视频到本地

python scripts/oss_download.py --oss-key output/transcode/transcoded.mp4 --local-file ./output_video.mp4
undefined
python scripts/oss_download.py --oss-key output/transcode/transcoded.mp4 --local-file ./output_video.mp4
undefined

Other Scenarios

其他场景

Scenario 2: Transcoding Only

场景2：仅转码

Execute transcoding only, without snapshot and moderation:
bash
source .venv/bin/activate
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset 1080p \
  --template-id "your-template-id"
仅执行转码，不进行截图和审核：
bash
source .venv/bin/activate
python scripts/mps_transcode.py \
  --oss-object /input/video.mp4 \
  --preset 1080p \
  --template-id "your-template-id"

Scenario 3: Content Moderation

场景3：仅内容审核

Execute content moderation only:
bash
source .venv/bin/activate
python scripts/mps_audit.py \
  --oss-object /input/video.mp4 \
  --scenes porn terrorism ad
仅执行内容审核：
bash
source .venv/bin/activate
python scripts/mps_audit.py \
  --oss-object /input/video.mp4 \
  --scenes porn terrorism ad

Success Verification

成功验证

After video processing, check results:
  1. Script exit code is 0
  2. Output contains processed media info (OSS path)
  3. Transcoding job status is "Success"
  4. Content moderation shows no violations
  5. Artifacts downloaded locally (using 
    oss_download.py
    )
Notes on Artifact Retrieval:
  • OSS files require signing for online access, direct URL access returns 403 error
  • Recommend using 
    oss_download.py
    to download results locally
  • For online preview, use 
    --sign-url
    parameter to generate temporary pre-signed URL
bash
undefined
视频处理完成后，可通过以下项检查结果：
  1. 脚本退出码为0
  2. 输出包含处理后的媒体信息（OSS路径）
  3. 转码任务状态为「Success」
  4. 内容审核无违规内容
  5. 产物已下载到本地（使用 
    oss_download.py
    ）
产物获取注意事项：
  • OSS文件需要签名才能在线访问，直接访问URL会返回403错误
  • 推荐使用 
    oss_download.py
    将结果下载到本地
  • 如需在线预览，可使用 
    --sign-url
    参数生成临时预签名URL
bash
undefined

Verify transcoding success

验证转码成功

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

Expected output: Status: Success

预期输出：Status: Success

Verify moderation result

验证审核结果

python scripts/mps_audit.py --query-job-id <audit-job-id>
python scripts/mps_audit.py --query-job-id <audit-job-id>

Expected output: Moderation passed, no violations

预期输出：Moderation passed, no violations

undefined
undefined

Troubleshooting

故障排查

See references/troubleshooting.md for comprehensive troubleshooting guide.
查看 references/troubleshooting.md 了解完整的故障排查指南。

Cleanup

清理

Intermediate files and output files from this skill are stored in OSS. To clean up:
bash
undefined
本工具产生的中间文件和输出文件都存储在OSS中，可通过以下方式清理：
bash
undefined

Delete single file

删除单个文件

python scripts/oss_delete.py --oss-key output/transcode/video.mp4
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
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
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

> **Note**: Delete operations are irreversible. Confirm before executing. Use `--dry-run` to preview first.
python scripts/oss_delete.py --prefix output/ --recursive --dry-run

> **注意：** 删除操作不可逆，执行前请确认。建议先使用 `--dry-run` 预览。

Available Scripts

可用脚本

ScriptDescription
scripts/load_env.py
Environment variable loader, auto-scan and load Alibaba Cloud credentials
scripts/poll_task.py
MPS async task poller, query task status
scripts/oss_upload.py
Upload local file to OSS
scripts/oss_download.py
Download file from OSS to local
scripts/oss_list.py
List files in OSS Bucket
scripts/oss_delete.py
Delete OSS files or directories (supports recursive delete)
scripts/mps_mediainfo.py
Get media file info (resolution, bitrate, duration, etc.)
scripts/mps_snapshot.py
Snapshot and sprite sheet generation (supports normal/sprite mode)
scripts/mps_transcode.py
Video transcoding (supports adaptive Narrowband HD, multi-resolution presets, custom parameters)
scripts/mps_audit.py
Content safety moderation (supports multiple moderation scenarios)
scripts/mps_pipeline.py
Pipeline list query and auto-selection (get Pipeline ID)
脚本描述
scripts/load_env.py
环境变量加载器，自动扫描并加载阿里云凭证
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 ID）

Best Practices

最佳实践

  1. Always check environment variables first — Run 
    python scripts/load_env.py --check-only
    at the start of each session
  2. Use polling instead of waiting — Use 
    poll_task.py
    to auto-poll status after submitting jobs
  3. Choose resolutions wisely — Select appropriate transcoding resolutions based on target user devices
  4. Enable content moderation — For UGC content, always enable automatic moderation
  5. Use virtual environment — Ensure dependency isolation to avoid version conflicts
  6. Automatic pipeline management — No need to manually configure Pipeline ID, scripts auto-select appropriate pipelines based on task type
  1. 始终优先检查环境变量 — 每次会话开始时运行 
    python scripts/load_env.py --check-only
  2. 使用轮询代替等待 — 提交任务后使用 
    poll_task.py
    自动轮询状态
  3. 合理选择分辨率 — 根据目标用户设备选择合适的转码分辨率
  4. 开启内容审核 — 针对UGC内容，始终开启自动审核
  5. 使用虚拟环境 — 确保依赖隔离，避免版本冲突
  6. 自动流水线管理 — 无需手动配置Pipeline ID，脚本会根据任务类型自动选择合适的流水线

Reference Documentation

参考文档

DocumentDescription
references/ram-policies.mdComplete RAM permission policy list
references/params.mdScript parameter documentation
references/scripts-detail.mdDetailed script usage examples
references/verification-method.mdSuccess verification methods
references/related-commands.mdRelated CLI commands
references/cli-installation-guide.mdAliyun CLI installation guide
references/acceptance-criteria.mdTesting acceptance criteria
文档描述
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.mdAliyun CLI安装指南
references/acceptance-criteria.md测试验收标准

CLI Command Standards

CLI命令规范

Important: If using 
aliyun
CLI commands, all commands MUST include the 
--user-agent AlibabaCloud-Agent-Skills
parameter. Example: 
aliyun mts search-pipeline --PageNumber 1 --PageSize 10 --user-agent AlibabaCloud-Agent-Skills
重要提示： 如果使用 
aliyun
CLI命令，所有命令必须携带 
--user-agent AlibabaCloud-Agent-Skills
参数。 示例：
aliyun mts search-pipeline --PageNumber 1 --PageSize 10 --user-agent AlibabaCloud-Agent-Skills