alibabacloud-video-forge

What this skill does

# 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](references/security-guidelines.md) for credential security rules.

## 🚀 Quick Start

**Easiest Way** - One-click video processing:

```bash
# 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
```bash
python scripts/video_workflow.py \
  --input my_video.mov \
  --preset 720p \
  --generate-cover \
  --scenes porn terrorism ad
```

#### Scenario 2: UGC Content Moderation
```bash
python scripts/mps_audit.py --oss-object /input/user_uploaded.mp4
```

#### Scenario 3: Multi-Resolution Transcoding
```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

### 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](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](references/security-guidelines.md) for complete security guidelines and credential management best practices.

## SDK Installation

See [references/sdk-installation.md](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.

| Parameter | Required/Optional | Description | Default |
|-----------|------------------|-------------|---------|
| input-url | Required | Input video URL or local path | - |
| output-bucket | Optional | Output OSS Bucket | Environment variable value |
| output-path | Optional | Output path prefix | output/ |
| template-id | Optional | Transcoding template ID | System preset template |
| resolutions | Optional | Transcoding resolution list | 720p,1080p |
| audit | Optional | Whether to perform content moderation | true |
| pipeline-id | Optional | MPS Pipeline ID | Auto-select |

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

```bash
# 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

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

```bash
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:

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

```bash
# 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

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

#### Step 6: Poll Task Status

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

#### Complete Example

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

# 2. Upload video
python scripts/oss_upload.py --local