byted-byteplus-vod-precision-erasure

# 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 finished yet; resume polling with the command below", "command": "uv run python scripts/poll_execution.py '<RunId>' [space_name]" } } ``` --- ## Environment Variables | Name | Description | Required | |------|-------------|----------| | `BYTEPLUS_ACCESSKEY` | BytePlus Access Key | Yes | | `BYTEPLUS_SECRETKEY` | BytePlus Secret Key | Yes | | `VOD_SPACE_NAME` | VOD space name | Yes (or via CLI argument) | | `VOD_POLL_INTERVAL` | Polling interval (seconds, default 5) | No | | `VOD_POLL_MAX` | Maximum polling attempts (default 360) | No | | `VOD_URL_EXPIRE_MINUTES` | Signed URL expiry (minutes, default 60) | No | | `VOD_PLAY_DOMAIN` | Force a specific playback domain (optional, highest priority) | No | | `VOD_HOST` | Override VOD OpenAPI hostname (optional) | No | --- ## Error Output Format All failures use: ```json {"error": "error description"} ``` --- ## References - [BytePlus VOD Python SDK](https://docs.byteplus.com/en/docs/byteplus-vod/docs-python-sdk) - [precision erasure parameter reference](references/precise_erase.md) - API: `ApplyUploadInfo` (`2023-01-01`) - API: `CommitUploadInfo` (`2023-01-01`) - API: `UploadMediaByUrl` (`2023-01-01`) - API: `QueryUploadTaskInfo` (`2023-01-01`) - API: `StartExecution` (`2025-07-01`) - API: `GetExecution` (`2025-07-01`)