@mediaruntime/cli 1.2.0 → 1.4.0

package/docs/AUTH.md

@@ -61,6 +61,14 @@ Authenticated commands resolve credentials in this order:
 No command-line API-key flag exists. No plaintext credential-file fallback exists. A
 machine without a supported credential vault must use `MEDIARUNTIME_API_KEY`.
 
+Hosted Sticker Runtime has one deliberately narrower exception. For collection-bound
+`stickers packs list`, `search`, `typeahead`, `get`, and `resolve`,
+`MEDIARUNTIME_STICKER_CLIENT_TOKEN` selects a short-lived scoped client without reading the
+master API key or stored login. The explicit collection must match the token claim.
+Collection management, pack binding, workspace usage, and token issuance never accept that
+credential and continue using the normal resolution order above. See
+[the Sticker Runtime contract](STICKERS.md) for the exact boundary.
+
 ## Security invariants
 
 - Device codes and PKCE verifiers carry at least 256 bits of randomness.

package/docs/CLI_SDD.md

@@ -23,6 +23,12 @@ mediaruntime recipes get <name>
 mediaruntime recipes create --file <recipe.json>
 mediaruntime recipes version <name> --file <recipe.json> --expected <version>
 mediaruntime recipes archive <name>
+mediaruntime stickers collections list
+mediaruntime stickers collections packs enable <collection_id> --pack <pack_id>
+mediaruntime stickers search <query> --collection <collection_id>
+mediaruntime stickers resolve <sticker_id> --variant <name> --collection <collection_id>
+mediaruntime stickers usage
+mediaruntime stickers token create --collection <collection_id>
 mediaruntime jobs list
 mediaruntime jobs get <job_id>
 mediaruntime trigger job.completed --to http://127.0.0.1:3000/webhooks/mediaruntime
@@ -41,6 +47,11 @@ The canonical result remains one expiring ZIP bundle containing the complete out
 The CLI downloads that ZIP as-is; it does not expose individual artifacts or infer an
 engine directory layout.
 
+Hosted Sticker Runtime commands are the other explicit asset-delivery surface. They bind
+all reads to one application collection and use the SDK's short-lived, generation-pinned
+sticker resolution rather than the job ZIP contract. The complete command and security
+contract is maintained in `docs/STICKERS.md`.
+
 ## 2. Goals and non-goals
 
 ### Goals
@@ -130,6 +141,38 @@ mediaruntime run <source>
   [--json]
 ```
 
+When exactly one clipping preset is selected, `run` accepts the controls in
+[the clipping guide](clipping.md). `video_clip_v1` requires explicit `--clip-start`
+and `--clip-duration`; `clip_candidates_v1` accepts duration bounds, suggestion count,
+and repeated keywords. `--clip-transcript` accepts a local JSON plan/segment array,
+SRT, or VTT file with full-source timestamps (at most 1 MiB). Invalid attachments
+fail before job creation. Burned captions are opt-in through `--clip-captions`, which
+requires a transcript. Supplied transcripts bypass analysis transcription; manual
+ranges never require Whisper. Clipping controls cannot ambiguously target multiple
+outputs or a hosted recipe. This additive surface is available in client release 1.4.0.
+
+When exactly one `contact_sheet_v1` preset is selected, `run` also accepts bounded
+`--contact-columns`, `--contact-rows`, `--contact-tile-width`,
+`--contact-tile-height`, `--contact-interval`, `--contact-start`,
+`--contact-duration`, `--contact-max-sheets`, `--contact-format`, and
+`--contact-quality` controls. They are rejected with recipes, mixed outputs, or any
+other preset so the CLI cannot attach them ambiguously.
+
+When exactly one `audiogram_v1` preset is selected, `--audiogram-artwork` is required.
+`--audiogram-captions` is optional and explicitly enables caption burning. Layout,
+background/waveform colours, start, duration, and frame-rate controls mirror the bounded
+gateway contract. Artwork and captions may be HTTP(S), `gs://`, `file://`, or local
+paths. Local secondary assets use the same authenticated signed-upload client as the
+main source; the submitted job contains only the resulting account-scoped `gs://` URI.
+Raw filters, font paths, and arbitrary rendering arguments are not accepted.
+
+Privacy redaction is a Premium Preview for still-image inputs and public image presets with one or
+more repeatable `--privacy-detector face|license_plate|text` flags. The CLI accepts only
+the gateway's bounded style, strength, failure-mode, confidence, segmented frame-count,
+padding, pixel-block, debug-observation, and solid-colour controls. It resolves aliases through the live capabilities document so
+the request carries explicit output objects, rejects video, audio, animated-image, and recipe combinations
+locally, and never accepts model paths, raw OCR retention, or arbitrary detector options.
+
 `-o` is the short spelling of `--output`. Exactly one source and at least one output or preset are
 required. `<source>` may be an HTTP(S) URL, `gs://` URI, local path, or `file://` URL. The
 CLI passes it to the SDK so local inputs use the SDK's signed-upload flow.

package/docs/STICKERS.md

@@ -0,0 +1,98 @@
+# Hosted Sticker Runtime CLI contract
+
+## Authentication boundary
+
+Sticker commands use the normal trusted credential by default: an explicit
+`MEDIARUNTIME_API_KEY`, then the API key stored by `mediaruntime login`. There is no
+command-line secret flag.
+
+`MEDIARUNTIME_STICKER_CLIENT_TOKEN` is an optional short-lived credential for only these
+collection-bound runtime reads:
+
+```text
+stickers packs list
+stickers search
+stickers typeahead
+stickers get
+stickers resolve
+```
+
+When this variable is set for one of those reads, the CLI constructs the Node SDK's scoped
+`StickerRuntime` directly and does not resolve or send a master API key. The explicit
+`--collection` must match the token claim. A scoped token cannot manage collections or pack
+bindings, inspect workspace usage, or mint another token. Those commands always require the
+trusted credential.
+
+## Collection management
+
+```text
+mediaruntime stickers collections list [--include-archived] [--json]
+mediaruntime stickers collections create --name <name> [--description <text>] [--json]
+mediaruntime stickers collections get <collection_id> [--json]
+mediaruntime stickers collections update <collection_id>
+  [--name <name>] [--description <text> | --clear-description]
+  [--status active|archived] [--json]
+mediaruntime stickers collections archive <collection_id> [--json]
+```
+
+Archive is recoverable and retains pack-binding history. Restore an archived collection with
+`collections update <collection_id> --status active`. JSON output is the SDK's camel-case
+projection.
+
+## Pack bindings
+
+```text
+mediaruntime stickers collections packs list <collection_id> [--json]
+mediaruntime stickers collections packs enable <collection_id>
+  (--pack <pack_id> | --activation <activation_id>) [--json]
+mediaruntime stickers collections packs disable <collection_id> --pack <pack_id> [--json]
+```
+
+These commands bind an existing paid Hosted Pack activation to an application collection.
+They do not purchase, activate, revoke, or charge for a pack. The stable pack-ID form is
+idempotent and suitable for configuration scripts. The activation-ID form is useful just
+after an account administrator completes activation elsewhere.
+
+Disabling removes the pack from new-use discovery while retaining the binding and its
+historical-access policy. Exact historical references can therefore remain renderable when
+the policy is `preserve`; search and metadata retrieval no longer return the disabled pack.
+
+## Runtime reads
+
+```text
+mediaruntime stickers packs list --collection <collection_id> [--json]
+mediaruntime stickers search <query> --collection <collection_id>
+  [--pack <pack_id>] [--category <category>]
+  [--animated | --static] [--limit <1..50>] [--json]
+mediaruntime stickers typeahead <prefix> --collection <collection_id>
+  [--pack <pack_id>] [--locale <locale>] [--limit <1..20>] [--json]
+mediaruntime stickers get <sticker_id> --collection <collection_id> [--json]
+mediaruntime stickers resolve <sticker_id> --variant <variant>
+  --collection <collection_id> [--json]
+```
+
+Search is metadata-only. Persist the stable `stickerId`, then call `resolve` only when an
+approved representation is needed. Resolution intentionally prints the short-lived signed
+URL because delivery authorization is the command's purpose. The URL is collection checked,
+variant checked, generation pinned, and expiring; do not persist it or write it to logs.
+
+Supported variants are `animated`, `reduced_motion`, `small_80`, `small_100`, `small_160`,
+and `thumbnail`. The gateway remains authoritative and may reject a supported name when the
+specific sticker does not publish that representation.
+
+## Usage and scoped token issuance
+
+```text
+mediaruntime stickers usage [--json]
+mediaruntime stickers token create --collection <collection_id>
+  [--expires-in <60..3600>]
+  [--scope packs:read|stickers:search|stickers:read|assets:resolve]...
+  [--json]
+```
+
+Omitting `--scope` asks the gateway for all four read scopes. Repeated scopes are
+deduplicated. Token output is secret-bearing by explicit request; redirect it only to a
+protected sink and avoid CI log capture. Usage is pooled at workspace/month level and
+reports operations, authorized delivery bytes, included allowances, settled overage, and
+health status. URL issuance records maximum authorized bytes; it does not claim that the
+client completed a CDN transfer.

package/docs/clipping.md

@@ -0,0 +1,113 @@
+# Assisted clipping (1.4.0)
+
+Requires CLI and Node SDK 1.4.0 or newer. Earlier versions do not include these
+controls. The gateway and worker must
+also deploy `clip_candidates_v1` and `video_clip_v1`. The live capability catalog
+controls which presets an account can run.
+
+## Analyze → review → render
+
+Analyze and download the resulting plan using the normal job flow. Choose a minimum
+no longer than the source (the 15-second default does not fit a 12-second video):
+
+```sh
+mediaruntime run https://your-cdn.example/episode.mp4 \
+  --preset clip_candidates_v1 --clip-min-duration 15 --clip-max-duration 60 \
+  --clip-count 5 --clip-keyword deployment --download analysis.zip
+```
+
+`--download` implies `--wait`. Extract `clip_candidates.json` from the ZIP, review
+its candidates and transcript, and choose a range. Scores express transcript and
+pause heuristics, not predicted engagement. Analysis produces a JSON report, not
+rendered clips. Empty candidates are a successful result when nothing matches;
+`empty_reason` explains `no_speech`, `no_keyword_match`, `no_matching_ranges`, or
+`source_too_short` when present. A nonempty transcript can still be reused. Current
+preflight rejects a minimum longer than the source before analysis begins.
+
+Render the reviewed range from the **same source**:
+
+```sh
+mediaruntime run https://your-cdn.example/episode.mp4 \
+  --preset video_clip_v1 --clip-start 20 --clip-duration 30 \
+  --clip-layout vertical_blur --clip-transcript clip_candidates.json --clip-captions \
+  --download clip.zip
+```
+
+The example needs a source of at least 50 seconds. Replace its start and duration
+with the candidate you reviewed; CLI does not automatically pick or submit a candidate.
+The ZIP includes the MP4, poster, and SRT/VTT sidecars when a transcript intersects
+the range. `--clip-captions` additionally burns that supplied text into the video.
+Omit `--clip-captions` to keep sidecars only.
+
+## Manual clips and existing captions
+
+Manual clipping requires no transcription or Whisper model:
+
+```sh
+mediaruntime run ./source.mp4 --preset video_clip_v1 \
+  --clip-start 1 --clip-duration 5 --download manual-clip.zip
+
+mediaruntime run ./source.mp4 --preset video_clip_v1 \
+  --clip-start 1 --clip-duration 5 --clip-transcript ./source.srt \
+  --clip-captions --download captioned-clip.zip
+```
+
+`--clip-transcript` accepts a **local** `.srt`, `.vtt`, or `.json` file. JSON may
+be a report with `transcript` or a bare segment array. Snake-case API fields
+`start_time_sec` / `end_time_sec` and camel-case Node fields `startTimeSec` /
+`endTimeSec` are accepted with `text`. SRT/VTT styling is flattened into plain text.
+Cloud URLs and storage paths are not transcript file arguments: download the file
+locally first. Main media sources continue to support the usual upload/source flow.
+
+Times refer to the **full original source**, not the trimmed clip. Do not subtract
+the clip start; the engine intersects and rebases captions. Burning requires text
+that overlaps the selected range. Text need not describe the content for a rendering
+test, but use accurate transcripts for meaningful speech suggestions.
+
+Attachments must be UTF-8, at most 1 MiB, and contain 1–2000 ordered segments.
+Each cue needs a finite start ≥ 0, end > start, and nonblank text of at most
+2000 UTF-8 bytes. Total text is bounded to 256 KiB and timestamps to 604800 seconds.
+Source duration/range validity is checked by gateway/engine preflight.
+
+## Controls and processing
+
+| Option | Bound/default |
+| --- | --- |
+| `--clip-start` | Required for render; 0–604800 seconds |
+| `--clip-duration` | Required for render; 0.1–300 seconds, wholly within source |
+| `--clip-layout` | `original` (default) or `vertical_blur` |
+| `--clip-min-duration` | Analysis: 1–300 seconds; default 15 |
+| `--clip-max-duration` | Analysis: 1–300 seconds; default 60; ≥ minimum |
+| `--clip-count` | Analysis: integer 1–20; default 5 |
+| `--clip-keyword` | Analysis: repeat up to 20 times, 1–100 UTF-8 bytes each |
+| `--clip-transcript` | Local JSON/SRT/VTT attachment for either clipping preset |
+| `--clip-captions` | Render only; opt-in burn, requires transcript |
+
+Clipping controls require exactly one corresponding `--preset`; they cannot be
+combined with a hosted recipe or ambiguously target multiple outputs.
+
+Analysis is Premium. Without supplied text it uses the worker's **existing Whisper
+base model**, which must be available in that runtime. Supplying `--clip-transcript`
+for analysis bypasses Whisper. This feature introduces no additional ML model.
+Standard renders cap original framing at a 1920-pixel long edge and 30 fps;
+vertical blur-fill uses 720×1280 at up to 30 fps. Account settings may select a
+higher effective tier. Premium analysis depends on the deployment's Sandbox
+configuration; use a funded account when that Sandbox disables Premium processing.
+
+## Local release verification
+
+Build and pack the sibling Node SDK 1.4.0 first, then install its tarball only for
+local verification, keeping the committed dependency as `^1.4.0`:
+
+```sh
+npm install --offline --no-save --package-lock=false /path/to/mediaruntime-node-1.4.0.tgz
+npm run check
+npm test
+node dist/cli.js --version
+```
+
+The CLI checks that its SDK supports clipping before submission. Do not publish a
+filesystem dependency. After publishing the SDK, regenerate the CLI lock with
+`npm install --package-lock-only`, run a clean `npm ci` and package smoke test, then
+publish the CLI. Registry publication and deployed-service verification are separate
+release steps; passing local tests does not assert they have happened.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediaruntime/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Official command-line client for MediaRuntime",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
     "prepack": "npm run check && npm test"
   },
   "dependencies": {
-    "@napi-rs/keyring": "^1.3.0",
-    "@mediaruntime/node": "^1.2.0"
+    "@mediaruntime/node": "^1.4.0",
+    "@napi-rs/keyring": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",