byted-byteplus-vod-precision-erasure

Files (10)

• LICENSE
• SKILL.md
• precise_erase.md · references/
• .env.example · scripts/
• poll_execution.py · scripts/
• precise_erase.py · scripts/
• pyproject.toml · scripts/
• tos_upload.py · scripts/
• upload.py · scripts/
• vod_client.py · scripts/

SKILL.md (first lines)

# VOD precision erasure

Uploads video/audio to a BytePlus VOD space (from a **local file** or a **public URL**) and returns a `vid://…` reference. For media already in VOD, submits **precision erasure** tasks (`StartExecution` → `Operation.Task.Type: Erase`) using **automatic OCR only**. Do **not** tell end users they can change erasure **mode** between Manual and Auto — this skill always sends **`Auto`**. **`NewVid` is always `true`** (not surfaced as a user choice).

---

## Product scope

| Aspect | Behaviour |
|--------|-----------|
| **Input** | `Vid` or `DirectUrl` (JSON field `video`) |
| **Erasure coverage** | Default **subtitle only** (`Auto.Type: Subtitle`, `SubtitleFilter: {}`). User may opt into **all detected on-screen text** via `text: true` or `all_text: true` → `Auto.Type: Text`. |
| **Timeline** | Default: **whole** video (no `ClipFilter`). Optional `clip_filter` with **`mode`** `skip` or **`selected`** — when either is used, **`clips` is mandatory** (non-empty). |
| **Output asset** | **`NewVid` is always `true`** — not configurable and not prompted. |
| **Erasure metadata** | Default **`with_erase_info: true`** (`WithEraseInfo`). If `false`, stdout `EraseMeta` is `{}`; `VideoUrls` are still populated when `Erase.File` is returned. |

**Not supported:** `Manual` mode, custom ratio `Locations`, tuning `SubtitleFilter` beyond `{}`, `VideoOption.EncodeMode`, overriding `NewVid`.

**Precision erasure allowlist:** if you see HTTP **403** or “Permission denied”, explain allowlist / work order per [BytePlus VOD](https://console.byteplus.com/workorder/create?step=2&SubProductID=P00001112).

---

## Prerequisites

- **Environment variables** (required; optionally place a `.env` in the working directory — scripts 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 …` (`python scripts/…` works if deps are installed).

---

## Workflow overview

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

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

Precision erasure pipeline:
  [S3_ERASE]  Submit Erase task (StartExecution / Task.Type Erase) → RunId
  [S4_POLL]   Poll GetExecution → output Erase.File (+ optional Erase.Info)
  Output: { Status, SpaceName, VideoUrls[{ FileId, Vid, DirectUrl, Source, Url }], EraseMeta? }
```

---

## Quick Self-Check (recommended)

Before running any script:

- `.env` or env vars contain `BYTEPLUS_ACCESSKEY`, `BYTEPLUS_SECRETKEY`, and `VOD_SPACE_NAME`.

Pick the pipeline from user intent:

| User intent | Pipeline | Entry script |
|-------------|----------|--------------|
| Upload video to VOD | Upload | `scripts/upload.py` |
| Subtitle / on-screen text erasure | Precision erasure | `scripts/precise_erase.py` |

---

## S1_UPLOAD & S2_POLL: Upload and Obtain Vid

### Calling convention

Run from the Skill root directory (`byted-byteplus-vod-precision-erasure/`):

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

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

uv run python scripts/upload.py "https://example.com/sample.mp4" my_space
```

- First argument: **local file path** or public `http://` / `https://` URL (auto-detected).
- Second argument (optional): space name; if omitted, `VOD_SPACE_NAME` is used.
- Paths and URLs **must include a file extension** (e.g. `.mp4`, `.mov`, `.mp3`).

### Upload flow

**Local file** (synchronous, three-step):

1. `ApplyUploadInfo` (API version `2023-01-01`) → TOS address, SessionKey  
2. PUT to TOS (direct `< 20 MiB`, else chunked)  
3. `CommitUploadInfo` (`2023-01-01`) → `Vid`  

**URL pull** (async + poll):

1. `UploadMediaByUrl` (`2023-01-01`) → `JobId`  
2. Poll `QueryUploadTaskInfo` until done (same limits as sibling skill: typically 360 × 5 s)  
3. Return `Vid`  

### Output format

On success, one JSON object on stdout, e.g.:

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

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples