byted-byteplus-vod-video-enhancement

Files (10)

• LICENSE
• SKILL.md
• quality-enhance.md · references/
• env.md · scripts/
• poll_execution.py · scripts/
• pyproject.toml · scripts/
• quality_enhance.py · scripts/
• tos_upload.py · scripts/
• upload.py · scripts/
• vod_client.py · scripts/

SKILL.md (first lines)

# 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

```text
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/`):

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

```json
{
  "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:

```json
{
  "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]"
  },

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples