byted-byteplus-vod-precision-erasure

What this skill does

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

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

### Timeout handling (URL upload)

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

```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]"
  },
  "JobIds": "job-xxx",
  "State": "running"
}
```

---

## S3_ERASE & S4_POLL: precision erasure

### Calling convention

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

```bash
# Default: subtitle-only, whole video, WithEraseInfo on
uv run python scripts/precise_erase.py '{"type":"Vid","video":"v0310abc"}'

uv run python scripts/precise_erase.py '{"type":"Vid","video":"vid://v0d225gxxx"}' production_space

# Broader OCR (subtitle + other on-screen text)
uv run python scripts/precise_erase.py '{"type":"Vid","video":"v0310abc","text":true}'

uv run python scripts/precise_erase.py @params.json

# Resume after timeout
uv run python scripts/poll_execution.py '<RunId>' [space_name]
```

### Parameter reference

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | ✅ | `Vid` or `DirectUrl` |
| `video` | string | ✅ | Vid or VOD `FileName`; `vid://` / `directurl://` stripped automatically |
| `text` | boolean | no | If true: **`Auto.Type: Text`** (more aggressive). Default false → subtitle-only. |
| `all_text` | boolean | no | Synonym for **`text`** (if both are set, **`text`** is applied first). |
| `clip_filter` | object | no | Omit = whole video. If set: **`mode`** `skip` or `selected`, and **`clips`** (non-empty list of `{ "start", "end" }` seconds; `Start`/`End` accepted). |
| `with_erase_info` | boolean | no | Default `true` (`WithEraseInfo`). If `false`, detailed erase geometry is not requested; stdout **`EraseMeta`** is `{}`. |

Do **not** prompt users for **Manual mode** or **NewVid**.

### Agent prompting (plain language)

Clarify: **subtitle-only** vs **all on-screen text**; **whole video** vs **segments** (`skip` / `selected` + `clips`); whether they need **region-level erase telemetry** (`with_erase_info`). Use conversational labels — avoid exposing raw JSON field names unless the user asks for implementation details.

### Output format

On success, one JSON object on stdout, roughly:

```json
{
  "Status": "Success",
  "SpaceName": "my_space",
  "VideoUrls": [
    {
      "FileId": "…",
      "Vid": "v0…",
      "DirectUrl": "path/to/output.mp4",
      "Source": "vid://v0…",
      "Url": "https://example.cdn.com/…"
    }
  ],
  "AudioUrls": [],
  "Texts": [],
  "EraseMeta": {
    "Duration": 57.099,
    "Info": {}
  }
}
```

When **`with_erase_info`** was false, **`EraseMeta`** is `{}`.

- **`VideoUrls[0].Url`:** playable / downloadable when signing succeeds for the space.  
- **`Source`:** prefer `vid://…` when the API returns a new `Vid`; else `directurl://…`.

### Timeout handling (GetExecution polling)

Same pattern as the enhancement skill:

```json
{
  "error": "Polling timed out (360 attempts × 5s); the job is still processing",
  "resume_hint": {
    "description": "The job has not fini