@mediaruntime/cli 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.4.0 — 2026-09-13
+
+- Add capability-discovered Clip Candidates and Video Clip commands, bounded ranges,
+  original or vertical blurred framing, keyword controls, and opt-in burned captions.
+- Attach local JSON plans/segment arrays, SRT, or VTT with source timestamps; reuse
+  transcripts for analysis without another Whisper run. Validate bounded UTF-8 attachments
+  before submission and preserve the normal wait and verified ZIP download flow.
+- Require `@mediaruntime/node` 1.4.0 for clipping serialization and report parity.
+- Correct the executable version and regression-test it against the package manifest.
+
+## 1.3.0 — 2026-08-31
+
+- Add complete Hosted Sticker Runtime commands for collection lifecycle, pack binding,
+  enabled-pack discovery, search, typeahead, stable metadata retrieval, signed asset
+  resolution, pooled usage, and short-lived scoped token issuance.
+- Keep API keys and secure browser login as the default sticker authentication while
+  allowing `MEDIARUNTIME_STICKER_CLIENT_TOKEN` only for collection-bound read commands.
+- Add explicit, bounded still-image Privacy Redaction Preview flags for face, license-plate, and visible-text
+  masking; aliases are expanded through the live capability catalog before submission.
+- Document the stable public privacy-report boundary and its ZIP-relative paths while
+  excluding detector/model and private infrastructure details.
+- Add bounded Audiogram artwork-fit, waveform-gain, safe-caption, and optional loudness
+  normalization flags; document the caption-free poster artifact.
+- Document capability-driven `code_detect_v1` execution and its untrusted-payload rule.
+- Document and regression-test capability-driven `compatibility_report_v1` execution.
+- Add bounded `contact_sheet_v1` run controls for grid geometry, sampling window, sheet
+  count, format, and quality.
+
 ## 1.2.0 — 2026-08-19
 
 - Add hosted recipe discovery, inspection, creation, immutable versioning, and archive

package/README.md

@@ -4,7 +4,12 @@ Official command-line client for MediaRuntime. It submits media, waits for jobs,
 the canonical ZIP output bundle, inspects account jobs, and sends correctly signed
 synthetic webhooks to a local receiver.
 
-Status: stable `1.2.0`. The documented `1.x` command names, flags, JSON envelopes, exit
+Version `1.4.0` adds [clipping commands](docs/clipping.md) for analysis,
+manual ranges, vertical blur-fill, and JSON/SRT/VTT transcript attachments. It requires
+Node SDK 1.4.0 or newer and a gateway/engine deployment supporting the clipping
+presets. The live capability catalog determines which presets are available.
+
+The documented `1.x` command names, flags, JSON envelopes, exit
 codes, and credential precedence follow semantic versioning. Breaking changes require a
 new major version; additive commands and fields may ship in minor releases.
 
@@ -87,6 +92,111 @@ mediaruntime run ./launch.mp4 \
 retrieves the catalog and supplies the preset's required output type automatically. Alias
 and preset selections may be mixed and repeated in one command.
 
+Animated WebP and APNG are explicit Premium presets. Their bounded controls apply when
+exactly one animation preset is selected (`0` loops forever; APNG is lossless and does
+not accept `--animation-quality`):
+
+```bash
+mediaruntime run ./clip.mp4 \
+  --preset image_animated_webp_v1 \
+  --animation-width 720 \
+  --animation-fps 15 \
+  --animation-duration 6 \
+  --animation-loop 0 \
+  --animation-quality 80 \
+  --wait --download ./animated-webp.zip
+```
+
+Generate BlurHash, ThumbHash, and a byte-bounded WebP LQIP from an image or video frame
+with the Standard `image_placeholders_v1` preset:
+
+```bash
+mediaruntime run ./product-photo.png \
+  --preset image_placeholders_v1 \
+  --placeholder-max-dimension 32 \
+  --placeholder-time 0 \
+  --lqip-quality 50 \
+  --lqip-max-bytes 4096 \
+  --wait --download ./placeholders.zip
+```
+
+The ZIP contains `placeholders.json` and `lqip.webp`. If the encoded image exceeds
+`--lqip-max-bytes`, the job fails instead of returning an artifact over the requested
+ceiling. The JSON includes source and placeholder dimensions, source format, the
+requested timestamp, and an alpha-aware dominant colour. `--placeholder-time` defaults
+to the first frame at `0`; it does not request automatic representative-frame selection.
+
+Generate bounded composite review sheets from a video with one flat Standard processing
+unit per produced sheet:
+
+```bash
+mediaruntime run ./interview.mp4 \
+  --preset contact_sheet_v1 \
+  --contact-columns 5 \
+  --contact-rows 4 \
+  --contact-tile-width 240 \
+  --contact-tile-height 135 \
+  --contact-interval 12 \
+  --contact-max-sheets 3 \
+  --contact-format jpg \
+  --contact-quality 80 \
+  --wait --download ./contact-sheets.zip
+```
+
+The ZIP contains numbered composite images and `contact_sheet.json`, which maps every
+tile to its exact source timestamp. `--contact-duration 0` means the remaining video.
+`--contact-quality` applies to JPG and WebP; PNG is lossless.
+
+Guarantee that a JPG or WebP rendition stays within a hard byte ceiling:
+
+```bash
+mediaruntime run ./photo.png \
+  --preset image_multi_v1 \
+  --image-width 1280 --image-height 720 --image-mode cover \
+  --image-format webp --image-quality 86 \
+  --image-max-bytes 200000 --image-min-quality 35 \
+  --wait --download ./bounded-image.zip
+```
+
+MediaRuntime performs a bounded quality search and verifies the final file. If the
+constraint cannot be met, the job fails instead of returning an oversized image. The ZIP
+includes `image_size_limits.json`; PNG and AVIF do not accept `--image-max-bytes` yet.
+
+## Privacy redaction
+
+Privacy redaction is an explicit Premium Preview for still-image inputs and image outputs.
+The CLI rejects obvious video or animated-image sources locally, expands the selected
+preset through the live capability catalog, and confirms the output is an image before
+uploading local media:
+
+```bash
+mediaruntime run ./team-photo.jpg \
+  --preset image_multi_v1 \
+  --privacy-detector face \
+  --privacy-detector license_plate \
+  --privacy-detector text \
+  --privacy-style blur \
+  --privacy-failure-mode fail_closed \
+  --wait --download ./redacted.zip
+```
+
+Detector flags are repeatable. Optional bounds include `--privacy-min-confidence`,
+`--privacy-sample-interval`, `--privacy-max-frames`, and `--privacy-padding`; solid masks
+also accept `--privacy-solid-color`, while pixelation accepts
+`--privacy-pixel-block-size` and `--privacy-strength`. Per-sample observations are
+available only with `--privacy-debug-observations`. The ZIP contains the redacted image and
+`privacy_redaction.json` schema v3. Public metadata reports stable detector categories,
+counts, verification outcomes, and ZIP-relative `report_bundle_path` and
+`output_bundle_paths`; it excludes detector vendors, model identities, private model or
+worker paths, bucket names, and raw OCR text. Automated detection can miss sensitive
+regions, so `coverage_verified` remains false and review is required before regulated use.
+In `fail_closed` mode detector failure, unresolved ambiguity, truncation,
+or a verified residual prevents image delivery. Recognizable residuals under blur or
+pixelation may be escalated to bounded opaque masks and verified again. Detector recall
+remains non-exhaustive.
+`--privacy-max-frames` applies independently to each 60-second segment. The defaults are a
+0.2-second interval and 1,800 frames per segment.
+
 ## Hosted recipes
 
 Hosted recipes are immutable account-scoped versions of a complete outputs, moderation,
@@ -118,6 +228,142 @@ Use `--json` for one compact, URL-redacted machine-readable result. A caller-pro
 `--idempotency-key` remains the durable deduplication mechanism across process restarts;
 the SDK-generated invocation key only protects retries inside one live command.
 
+## Check video compatibility
+
+The CLI reads the live capability catalog, so it can run the versioned compatibility
+preset without hard-coding its profile rules:
+
+```bash
+mediaruntime run ./launch.webm \
+  --preset compatibility_report_v1 \
+  --download ./launch-compatibility.zip
+```
+
+The ZIP contains `compatibility_report.json` with five conservative web, mobile,
+social-upload, and editing profiles, rule-level evidence, and existing corrective preset
+recommendations. It is actionable guidance, not exhaustive certification of every device.
+
+## Scan QR codes and barcodes
+
+Use the live `code_detect_v1` preset with an image, video, animated image, or an
+audio file that contains embedded cover artwork:
+
+```sh
+mediaruntime run ./product-label.png \
+  --preset code_detect_v1 \
+  --wait --download ./detected-codes.zip
+```
+
+The ZIP contains `codes.json` plus evidence PNGs only for frames with unique
+detections. Video is sampled at the opening frame and every 10 seconds, up to 12
+frames and 16 unique codes per frame. Plain audio without cover artwork is rejected. Decoded values are untrusted:
+render them as text and never automatically open a detected URL.
+
+## Generate an audiogram
+
+Compose an audio track, supplied artwork, a generated waveform, and optional supplied
+captions with the Premium `audiogram_v1` preset. The main audio, artwork, and captions
+may each be local files; the CLI uploads local assets through the authenticated account's
+signed-upload flow before creating the job:
+
+```bash
+mediaruntime run ./episode.mp3 \
+  --preset audiogram_v1 \
+  --audiogram-artwork ./cover.png \
+  --audiogram-captions ./episode.vtt \
+  --audiogram-layout square \
+  --audiogram-fit blurred_background \
+  --audiogram-background '#101827' \
+  --audiogram-waveform '#5B5CFF' \
+  --audiogram-waveform-gain 2 \
+  --audiogram-caption-position bottom \
+  --audiogram-caption-scale 1 \
+  --audiogram-normalize --audiogram-loudness-target -16 \
+  --audiogram-duration 60 \
+  --audiogram-fps 30 \
+  --wait --download ./audiogram.zip
+```
+
+Artwork must be PNG, JPEG, or WebP up to 10 MB. Captions must be UTF-8 SRT or VTT up
+to 2 MB; supplying captions burns them into the video. The ZIP contains
+`audiogram.mp4`, a caption-free `poster.jpg`, `audiogram.json`, and
+`audiogram.waveform.json`. Artwork fitting, waveform gain, caption placement, and
+optional loudness normalization are bounded named controls. Account watermarking
+and speech-generated subtitles cannot be combined with this preset in v1.
+
+Captions use their own top or bottom strip inside the reserved band and cannot cover caller
+artwork. Multi-line cues scale down adaptively. The caption-free poster is sampled after
+waveform activity begins, and successful normalization reports measured loudness values.
+
+## Hosted Sticker Runtime
+
+Sticker collections are free application configuration over packs your workspace already
+activated. Create a collection, then enable an existing paid Hosted Pack by its stable pack
+ID or activation ID:
+
+```bash
+mediaruntime stickers collections create \
+  --name "Support chat" \
+  --description "Customer-facing reactions"
+
+mediaruntime stickers collections list
+mediaruntime stickers collections get stc_0123456789abcdef0123456789abcdef
+mediaruntime stickers collections update stc_0123456789abcdef0123456789abcdef \
+  --name "Support and community"
+
+mediaruntime stickers collections packs enable stc_0123456789abcdef0123456789abcdef \
+  --pack white-sage-just-me
+mediaruntime stickers collections packs list stc_0123456789abcdef0123456789abcdef
+mediaruntime stickers collections packs disable stc_0123456789abcdef0123456789abcdef \
+  --pack white-sage-just-me
+```
+
+Disabling a pack prevents new discovery but preserves exact historical rendering under the
+binding's `historicalAccess` policy. `collections archive` is also recoverable; restore with
+`collections update <id> --status active`. These commands do not buy, activate, revoke, or
+charge for a pack. Use the authenticated MediaRuntime account surface for paid activation.
+
+Search and resolve assets inside one explicitly selected collection:
+
+```bash
+mediaruntime stickers packs list --collection stc_0123456789abcdef0123456789abcdef
+mediaruntime stickers search "wave" \
+  --collection stc_0123456789abcdef0123456789abcdef \
+  --category greeting --animated --limit 10
+mediaruntime stickers typeahead "wa" \
+  --collection stc_0123456789abcdef0123456789abcdef --locale en
+mediaruntime stickers get white-sage-just-me-wave \
+  --collection stc_0123456789abcdef0123456789abcdef
+mediaruntime stickers resolve white-sage-just-me-wave \
+  --variant small_160 \
+  --collection stc_0123456789abcdef0123456789abcdef
+```
+
+All sticker commands use `MEDIARUNTIME_API_KEY` or the secure browser login by default.
+Untrusted application testing may instead set a short-lived token for only the five runtime
+read commands above:
+
+```bash
+mediaruntime stickers token create \
+  --collection stc_0123456789abcdef0123456789abcdef \
+  --expires-in 900 \
+  --scope packs:read \
+  --scope stickers:search \
+  --scope stickers:read \
+  --scope assets:resolve
+
+export MEDIARUNTIME_STICKER_CLIENT_TOKEN="mrt_v1_..."
+mediaruntime stickers search "wave" \
+  --collection stc_0123456789abcdef0123456789abcdef
+```
+
+The scoped token never authorizes collection management, pack binding, workspace usage, or
+token minting; those always require the trusted API key. The CLI accepts the scoped secret
+only through `MEDIARUNTIME_STICKER_CLIENT_TOKEN`, not a command-line flag. The collection
+argument must still match the token claim. Inspect pooled monthly usage with
+`mediaruntime stickers usage`. See [the Sticker Runtime command contract](docs/STICKERS.md)
+for complete flags, JSON behavior, and security boundaries.
+
 ## Inspect jobs
 
 ```bash

package/dist/cli.d.ts

@@ -39,6 +39,110 @@ interface RecipesClient {
     archive(name: string): Promise<void>;
 }
 
+interface StickerCollectionRecord {
+    collectionId: string;
+    name: string;
+    description: string;
+    status: "active" | "archived";
+    packs: StickerPackBinding[];
+    createdAt: string;
+    archivedAt: string | null;
+    updatedAt: string;
+}
+interface StickerPackBinding {
+    bindingId: string;
+    collectionId: string;
+    activationId: string;
+    packId: string;
+    packName: string;
+    packVersion: string;
+    status: "enabled" | "disabled";
+    historicalAccess: "preserve" | "revoke";
+    updatedAt: string | null;
+}
+interface RuntimeStickerRecord {
+    stickerId: string;
+    packId: string;
+    label: string;
+    emoji: string | null;
+    category: string | null;
+    animated: boolean;
+    variants: Array<{
+        name: string;
+        bytes: number;
+    }>;
+    score?: number;
+}
+interface RuntimeStickerPackRecord {
+    packId: string;
+    name: string;
+    version: string;
+    assetCount: number;
+    animated: boolean;
+}
+interface StickerRuntimeReadClient {
+    listPacks(): Promise<RuntimeStickerPackRecord[]>;
+    search(query: string, options?: {
+        packId?: string;
+        category?: string;
+        animated?: boolean;
+        limit?: number;
+    }): Promise<{
+        query: string;
+        items: RuntimeStickerRecord[];
+        total: number;
+    }>;
+    typeahead(query: string, options?: {
+        packId?: string;
+        locale?: string;
+        limit?: number;
+    }): Promise<{
+        query: string;
+        locale: string;
+        suggestions: Array<{
+            text: string;
+            assetCount: number;
+        }>;
+    }>;
+    retrieve(stickerId: string): Promise<RuntimeStickerRecord>;
+    resolve(stickerId: string, variant: string): Promise<Record<string, unknown>>;
+}
+interface HostedStickersCommandClient {
+    listCollections(options?: {
+        includeArchived?: boolean;
+    }): Promise<{
+        items: StickerCollectionRecord[];
+        total: number;
+    }>;
+    createCollection(params: {
+        name: string;
+        description?: string | null;
+    }): Promise<StickerCollectionRecord>;
+    getCollection(collectionId: string): Promise<StickerCollectionRecord>;
+    updateCollection(collectionId: string, params: {
+        name?: string;
+        description?: string | null;
+        status?: "active" | "archived";
+    }): Promise<StickerCollectionRecord>;
+    archiveCollection(collectionId: string): Promise<StickerCollectionRecord>;
+    listCollectionPacks(collectionId: string): Promise<{
+        items: StickerPackBinding[];
+        total: number;
+    }>;
+    addCollectionPack(collectionId: string, params: {
+        activationId: string;
+    }): Promise<StickerPackBinding>;
+    enableCollectionPack(collectionId: string, packId: string): Promise<StickerPackBinding>;
+    disableCollectionPack(collectionId: string, packId: string): Promise<StickerPackBinding>;
+    collection(collectionId: string): StickerRuntimeReadClient;
+    usage(): Promise<Record<string, unknown>>;
+    createClientToken(params: {
+        collectionId: string;
+        expiresInSeconds?: number;
+        scopes?: string[];
+    }): Promise<Record<string, unknown>>;
+}
+
 declare const SUPPORTED_TRIGGER_EVENTS: readonly ["job.completed", "job.failed", "job.rejected"];
 type TriggerEventType = (typeof SUPPORTED_TRIGGER_EVENTS)[number];
 interface SyntheticEventOptions {
@@ -102,13 +206,22 @@ type CliJobsClient = RunJobsClient & JobsReadClient;
 interface CliClient {
     jobs: CliJobsClient;
     capabilities: CapabilitiesReadClient;
+    uploads?: {
+        resolveSource(source: string): Promise<string>;
+    };
     recipes?: RecipesClient;
+    stickers?: HostedStickersCommandClient;
 }
 interface CliDependencies {
     createClient?(options: {
         baseUrl?: string;
         apiKey?: string;
     }): CliClient;
+    createStickerRuntime?(options: {
+        accessToken: string;
+        collectionId: string;
+        baseUrl?: string;
+    }): StickerRuntimeReadClient;
     downloadBundle?(url: string, destination: string, options: {
         force: boolean;
         expectedSizeBytes?: number | null;