Alibabacloud Oss Media Process

Alibaba Cloud OSS Media Processing

Process images, audio, and video files stored in Alibaba Cloud OSS using native OSS media processing capabilities. Synchronous processing returns immediate results via x-oss-process; asynchronous processing handles long-running jobs via x-oss-async-process with polling.

Default language: 默认中文回复。Only use English when the user explicitly writes in English.

Quick Start

Working directory

All script commands run from the skill package root. Use full absolute paths to invoke scripts:

python /path/to/skill/scripts/process.py ...

Do not cd into the directory and use relative paths. If a script fails with "No such file or directory", use Glob to find **/alibabacloud-oss-media-process/scripts/process.py and use its full path.

Setup workspace output directory (run once per session):

WORKSPACE_OUTPUT=$(pwd)/outputs && mkdir -p "$WORKSPACE_OUTPUT"

All --output-path arguments MUST use $WORKSPACE_OUTPUT/<filename> — files saved inside the skill directory will NOT be renderable.

Credentials (Aliyun CLI)

This skill uses Aliyun CLI for credential management. Python scripts auto-discover credentials via the alibabacloud-credentials default chain (supporting ~/.aliyun/config.json, environment variables, ECS instance roles, etc.).

Security rules:

• Never read, echo, print, cat, or dump ~/.aliyun/config.json, credential files, or any raw command output that contains access_key_id, access_key_secret, sts_token, AccessKeyId, AccessKeySecret, or SecurityToken values.
• Never ask the user to input AK/SK directly in the conversation or command line
• Guide users to use aliyun configure to set up credentials securely
• Never write AccessKeyId, AccessKeySecret, or SecurityToken into any temporary Python/Shell script, here-doc, env export, or intermediate file. All credentials must be discovered through Aliyun CLI or the SDK default credential chain.
• For credential diagnostics, use aliyun configure list, python scripts/load_env.py, or other non-secret checks. If you must inspect configuration structure, only inspect non-sensitive fields and do not print secret or token values to the transcript.
• Treat full presigned URLs as sensitive whenever they contain signing parameters such as OSSAccessKeyId, accessKeyId, x-oss-credential, Signature, x-oss-signature, security-token, SecurityToken, or sts_token. Do not print these full URLs into the conversation transcript, command echo, markdown summary, or ordinary log files.
• When a signed URL is needed for user consumption, distinguish between delivery and display: it is acceptable to generate a usable signed URL, but unless the runtime provides a secure private-output channel that does not enter the transcript or logs, only display a redacted URL or an OSS path in normal user-facing text.

Prerequisites

Blocking preflight policy:

• python scripts/load_env.py may report missing SDKs, missing credentials, missing bucket/region, or RAM permission problems.
• aliyun configure list must show a usable configured CLI profile.
• Treat preflight results as stale after any environment or runtime change. If you install Python packages, run aliyun configure, change env vars, edit shell profiles, switch users, or otherwise modify credential/runtime state, you must rerun both python scripts/load_env.py and aliyun configure list before the next python scripts/process.py ... command.
• If either command fails these checks, stop immediately.
• Do not run python scripts/process.py ....
• Do not retry media processing.
• Do not simulate a successful result.
• Return only configuration guidance until both checks pass.

AI-Mode

Enable at session start:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-media-process"

Disable on every exit: success, failure, error, cancellation, or session end:

aliyun configure ai-mode disable

Preflight then Execute

When the user requests a media operation (resize, detect faces, watermark, etc.), apply the blocking preflight policy above before running any python scripts/process.py ... command. process.py also performs a runtime dependency preflight and exits with pip install -r scripts/requirements.txt guidance if required SDKs are missing. If you change the environment after a failed attempt (for example by installing dependencies, editing env vars, or re-running aliyun configure), do not assume the earlier preflight still holds — rerun the full blocking preflight first.

First-time setup

Direct users to run aliyun configure to set up credentials, then verify with:

aliyun configure list

Python scripts use the alibabacloud-credentials SDK to auto-discover credentials from the Aliyun CLI config. Bucket and region are read from the ALIBABA_CLOUD_OSS_BUCKET / ALIBABA_CLOUD_OSS_REGION environment variables, or from --bucket / --region CLI flags. load_env.py scans shell config files (~/.bashrc, ~/.zshrc) for these exports and loads them into os.environ.

Recommended Workflow

Follow this numbered workflow for every request:

1. Prepare Confirm the bucket and region are available through --bucket / --region or the ALIBABA_CLOUD_OSS_BUCKET / ALIBABA_CLOUD_OSS_REGION environment variables. Apply the blocking preflight policy before any media command. Create $WORKSPACE_OUTPUT once per session for all local downloads.

2. Choose the source Use --source for an existing OSS object key. Use --uri for a local file path or HTTP(S) URL that should be uploaded temporarily before processing.

3. Decide the execution path Use python scripts/process.py for all media processing and file operations. If the request involves video, audio, HLS, or image-intelligent features, run python scripts/imm_admin.py auto-setup --bucket <b> --region <r> first to ensure IMM bucket binding exists.

4. Execute Build exactly one valid operation chain. Prefer --output-mode download --output-path $WORKSPACE_OUTPUT/<name> for sync image outputs, --output-mode save --target-key <key> for async media outputs, and --output-mode url when the result is meant to be consumed remotely.

5. Verify Read the returned JSON. Check success, request_id, task_id (async only), target_key, local path, and any validation_warnings. If the command downloaded a local file, present the absolute path to the user. Only report a local output path after the file was actually written to $WORKSPACE_OUTPUT and the returned absolute path matches the real downloaded file. Do not claim that a file was saved to outputs/... or any other local path unless it truly exists there. If you need to record task_id, request_id, target_key, generated_keys, or similar fields in logs, notes, or output files, extract them directly from the process.py JSON response. Do not transcribe, rewrite, or manually retype these values. If the user or eval explicitly requires verification of any machine-verifiable output property (for example codec, bitrate, sample rate, channel count, duration, resolution, frame rate, width, height, or format), prefer running one additional read-only verification step against a persisted OSS output object before finalizing the summary. Use audio/info or video/info for audio/video outputs, and use a separate --operations info command for image outputs. Do not download the file locally just for this purpose. For image width, height, format, and file-size verification, treat OSS-side --operations info on the saved target object as the default and preferred verification path. info is a standalone read-only image metadata operation, not a follow-up segment that should be appended to a basic image processing chain. Do not switch to local image-library inspection when info can answer the question. If a read-only verification step was performed and its result differs from the requested value, report the actual verified output value. Do not substitute the request value, and do not claim the request was fully satisfied when the verification result shows otherwise. If no read-only verification step was performed, do not describe machine-verifiable output properties as independently confirmed. Do not assume local verification tools such as PIL/Pillow, ffprobe, or similar utilities are installed. If a tool is unavailable, do not claim that you performed the corresponding local pixel-level or media-property verification. For image-property verification in particular, do not introduce ad hoc local-library checks such as PIL/Pillow unless the workflow explicitly requires a local-file-only inspection and OSS-side info cannot provide the property. In normal skill usage and evals, prefer OSS-side verification and avoid emitting local PIL/Pillow commands entirely. If the workflow returns only a signed URL and does not persist a reusable OSS target object, do not claim that you performed a follow-up info check on the final output object unless such an object actually exists. In that case, either save the result to OSS first and verify the saved object, or state that only the immediate processing result was available and no persisted-object verification was performed. Before sending the final user-facing summary, follow the Language rule in Result Presentation.

6. Recover If the command fails, use the Error Recovery table below. Retry only after correcting the concrete cause, such as missing IMM binding, bad parameters, or insufficient RAM permissions.

---

Quick Decision Guide

All processing goes through process.py

Image, video, and audio operations MUST be executed via python scripts/process.py --operations "...". The agent must not write its own SDK or CLI calls to bypass process.py or imm_admin.py for video/audio/image processing. Underlying SDK or API requests triggered internally by these scripts (including IMM requests such as CreateMediaConvertTask) are expected implementation behavior and do not count as direct agent-side SDK usage. The only intentional script-level IMM entry points are imm_admin.py for project setup and blindwatermark-extract for async watermark extraction.

Never create your own Python scripts or wrappers to bypass process.py. When process.py doesn't support a feature, check SKILL.md and references/ documentation, use --dry-run to preview, and report to the user if it truly cannot be done.

IMM setup (before IMM-dependent ops)

Before running video, audio, HLS, or image-intelligent operations, first run imm_admin.py auto-setup to ensure the bucket is bound to an IMM project. Pass --imm-project <project_name> only for blindwatermark-extract, or if you intentionally want to override the optional ALIBABA_CLOUD_IMM_PROJECT fallback used by that operation.

Source selection

• OSS object → --source object-key
• Local file or URL → --uri /path/to/file (auto-uploads, processes, cleans up)

Sync vs Async (auto-detected)

• Sync (x-oss-process): image ops, video/snapshot, video/info, audio/info, hls/m3u8, AI detection
• Async (x-oss-async-process): video/convert, video/animation, video/snapshots, video/sprite, video/concat, audio/convert, audio/concat, blindwatermark-extract

The script auto-detects async-only operations and handles routing/polling automatically — no --async or --wait flags needed.

Output rules

All --output-path MUST use $WORKSPACE_OUTPUT/<filename> — files saved inside the skill directory will NOT be renderable.

No-local-download rule: if the user explicitly says not to download locally, only to save in OSS, or only to return a link/URL, do not pass --output-path and do not perform any follow-up download for verification. Use --output-mode url for sync results meant to be consumed remotely, and use --output-mode save --target-key ... for async media results that should remain in OSS. Never download to $WORKSPACE_OUTPUT, /tmp, or any local path just to verify success; rely on the process.py JSON response instead.

Ambiguous save wording rule: if the user says "保存", "保存下来", "存起来", or similar wording but does not explicitly say "下载到本地", "本地查看", "给我本地文件", or another clear local-destination phrase, default to saving the result back to OSS with --output-mode save --target-key .... Only use --output-mode download --output-path ... when the user explicitly asks for a local file. If the user only wants to inspect the result and does not require a persisted local copy, prefer --output-mode url for sync outputs and --output-mode save plus the OSS path for async outputs.

Signed-URL delivery rule: the purpose of --output-mode url is to make a remote result accessible, not to force the full signed query string into the transcript. In ordinary text responses, prefer an OSS path or a redacted URL. Only provide a full presigned URL when the runtime offers a secure private-output channel that keeps the raw URL out of transcript/log surfaces. If no such channel exists, explain the limitation briefly and avoid printing the full signed query parameters. A redacted URL should keep the path and any non-sensitive query parameters, while replacing sensitive signing values with ***, for example: https://bucket.oss-cn-hangzhou.aliyuncs.com/output/result.webp?OSSAccessKeyId=***&x-oss-credential=***&Signature=***&security-token=***&Expires=1700000000.

Unique suffix rule: when you need a unique OSS target key suffix for evals, retries, or parallel runs, prefer Python-generated UUIDs or a timestamp-plus-random suffix. Do not rely on uuidgen being available. If you must generate a suffix from shell commands, first verify the command exists; otherwise fall back to a timestamp plus random digits. Safe shell example: SUFFIX=$(python3 -c "import uuid; print(uuid.uuid4().hex[:8])" 2>/dev/null || date +%Y%m%d_%H%M%S_$RANDOM).

Chaining rules

See the dedicated Chaining Rules section below for full chaining guidelines.

---

Core Parameter Rules

1. Only pass parameters the user specifies — do not invent defaults. OSS uses official defaults for unspecified parameters (e.g., keep original width/height, original bitrate, original framerate). 2. Recipes are examples, not defaults — parameter values in recipe tables (e.g., w=800, vb=2000000) are for specific scenarios and should NOT be used as defaults. 3. video/convert — remux vs re-encode: omitting vcodec means OSS only does remux (stream copy without re-encoding). Parameters like videoslim, vb, crf, s, fps are silently ignored in remux mode. Always specify `vcodec` (default `h264`) when the user says "transcode", "compress", or "slim". Only omit vcodec for pure remux (e.g., AVI→MP4 container switch) or audio extraction. 4. video/concat — when input params differ: if input videos have different resolution, framerate, or codec, you must ask the user which video to align to (option A: first video, B: second video, C: custom params). Never auto-decide. 5. video/concat — validation scope: process.py always performs input compatibility checks before submitting the async task. Additional local ffprobe output validation only runs when the command also downloads the result via --output-path. If you use --output-mode save without a local download path, there is no post-download media validation step. 6. Snapshots vs snapshot: use video/snapshots (async) for multi-frame extraction. Never use multiple video/snapshot calls as a workaround. video/snapshots target-key must NOT have a file extension. 7. For full parameter specifications, see the corresponding reference files in references/.

---

Result Presentation

After every successful process.py execution, present results in this format:

Language rule: unless the user explicitly requested English, the final user-facing result summary in this section must be written in Chinese. Use a result template that matches the response language. For Chinese responses, use a Chinese lead-in such as 处理结果如下： and Chinese field labels such as 状态 / 请求 ID / 任务 ID / 源文件 / 输出 / 参数 / 文件大小 / OSS 路径. For English responses, use Result summary: and the corresponding English labels Status / RequestID / Task ID / Source / Output / Params / File Size / OSS Path.

1. File path: output the local absolute path in a code block (e.g., /path/to/outputs/snapshot.jpg). Never use open or Read tool to display files. Only include this section when the file was actually downloaded or written locally. Do not present an outputs/... path that was only planned, inferred, or mentioned in a transcript.

2. Result table:

Field sourcing rules: Status and Params must be quoted directly from the process.py JSON response. Status must come from the returned success field, and Params must come from the returned operations field. Never rewrite, estimate, normalize, or summarize numeric/media values by hand, including confidence scores, bitrate, resolution, dimensions, frame rate, or codec details.

If you need a textual summary, include the original command or process string in a fenced code block and describe it conservatively. Do not invent parameter values or restate them in free-form prose when they are not explicitly present in the process.py response.

Final summary constraints:

• Do not insert fixed English filler such as Task Completed Successfully.
• Numeric values such as sample rate, bitrate, resolution, duration, frame rate, and file count must be copied directly from process.py JSON fields or an explicitly performed read-only verification result.
• If a value was not obtained directly from machine output, omit it instead of rewriting, estimating, rounding, or normalizing it by hand.
• If an explicitly performed read-only verification result differs from the requested value, report the actual verified output value and describe the request as only partially satisfied when necessary. Do not replace the verified value with the requested one.
• If no read-only verification result was obtained, do not claim that machine-verifiable output properties were independently confirmed.

If the user forbids local downloads, omit the File path row/section entirely and do not create temporary local files for validation. In that case, present only the JSON-backed metadata returned by process.py, such as success, request_id, task_id, target_key, generated_keys, or url.

If process.py returns a signed URL, treat the full query string as sensitive output. In normal visible summaries, prefer the OSS path, target key, or a redacted URL. Do not expand raw signing parameters into the final summary unless the runtime has a secure private-output channel for secret delivery.

If independent verification was requested but the workflow returned only a signed URL and did not create a persisted OSS target object, do not claim that a follow-up info check was performed on a final output object. Either save the result first and verify the saved object, or state clearly that no persisted-object verification was available.

For image outputs and visual effects such as watermarks, overlays, blur regions, or face redaction, distinguish between metadata verification and visual verification. If the output was not downloaded or rendered locally, do not claim that a visual element was independently confirmed by inspection; state that only the service-reported processing result was verified unless a local render or explicit inspection step was actually performed.

Rules:

• Do not run video/info, audio/info, or image --operations info after processing for ordinary result reporting. However, if the user explicitly asks you to verify concrete machine-verifiable output properties such as codec, bitrate, sample rate, channel count, duration, resolution, frame rate, width, height, or format, or if the eval/acceptance criteria explicitly require an independent property check, prefer running one additional read-only verification step against a persisted OSS output object and report that verification separately from the main process.py result. Use audio/info or video/info for audio/video outputs, and use a separate --operations info command for image outputs.
• Do not assume local verification libraries or binaries such as PIL/Pillow, ffprobe, or similar tools are preinstalled. Use them only when they are actually available and the workflow genuinely requires a local-file check; otherwise rely on process.py JSON output and permitted read-only OSS-side checks.
• For image width/height/format verification, prefer OSS-side --operations info on the saved target object even if a local file is present. Do not use PIL/Pillow as the default verification method for evals or routine skill runs.
• Requests to verify image width, height, format, or similar machine-verifiable properties do not by themselves authorize a local download. If the user did not explicitly request a local file, and a saved OSS target object can be verified with info, do not switch to --output-mode download solely for verification.
• Do not use head_object as a substitute for media-property verification.
• Avoid sleep + retry loops; the script handles async polling internally.
• All media processing goes through process.py; if unsupported, check references/ and report — do not write custom scripts.

---

Chaining Rules

Image Operations

• Basic operations can be freely chained with each other
• blindwatermark-embed can follow basic ops but must be the last operation
• blindwatermark-extract must be used alone — no chaining
• AI detection (faces, bodies, cars, codes, labels, score) must be used alone

Video/Audio Operations

• Video/audio operations cannot be chained with image operations
• Only one video/audio operation per request (no chaining)
• For complex workflows, use multiple separate requests

---

Credential & Environment Setup

Credentials are managed by Aliyun CLI (~/.aliyun/config.json). Python scripts auto-discover them via the alibabacloud-credentials SDK default chain. See Prerequisites above for setup steps.

Diagnostic check:

python scripts/load_env.py

This scans for legacy env vars and verifies RAM permissions. Use this if operations fail with access errors.

Runtime dependency preflight: process.py checks required Python packages before execution. Basic OSS/file operations require oss2 and alibabacloud-credentials; video/audio/HLS/IMM operations also require the IMM SDK packages from scripts/requirements.txt. If any dependency is missing, the command fails fast with an install hint instead of starting a partial execution.

IMM project — usually discovered by imm_admin.py auto-setup. process.py only consumes --imm-project / ALIBABA_CLOUD_IMM_PROJECT for blindwatermark-extract.

---

IMM Auto-Setup

Video/audio processing and image-intelligent features require an IMM project bound to the bucket. Follow this workflow for IMM-dependent operations:

Step 1 — Detect IMM project (before any processing command):

python scripts/imm_admin.py auto-setup --bucket <bucket> --region <region>

This ensures the bucket is bound to a usable IMM project and prints the resolved project name.

Step 2 — Execute the media operation:

python scripts/process.py --source video.mp4 \
  --operations "video/convert:f=mp4,vcodec=h264" \
  --output-mode save --target-key output/video.mp4

For blindwatermark-extract, append --imm-project <project_name> if you do not want to rely on the optional ALIBABA_CLOUD_IMM_PROJECT fallback.

Step 3 — Present results per Execution & Output Workflow above.

Operations that require IMM bucket setup: all video/audio/HLS ops, image-intelligent ops (faces, bodies, cars, codes, labels, score, blindwatermark-embed/extract), smart crop (crop:g=auto/crop:g=face), face blur (blur:g=face/blur:g=faces). Only blindwatermark-extract requires the project name as a direct process.py input.

---

Available Operations

Image Processing (Sync)

Image-Intelligent (IMM)

Video Processing

Audio Processing

HLS Streaming

File Operations

---

Processing Modes

• Synchronous (x-oss-process): image basic processing, video/snapshot, video/info, audio/info, hls/m3u8, AI detection — results returned immediately
• Asynchronous (x-oss-async-process): video/audio transcoding, animation, sprite, snapshots, concat, blindwatermark-extract — auto-detected, auto-polled until completion

---

Usage

python scripts/process.py \
  [--bucket BUCKET_NAME] \
  [--region REGION_ID] \
  (--source OSS_OBJECT_KEY | --uri URI) \
  --operations OPERATION [OPERATION ...] \
  [--output-mode url|download|save] \
  [--expires SECONDS] \
  [--output-path LOCAL_PATH] \
  [--target-key OSS_TARGET_KEY] \
  [--endpoint CUSTOM_ENDPOINT] \
  [--imm-project IMM_PROJECT_NAME] \
  [--dry-run]

--imm-project is only consumed by blindwatermark-extract; other operations rely on IMM bucket binding, not this flag.

--uri

Process a file from a local file path or URL (http/https) without pre-uploading. The script auto-uploads to a temp key, processes, and cleans up. --uri and --source are mutually exclusive.

--dry-run

Prints the generated process string and operation details as JSON to stdout, then exits without connecting to OSS.

Operation String Format

Each operation: name:key=value,key=value. No-param operations use just the name (e.g., info, video/info). Video/audio operations use slash notation: video/convert, audio/convert.

End-to-End Example

User request:

Resize `images/photo.jpg` in OSS to width 600px, add a bottom-right text watermark `Copyright 2026`, and download the result locally. The bucket is `my-media-bucket` in region `cn-shanghai`.

Command:

python scripts/process.py --bucket my-media-bucket --region cn-shanghai \
  --source images/photo.jpg \
  --operations "resize:w=600" "watermark:text=Copyright 2026,g=se,opacity=60,size=30" \
  --output-mode download \
  --output-path "$WORKSPACE_OUTPUT/photo-watermarked.jpg"

Expected result shape:

{
  "success": true,
  "mode": "download",
  "path": "/absolute/path/to/outputs/photo-watermarked.jpg",
  "size": 12345,
  "request_id": "xxxxxx"
}

Interpretation:

• success: true means OSS processing completed successfully.
• path is the local file path you should present to the user.
• request_id is the server-side request trace ID for troubleshooting.

Additional Examples

# HLS streaming (with IMM auto-setup)
python scripts/imm_admin.py auto-setup --bucket my-bucket --region cn-hangzhou
# → Capture project name from output
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source videos/input.mp4 \
  --operations "hls/m3u8:ss=15000,t=1800000,vcodec=h264,fps=25,s=1280x720,vb=2000000,acodec=aac,ab=128000" \
  --output-mode url

# Upload a local file to OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --uri /path/to/report.pdf --operations upload --target-key documents/report.pdf

# Download a file from OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source documents/report.pdf --operations download --output-path $WORKSPACE_OUTPUT/report.pdf

Edge Cases

• watermark values that contain commas should be quoted. For example: preprocess="resize:w=200,text=demo,image/logo.png".
• video/snapshots target keys must not include a file extension. Use output/frames/frame, not output/frames/frame.jpg.
• video/concat always performs input compatibility checks before task submission. Additional local ffprobe output validation only runs when the result is also downloaded via --output-path.
• Async media polling defaults to 600 seconds. Override with --timeout-seconds <n> or ALIBABA_CLOUD_ASYNC_TIMEOUT_SECONDS.
• blindwatermark-extract must run alone. blindwatermark-embed can follow basic image operations, but it must be the last operation in the chain.

---

Error Recovery

---

Quick References

• Parameter details: references/image-basic-operations.md, references/image-imm-operations.md, references/video-operations.md, references/audio-operations.md
• RAM Permissions: references/ram-policies.md
• Format Support & Limitations: references/limitations.md
• IMM Administration: references/imm-admin.md

Audio Operations Parameter Reference

Detailed parameter specifications for audio processing operations. Audio operations use slash notation (e.g., audio/convert, audio/concat). Only one audio operation can be specified per request — no chaining with other video/audio/image operations.

Table of Contents

• audio/convert — Audio Transcoding
• audio/concat — Audio Concatenation
• audio/info — Audio Metadata

---

audio/convert — Audio Transcoding

Transcode audio to a different format, bitrate, or sample rate. Asynchronous ONLY — requires --async flag.

Note: aq and ab are mutually exclusive. Use aq for quality-based encoding or ab for bitrate-based encoding.

Examples:

audio/convert:f=aac,ab=96000,ar=48000,ac=2
audio/convert:f=mp3,ab=192000,ar=44100,ac=2
audio/convert:f=mp3,aq=90,ar=44100,ac=2
audio/convert:f=flac,ar=48000,ac=2,adepth=24
audio/convert:f=opus,ab=64000,ar=48000,ac=1
audio/convert:f=aac,ss=5000,t=30000,ab=128000

---

audio/concat — Audio Concatenation

Concatenate multiple audio files into one. Asynchronous ONLY — requires --async flag.

The first audio file is specified via --source. Additional audio files are appended using /pre (before main) and /sur (after main) segments with their parameters.

Segment syntax (for additional audio files):

• /pre,o_<base64_key>,ss_<ms>,t_<ms> — prepend segment
• /sur,o_<base64_key>,ss_<ms>,t_<ms> — append segment

Where <base64_key> is the URL-safe Base64-encoded OSS object key.

Examples:

audio/concat:f=mp3,ab=192000,ar=44100,ac=2,align=0
audio/concat:f=aac,ab=128000,ar=48000,ac=2
audio/concat:f=flac,ar=48000,ac=2,adepth=24

---

audio/info — Audio Metadata

Extract audio metadata including duration, format, bitrate, stream information. Returns JSON. Synchronous processing. No parameters required.

Note: Anonymous access is NOT supported for audio/info.

Example:

audio/info

Sample response data:

{
  "Format": {
    "Duration": "245.3",
    "Size": "3920000",
    "FormatName": "mp3",
    "BitRate": "128000"
  },
  "Streams": {
    "AudioStream": [{
      "CodecName": "mp3",
      "SampleRate": "44100",
      "Channels": "2",
      "BitRate": "128000"
    }]
  }
}

---

Parameter specifications in this document are derived from the Alibaba Cloud OSS Audio Processing documentation and are reproduced here for quick reference.

Basic Operations Parameter Reference

Detailed parameter specifications for basic image processing operations. The script accepts operations in the format name:key=value,key=value. Multiple operations can be passed as separate --operations arguments and will be chained in order.

Table of Contents

• resize — Image Scaling
• crop — Image Cropping
• rotate — Image Rotation
• flip — Image Flip
• quality — Quality Adjustment
• format — Format Conversion
• watermark — Text or Image Watermark
• blur — Blur Effect
• sharpen — Sharpen Effect
• bright — Brightness Adjustment
• contrast — Contrast Adjustment
• auto-orient — Auto Orientation
• circle — Inscribed Circle Crop
• rounded-corners — Rounded Corners
• interlace — Progressive Display
• info — Image Metadata
• average-hue — Dominant Color
• Chaining Operations

---

resize — Image Scaling

Scale the image by specifying width, height, percentage, or scaling mode.

Scaling modes (`mode`):

Examples:

resize:w=400,h=300
resize:w=800,mode=lfit
resize:l=1024
resize:p=50
resize:p=200                    # Proportional upscale, no limit needed
resize:w=800,h=600,limit=0      # Fixed-size upscale, limit=0 is required
resize:w=200,h=200,mode=pad,color=F5F5F5

---

crop — Image Cropping

Crop a region from the image.

Gravity values (`g`):

注意: OSS 官方 API 要求使用全称 (north, west, center, east, south)。process.py 同时接受缩写 (n, w, c, e, s) 并自动转换为全称。

Smart crop (`g=auto`, `g=face`): Requires IMM project binding. Does not support anonymous access.

Examples:

crop:w=200,h=200,g=c
crop:w=300,h=300,x=50,y=50
crop:w=100,h=100,g=se
crop:g=auto                      # Smart AI-recommended crop
crop:g=face,w=200,h=200          # Face-centered crop with fixed size
crop:g=face,p=150                # Face-centered crop, 1.5x zoom

---

indexcrop — Indexed Slice

Split the image along the x or y axis into equal-sized blocks, then return one block by index. x and y are mutually exclusive (if both specified, y takes precedence).

Examples:

indexcrop:x=100,i=0
indexcrop:y=200,i=1

---

rotate — Image Rotation

Rotate the image clockwise by a specified angle.

Examples:

rotate:angle=90
rotate:angle=180
rotate:angle=45

---

flip — Image Flip

Flip the image horizontally, vertically, or both.

Examples:

flip:v=0
flip:v=1
flip:v=2

---

quality — Quality Adjustment

Adjust the compression quality. Applicable to JPG and WebP formats.

Examples:

quality:q=80
quality:q=50

---

format — Format Conversion

Convert the image to a different format.

Examples:

format:target=webp
format:target=png
format:target=avif

---

watermark — Text or Image Watermark

Add a text or image watermark to the image. Use text for text watermarks, or image for image watermarks. Chain multiple watermark operations to overlay multiple watermarks.

Common Parameters

Text Watermark Parameters

Image Watermark Parameters

Scaling vs Auto-size: Use rw/rh for percentage-based scaling. Use aw/ah for absolute pixel dimensions that auto-adjust based on source image size. aw/ah take priority over rw/rh.

>

Preprocess: Uses + to chain sub-operations. Each sub-op uses basic operation syntax (e.g., resize,P_30, rotate,90).

>

Multi-watermark: Chain multiple watermark operations to overlay text + image or multiple image watermarks (e.g., "watermark:text=Copyright" "watermark:image=logo.png,opacity=50,g=se").

Examples:

watermark:text=Copyright 2024,size=24,color=FFFFFF,opacity=60,g=se,x=10,y=10
watermark:text=SAMPLE,size=48,color=FF0000,opacity=30,g=c
watermark:text=DRAFT,size=36,opacity=15,tile=1                    # Tiled text watermark
watermark:image=assets/logo.png,opacity=50,g=se,x=10,y=10
watermark:image=watermarks/draft.png,opacity=20,tile=1              # Tiled image watermark
watermark:image=logo.png,rw=20,rh=20                                # 20% of original size
watermark:image=logo.png,aw=200,ah=100                              # Fixed 200x100 pixels
watermark:image=panda.png,preprocess=resize,P_30,opacity=90,g=se    # 30% scale watermark
watermark:image=logo.png,preprocess=resize,w_100+rotate,90,opacity=80  # resize + rotate

---

blur — Blur Effect

Apply a Gaussian blur to the image.

Face blur (`g=face`, `g=faces`): Requires IMM project binding. Does not support anonymous access.

Examples:

blur:r=5,s=3
blur:r=10,s=8
blur:g=face,r=25,s=50              # Blur largest face
blur:g=faces,r=25,s=50             # Blur all faces
blur:g=face,p=200,r=25,s=50        # Blur largest face, 2x zoom

---

sharpen — Sharpen Effect

Sharpen the image.

Examples:

sharpen:v=100
sharpen:v=200

---

bright — Brightness Adjustment

Adjust the image brightness.

Examples:

bright:v=20
bright:v=-30

---

contrast — Contrast Adjustment

Adjust the image contrast.

Examples:

contrast:v=30
contrast:v=-20

---

auto-orient — Auto Orientation

Automatically rotate the image based on EXIF orientation data.

Example:

auto-orient
auto-orient:v=1
auto-orient:v=0

---

circle — Inscribed Circle Crop

Crop the image to an inscribed circle. The output format must support transparency (e.g., PNG).

Example:

circle:r=100

---

rounded-corners — Rounded Corners

Apply rounded corners to the image. The output format must support transparency (e.g., PNG).

Example:

rounded-corners:r=20
rounded-corners:r=50

---

interlace — Progressive Display

Enable or disable progressive/interlaced rendering for JPEG images.

Example:

interlace:mode=1

---

info — Image Metadata

Retrieve image metadata (dimensions, format, file size, etc.). Returns a JSON object with the image properties. No parameters required.

Example:

info

Sample response data:

{
  "FileSize": {"value": "1024000"},
  "Format": {"value": "jpg"},
  "ImageHeight": {"value": "1200"},
  "ImageWidth": {"value": "1600"}
}

---

average-hue — Dominant Color

Retrieve the dominant (average) color of the image as a hex value. No parameters required.

Example:

average-hue

Sample response data:

{
  "RGB": "0x5c783a"
}

---

Chaining Operations

Multiple basic image operations are processed in order. Pass each basic operation as a separate --operations argument:

python scripts/process.py \
  --bucket my-bucket --region cn-hangzhou \
  --source photo.jpg \
  --operations "resize:w=800" "quality:q=80" "format:target=webp"

This generates the OSS process string: image/resize,w_800/quality,Q_80/format,webp

Basic operations are applied sequentially — order matters. For example, resize before crop produces different results than crop before resize.

Chaining Rules

• Basic operations can be freely chained with each other.
• `info` and `average-hue` are standalone read-only metadata operations and must be used alone.
• `blindwatermark-embed` can follow basic operations but must be the last operation in the chain (e.g., resize:w=800 then blindwatermark-embed:content=Test).
• `blindwatermark-extract` must be used alone — no chaining.
• AI detection operations (faces, bodies, cars, codes, labels, score) must be used alone — they cannot be chained with basic, metadata, or watermark operations.

---

Parameter specifications in this document are derived from the Alibaba Cloud OSS Image Processing documentation and are reproduced here for quick reference.

IMM Operations Parameter Reference

Detailed parameter specifications for image-intelligent (IMM) operations. These operations are powered by Alibaba Cloud IMM (Intelligent Media Management) and require IMM service activated with the OSS bucket bound to an IMM project.

Table of Contents

• blindwatermark-embed — Blind Watermark Embedding
• blindwatermark-extract — Blind Watermark Extraction
• faces — Face Detection
• bodies — Body Detection
• cars — Car Detection
• codes — QR/Barcode Recognition
• labels — Image Labeling
• score — Image Quality Score
• IMM Chaining Rules

---

blindwatermark-embed — Blind Watermark Embedding

Embed an invisible blind watermark into the image. The watermark text is not visible to the human eye but can be extracted later using blindwatermark-extract. This operation requires IMM service activated and bucket bound to an IMM project.

Higher strength makes the watermark more resistant to image transformations (crop, compression, etc.) but may slightly affect image quality.

blindwatermark-embed produces a new image and uses process_object with sys/saveas. It supports all three output modes (url, download, save). When chained with other operations, it must be the last operation.

Examples:

blindwatermark-embed:content=Copyright2024,s=high
blindwatermark-embed:content=MyBrand

---

blindwatermark-extract — Blind Watermark Extraction

Extract blind watermark text from a previously watermarked image. This is an asynchronous operation that uses the IMM SDK to create a decode task and poll for results. Requires --imm-project or the ALIBABA_CLOUD_IMM_PROJECT environment variable.

This operation must be used alone — it cannot be chained with other operations. The result is returned as JSON containing the extracted watermark content and task ID.

Examples:

blindwatermark-extract:s=high
blindwatermark-extract:s=medium,model=FFT

---

faces — Face Detection

Detect faces in the image and return their locations and attributes. Returns a JSON response. Requires IMM service. No parameters required.

Example:

faces

---

bodies — Body Detection

Detect human bodies in the image and return their bounding boxes. Returns a JSON response. Requires IMM service. No parameters required.

Example:

bodies

---

cars — Car Detection

Detect cars in the image and return their bounding boxes. Returns a JSON response. Requires IMM service. No parameters required.

Example:

cars

---

codes — QR/Barcode Recognition

Recognize QR codes and barcodes in the image. Returns a JSON response with decoded content. Requires IMM service. No parameters required.

Example:

codes

---

labels — Image Labeling

Generate descriptive labels/tags for the image content. Returns a JSON response with label names and confidence scores. Requires IMM service. No parameters required.

Example:

labels

---

score — Image Quality Score

Evaluate the aesthetic/technical quality of the image. Returns a JSON response with a quality score. Requires IMM service. No parameters required.

Example:

score

---

IMM Chaining Rules

• `blindwatermark-embed` can follow basic operations but must be the last operation in the chain (e.g., resize:w=800 then blindwatermark-embed:content=Test).
• `blindwatermark-extract` must be used alone — no chaining.
• AI detection operations (faces, bodies, cars, codes, labels, score) must be used alone — they cannot be chained with basic, metadata, or watermark operations.

---

Parameter specifications in this document are derived from the Alibaba Cloud IMM documentation and are reproduced here for quick reference.

IMM Administration

Use scripts/imm_admin.py to manage IMM (Intelligent Media Management) projects and bucket bindings. IMM projects are required for image-intelligent operations such as blind watermark extraction and AI detection.

IMM administration requires specific RAM permissions (imm:CreateProject, imm:GetProject, imm:ListProjects, imm:DeleteProject, imm:AttachOSSBucket, imm:DetachOSSBucket).

Commands

Create an IMM project

python scripts/imm_admin.py create-project --project PROJECT_NAME --region REGION_ID

List all projects

python scripts/imm_admin.py list-projects --region REGION_ID

Get project details

python scripts/imm_admin.py get-project --project PROJECT_NAME --region REGION_ID

Bind a bucket to a project

python scripts/imm_admin.py bind-bucket --project PROJECT_NAME --bucket BUCKET_NAME --region REGION_ID

Unbind a bucket from a project

python scripts/imm_admin.py unbind-bucket --project PROJECT_NAME --bucket BUCKET_NAME --region REGION_ID

Delete a project

python scripts/imm_admin.py delete-project --project PROJECT_NAME --region REGION_ID

The delete command includes a protective pre-check: it queries the project's dataset count and blocks deletion if any datasets (bound buckets) remain. Unbind all buckets before deleting.

Typical Setup Flow

# 1. Create an IMM project
python scripts/imm_admin.py create-project --project my-imm-project --region cn-hangzhou

# 2. Bind your OSS bucket to the project
python scripts/imm_admin.py bind-bucket --project my-imm-project --bucket my-bucket --region cn-hangzhou

# 3. Verify the setup
python scripts/imm_admin.py get-project --project my-imm-project --region cn-hangzhou

After setup, you can use IMM operations in scripts/process.py with --imm-project my-imm-project.

Media Processing Limitations

Constraints and supported formats for Alibaba Cloud OSS media processing (image, video, audio).

Image Processing Constraints

Source Image Constraints

Supported Image Source Formats

• JPG / JPEG
• PNG
• BMP
• GIF (animated)
• WebP
• TIFF
• HEIC
• AVIF

Animated GIF Restrictions

When the source image is an animated GIF, only the following operations are supported:

• resize
• crop
• rotate
• watermark (image mode)

All other operations are not applicable to animated GIF images.

Image Output Format Notes

• circle and rounded-corners require an output format that supports transparency (e.g., PNG or WebP). If the source is JPG, chain a format:target=png operation.
• interlace only applies to JPEG output.
• quality only applies to JPG and WebP output.

Blind Watermark Constraints

The watermark strength used for extraction (s) must match the strength used during embedding. Using a different strength level will result in extraction failure or garbled content.

IMM Detection Constraints

• All AI detection operations (faces, bodies, cars, codes, labels, score) require IMM service activated and the OSS bucket bound to an IMM project.
• Detection operations are subject to IMM QPS (queries per second) limits. Default limits vary by region and service tier.
• Source images must be in a format supported by IMM (JPG, PNG, BMP, WebP, TIFF).

Video Processing Constraints

Source Video Constraints

Supported Video Input Formats

avi, mpeg, mpg, dat, divx, xvid, rm, rmvb, mov, qt, asf, wmv, vob, 3gp, mp4, flv, avs, mkv, ts, ogm, nsv, swf, webm

Supported Video Output Formats (Offline Transcoding)

mp4, mkv, mov, asf, avi, mxf, ts, flv, webm, mp3, aac, flac, oga, ac3, opus, amr

Video Operation Constraints

Video Animation Constraints

• Output width and height: 32-4096 px
• Output format must be gif or webp

Video Sprite Constraints

• Sub-image width and height: 32-4096 px
• Tiles per row: 1-100 (default 6)
• Tiles per column: 1-100 (default 6)
• Padding: 0-100 px (default 2)
• Margin: 0-100 px (default 2)

Video Concat Constraints

• Maximum number of input videos: 11
• All input videos must be accessible in the same OSS bucket
• Output format, video codec, and audio codec are required parameters

Audio Processing Constraints

Supported Audio Input Formats

mp3, wav, aac, flac, ogg, wma, m4a, ac3, opus, amr, and other mainstream formats

Supported Audio Output Formats

mp3, aac, flac, oga, ac3, opus, amr

Audio Operation Constraints

Audio Parameter Constraints

• Audio channels: 1-8
• aq (quality) and ab (bitrate) are mutually exclusive
• adepth (bit depth: 16/24) only applies to FLAC output

HLS Streaming Constraints

• hls/m3u8 is synchronous and returns an M3U8 playlist
• Segment duration (st) is specified in milliseconds
• Only h264 and h265 video codecs are supported

General Constraints

Processing Mode Rules

• Image operations can be freely chained with each other (except detection/watermark restrictions).
• Video/audio operations cannot be chained with image operations.
• Only one video/audio operation per request (no chaining between media operations).
• Async-only operations will auto-upgrade to async mode even without the --async flag.

Async Processing

• Maximum polling timeout: 600 seconds (10 minutes)
• Polling interval: 5 seconds
• Async operations require --target-key to specify the output location

---

Technical specifications in this document are derived from the Alibaba Cloud OSS documentation and are reproduced here for quick reference.

RAM Permissions

Required RAM permissions for this Skill.

OSS Permissions (required for all operations)

oss:GetObject — Read objects from the OSS bucket (used for url/download/info modes)

oss:PutObject — Write objects to the OSS bucket (used for save mode and upload operations)

oss:ProcessObject — Execute media processing operations on objects (used for save mode and async operations)

oss:PostProcessTask — Submit asynchronous processing tasks (used for async video/audio operations via x-oss-async-process)

oss:DeleteObject — Delete temporary objects from the OSS bucket (used by blindwatermark-embed in download/url mode to clean up temp files, and by --uri auto-cleanup)

oss:SignUrl — Generate signed URLs for processed media (used for url output mode)

Check Permissions (required for check_permissions.py)

oss:GetBucketInfo — Verify bucket accessibility and permissions

IMM Permissions (required for image-intelligent operations)

imm:CreateDecodeBlindWatermarkTask — Create a blind watermark extraction task

imm:GetTask — Query task status during blind watermark extraction polling

imm:GetDecodeBlindWatermarkResult — Retrieve blind watermark extraction results

IMM Administration Permissions (required for imm_admin.py)

imm:CreateProject — Create an IMM project

imm:ListProjects — List all IMM projects

imm:GetProject — Get details of an IMM project

imm:DeleteProject — Delete an IMM project

imm:AttachOSSBucket — Bind an OSS bucket to an IMM project

imm:DetachOSSBucket — Unbind an OSS bucket from an IMM project

Recommended Policy

For basic media processing (image + video + audio):

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:PutObject",
        "oss:ProcessObject",
        "oss:PostProcessTask",
        "oss:DeleteObject",
        "oss:SignUrl",
        "oss:GetBucketInfo"
      ],
      "Resource": [
        "acs:oss:*:*:<your-bucket>",
        "acs:oss:*:*:<your-bucket>/*"
      ]
    }
  ]
}

For media processing + IMM operations:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:PutObject",
        "oss:ProcessObject",
        "oss:PostProcessTask",
        "oss:DeleteObject",
        "oss:SignUrl",
        "oss:GetBucketInfo"
      ],
      "Resource": [
        "acs:oss:*:*:<your-bucket>",
        "acs:oss:*:*:<your-bucket>/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "imm:CreateDecodeBlindWatermarkTask",
        "imm:GetTask",
        "imm:GetDecodeBlindWatermarkResult",
        "imm:GetProject",
        "imm:CreateProject",
        "imm:ListProjects",
        "imm:DeleteProject",
        "imm:AttachOSSBucket",
        "imm:DetachOSSBucket"
      ],
      "Resource": "*"
    }
  ]
}

Common Recipes

Quick-reference templates for frequent use cases. Copy and adjust parameters as needed.

⚠️ Parameters in recipes are examples, NOT defaults. Only pass parameters the user explicitly requests. OSS uses official defaults for unspecified parameters.

Common Mistakes & Fixes

Video Operations Parameter Reference

Detailed parameter specifications for video processing operations. Video operations use slash notation (e.g., video/convert, video/snapshot). Only one video operation can be specified per request — no chaining with other video/audio/image operations.

Table of Contents

• video/convert — Video Transcoding
• video/snapshot — Single Frame Extraction
• video/info — Video Metadata
• video/animation — Animated Image Conversion
• video/snapshots — Multi-Frame Extraction
• video/sprite — Sprite Sheet Generation
• video/concat — Video Concatenation
• hls/m3u8 — HLS Streaming Playlist

---

video/convert — Video Transcoding

Transcode video to a different format, codec, resolution, or bitrate. Supports both synchronous and asynchronous processing. Use async mode (--async) for large files or complex transcoding.

Examples:

video/convert:f=mp4,vcodec=h264,s=1920x1080,vb=2000000,fps=30,acodec=aac,ab=100000
video/convert:f=mp4,vcodec=h265,videoslim=1,s=1920x1080,vb=2000000,sn=1
video/convert:f=mp4,vcodec=h264,ss=5000,t=30000
video/convert:f=webm,vcodec=vp9,vb=1500000,acodec=vorbis,ab=128000
video/convert:f=mp3,vn=1,acodec=mp3,ab=192000

---

video/snapshot — Single Frame Extraction

Extract a single frame from a video at a specified time. Supports synchronous processing.

Examples:

video/snapshot:t=17000,f=jpg,w=800,h=600
video/snapshot:t=0,f=png,w=1920,h=1080
video/snapshot:t=5000,f=jpg,m=fast

---

video/info — Video Metadata

Extract video metadata including duration, resolution, codec, bitrate, stream information. Returns JSON. Synchronous processing. No parameters required.

Note: Anonymous access is NOT supported for video/info.

Example:

video/info

Sample response data:

{
  "Format": {
    "Duration": "120.5",
    "Size": "15728640",
    "FormatName": "mov,mp4,m4a,3gp,3g2,mj2"
  },
  "Streams": {
    "VideoStream": [{
      "CodecName": "h264",
      "Width": "1920",
      "Height": "1080",
      "FrameRate": "30.0",
      "BitRate": "2000000"
    }],
    "AudioStream": [{
      "CodecName": "aac",
      "SampleRate": "44100",
      "Channels": "2",
      "BitRate": "128000"
    }]
  }
}

---

video/animation — Animated Image Conversion

Convert a video segment to an animated GIF or WebP image. Asynchronous ONLY — requires --async flag.

Examples:

video/animation:f=gif,w=480,h=320,inter=1000
video/animation:f=webp,w=320,h=240,fps=10,ss=5000
video/animation:f=gif,w=200,h=200,num=20,scaletype=crop

---

video/snapshots — Multi-Frame Extraction

Extract multiple frames from a video at regular intervals or keyframes. Asynchronous ONLY — requires --async flag.

Examples:

video/snapshots:f=jpg,w=640,h=360,scaletype=crop,inter=10000
video/snapshots:f=png,m=key,w=1920,h=1080
video/snapshots:f=jpg,m=dhash,thr=5,w=512,h=512,inter=5000
video/snapshots:f=jpg,num=10,w=320,h=240

---

video/sprite — Sprite Sheet Generation

Generate a sprite sheet (contact sheet) from video frames. Asynchronous ONLY — requires --async flag.

Examples:

video/sprite:f=jpg,sw=200,sh=150,inter=2000,tw=3,th=3,pad=0,margin=0
video/sprite:f=png,sw=320,sh=240,num=36,tw=6,th=6
video/sprite:f=jpg,sw=160,sh=120,m=key,tw=4,th=4,pad=2,margin=2

---

video/concat — Video Concatenation

Concatenate multiple videos into one. Asynchronous ONLY — requires --async flag. Maximum 11 videos.

The first video is specified via --source. Additional videos are appended using /pre (before main) and /sur (after main) segments with their parameters.

Segment syntax (for additional videos):

• /pre,o_<base64_key>,ss_<ms>,t_<ms> — prepend segment
• /sur,o_<base64_key>,ss_<ms>,t_<ms> — append segment

Where <base64_key> is the URL-safe Base64-encoded OSS object key.

Examples:

video/concat:f=mp4,vcodec=h264,fps=25,vb=1000000,acodec=aac,ab=96000,ar=48000,ac=2,align=1

---

hls/m3u8 — HLS Streaming Playlist

Generate an HLS (HTTP Live Streaming) M3U8 playlist for transcode-while-play. Synchronous processing.

Examples:

hls/m3u8:ss=15000,t=1800000,vcodec=h264,fps=25,s=1280x720,vb=2000000,acodec=aac,ab=128000,st=10000,initd=30000
hls/m3u8:vcodec=h264,s=1920x1080,vb=4000000,acodec=aac,ab=256000

---

Parameter specifications in this document are derived from the Alibaba Cloud OSS Video Processing documentation and are reproduced here for quick reference.