/byted-byteplus-vod-video-enhancement

name: byted-byteplus-vod-video-enhancement
description: "Upload video/audio media to BytePlus VOD (Video on Demand) storage, returning the Vid and playback references; supports both local file upload (ApplyUploadInfo + TOS + CommitUploadInfo) and URL pull upload (UploadMediaByUrl); also supports AI-based comprehensive quality restoration on already-uploaded videos (removing compression artifacts, noise, scratches, improving clarity, and configuring Pro-tier color depth). Trigger keywords: upload video, upload media, upload to VOD, URL upload, pull upload, local upload, file upload, UploadMediaByUrl, ApplyUploadInfo, media ingestion, quality restoration, quality enhancement, comprehensive restoration, video denoising, denoise, compression artifact removal, color depth, bit depth, 10-bit, 12-bit, 16-bit."
version: 1.2.0
license: Apache-2.0
env:
  - name: BYTEPLUS_ACCESSKEY
    description: BytePlus Access Key
    required: true
    secret: true
    default: ''
  - name: BYTEPLUS_SECRETKEY
    description: BytePlus Secret Key
    required: true
    secret: true
    default: ''
  - name: VOD_SPACE_NAME
    description: VOD space name
    required: true
    secret: false
    default: ''

VOD_video enhancement

Uploads video/audio to a BytePlus VOD space (from a **local file** or a **public URL**) and returns a `vid://vxxxx` reference. Additionally provides AI-based comprehensive quality restoration that removes compression artifacts, noise, and scratches from ingested videos, improving overall clarity and color rendition.

---

Prerequisites

• **Environment variables** (required, can be configured via a `.env` file in the working directory — the scripts will load it automatically):
• `BYTEPLUS_ACCESSKEY` — BytePlus Access Key
• `BYTEPLUS_SECRETKEY` — BytePlus Secret Key
• `VOD_SPACE_NAME` — VOD space name
• **Execution**: examples use `uv run python ...` (if the host environment can run Python directly, `python scripts/...` also works).

---

Workflow Overview

Upload pipeline (local file):
  [S1_APPLY]  ApplyUploadInfo → returns TOS upload address + SessionKey
  [S2_TOS]    PUT file to TOS (direct or chunked)
  [S3_COMMIT] CommitUploadInfo → returns Vid
  Output: { Vid, Source, PlayURL, FileName, SpaceName, SourceUrl }

Upload pipeline (URL):
  [S1_UPLOAD] Submit URL upload job (UploadMediaByUrl) → returns JobId
  [S2_POLL]   Poll QueryUploadTaskInfo → returns Vid
  Output: { Vid, Source, PlayURL, FileName, SpaceName, SourceUrl, JobId }

Quality restoration pipeline:
  [S3_ENHANCE] Submit restoration job (StartExecution/enhanceVideo) → returns RunId
  [S4_POLL]    Poll GetExecution → returns the restored file
  Output: { Status, SpaceName, VideoUrls[{ FileId, DirectUrl, Source }] }

---

Quick Self-Check (recommended)

Before running any script, confirm the following (avoid unrelated Python/uv version checks):

• `.env` or environment variables contain:
• `BYTEPLUS_ACCESSKEY` + `BYTEPLUS_SECRETKEY`
• `VOD_SPACE_NAME`

Once verified, pick the corresponding pipeline based on user intent:

| User intent | Pipeline | Entry script | |-------------|----------|--------------| | Upload video to VOD | Upload pipeline | `scripts/upload.py` | | Quality restoration / denoise / remove compression artifacts | Quality restoration pipeline | `scripts/quality_enhance.py` |

---

S1_UPLOAD & S2_POLL: Upload and Obtain Vid

Calling Convention

Run from the Skill root directory (`byted-byteplus-vod-video-enhancement/`):

# Local file upload (synchronous — returns Vid when complete)
uv run python scripts/upload.py "/path/to/video.mp4" [space_name]

# URL upload (automatically polls until a Vid is returned)
uv run python scripts/upload.py "<https://example.com/video.mp4>" [space_name]

# Example: specifying the space
uv run python scripts/upload.py "https://example.com/sample.mp4" my_space

• First argument: either a **local file path** or a public `http://` / `https://` link. The script auto-detects which mode to use.
• Second argument (optional): the VOD space name; when omitted it is read from the environment variable `VOD_SPACE_NAME`.
• The file / URL must carry a file extension (such as `.mp4`, `.mov`, `.mp3`), otherwise an error is raised.

Upload Flow

**Local file upload** (synchronous, three-step): 1. Call `ApplyUploadInfo` (API Version: 2023-01-01) to obtain the TOS upload address, authentication token, and SessionKey. 2. PUT the file to TOS (direct upload for files < 20 MiB, chunked upload otherwise). 3. Call `CommitUploadInfo` (API Version: 2023-01-01) with the SessionKey; returns the `Vid`.

**URL upload** (two-phase asynchronous): 1. Call `UploadMediaByUrl` (API Version: 2023-01-01) to submit the pull job; returns a `JobId`. 2. Poll `QueryUploadTaskInfo` until the job completes, with a maximum wait of 30 minutes (360 × 5s). 3. Once the job is complete, return the `Vid`.

Output Format

On success, a JSON line is printed to stdout:

{
  "Vid": "v0d123abc",
  "Source": "vid://v0d123abc",
  "PlayURL": "https://example.cdn.com/xxx.m3u8",
  "PosterUri": "",
  "FileName": "uuid-filename.mp4",
  "SpaceName": "my_space",
  "SourceUrl": "https://example.com/video.mp4",
  "JobId": "job-xxx"
}

• `Source`: a `vid://`-formatted reference that can be passed directly to follow-up skills such as `byted-mediakit`.
• The host agent should save the `Source` field for use in subsequent processing steps.

Timeout Handling

If polling times out (30 minutes), the output is:

{
  "error": "Polling timed out (360 attempts × 5s); the URL pull upload is still processing",
  "resume_hint": {
    "description": "The URL upload has not finished yet; retry with the command below",
    "command": "uv run python scripts/upload.py \"<original URL>\" [space_name]"
  },
  "JobIds": "job-xxx",
  "State": "running"
}

---

S3_ENHANCE & S4_POLL: AI Comprehensive Quality Restoration

Calling Convention

Run from the Skill root director