alibabacloud-video-forge

Alibaba Cloud Video Forge

One-stop video processing through Alibaba Cloud Media Processing Service (MPS), including cover generation, multi-resolution transcoding, content moderation, and more.

Prerequisites

Pre-check: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update, or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

Pre-check: AI-Mode Configuration required [MUST] Before using aliyun CLI commands, configure 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

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.

🚀 Quick Start

Easiest Way - One-click video processing:

# 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

Common Scenarios

Scenario 1: Bilibili Video Publishing

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

Scenario 2: UGC Content Moderation

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

Scenario 3: Multi-Resolution Transcoding

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

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

Capability Overview

See references/capability-overview.md for detailed feature tree and automatic pipeline management.

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.

🔒 Security Guidelines

See references/security-guidelines.md for complete security guidelines and credential management best practices.

SDK Installation

See references/sdk-installation.md for detailed installation guide and troubleshooting.

Run python3 --version to verify. Some scripts may fail with older Python versions.

RAM Permissions

[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

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.

Core Workflow

Scenario 1: One-stop Video Standardization

Complete workflow: User provides video → Upload to OSS → Media info probe → Cover generation (snapshot) → Multi-resolution transcoding → Content moderation → Summary results (with download links)

Step 0: Automatic Pipeline Selection (Optional)

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:

# 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)

Step 1: Upload Video to OSS

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

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

Step 3: Cover Generation (Snapshot)

Use snapshot function to generate video cover at specified time:

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)

# 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

Step 5: Content Moderation

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

Step 6: Poll Task Status

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

Complete Example

# 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

Other Scenarios

Scenario 2: Transcoding Only

Execute transcoding only, without snapshot and moderation:

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

Execute content moderation only:

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

# 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

Troubleshooting

See references/troubleshooting.md for comprehensive troubleshooting guide.

---

Cleanup

Intermediate files and output files from this skill are stored in OSS. To clean up:

# 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

Note: Delete operations are irreversible. Confirm before executing. Use --dry-run to preview first.

Available Scripts

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

Reference Documentation

AI-Mode Configuration

[MUST] AI-Mode Setup for Aliyun CLI — Before using aliyun CLI commands, you must configure AI-Mode to enable proper tracking and plugin management.

Enable AI-Mode

Enable AI-Mode for enhanced functionality:

aliyun configure ai-mode enable

Configure User-Agent

Set the User-Agent for proper skill identification:

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

Disable AI-Mode

Disable AI-Mode when no longer needed:

aliyun configure ai-mode disable

Note: AI-Mode must be enabled before executing any aliyun CLI commands to ensure proper functionality tracking and plugin compatibility.

CLI Command Standards

Important: User-Agent is automatically applied via AI-Mode configuration. After running aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge", all subsequent aliyun CLI commands will include the correct User-Agent automatically. No need to add --user-agent parameter to each command.