/byted-byteplus-vod-precision-erasure

name: byted-byteplus-vod-precision-erasure
description: "Upload video/audio media to BytePlus VOD (Video on Demand) storage, returning the Vid and playback references; supports local file upload (ApplyUploadInfo + TOS + CommitUploadInfo) and URL pull upload (UploadMediaByUrl); also submits precision erasure jobs on ingested media (StartExecution / Operation.Task.Erase): Auto OCR only — default subtitle-only erasure, optional full on-screen text, optional EraseOption ClipFilter (skip/selected); NewVid is always true; optional WithEraseInfo. Trigger keywords: precision erasure, precise erase, VOD upload, subtitle removal, OCR subtitles, remove on-screen text, erase text, StartExecution Erase."
version: 1.0.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 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

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

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

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

• Preserve **`Source`** (`vid://…`) for downstream skills.

Timeout handling (URL upload)

If URL polling exhausts retries, stderr / JSON includes something like:

{
  "error": "Polling timed ou