@spatius/cli 0.1.0-beta.0

package/skills/spatius-video/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: spatius-video
+description: Render downloadable Spatius avatar videos from audio and optional backgrounds using Spatius CLI. Use for local or URL media preparation, video submission, polling, safe resume, and MP4 download.
+license: MIT
+---
+
+# Render an avatar video
+
+Use an existing permitted avatar ID, or create one with the avatar skill. Check
+`spatius auth status` and `spatius schema videos create` before the workflow.
+Studio login and Video API approval are separate requirements.
+
+Use the supplied audio and optional background; the CLI does not synthesize
+speech. Local files upload automatically. Supported audio includes WAV, MP3,
+M4A/MP4 audio, AAC, and Ogg, up to 500 MiB. Backgrounds are JPEG, PNG, or WebP up
+to 50 MiB. Raw PCM must first be wrapped correctly in WAV; changing its extension
+does not convert it. For settings and lifetime details, read
+[inputs and recovery](references/inputs-and-recovery.md).
+
+```sh
+spatius videos create --avatar-id 00000000-0000-4000-8000-000000000001 --audio ./speech.wav --background ./background.png --dry-run
+spatius videos create --avatar-id 00000000-0000-4000-8000-000000000001 --audio ./speech.wav --background ./background.png
+```
+
+Replace the UUID and paths with the actual inputs. Save `operationId` and
+`jobId`. The CLI saves a request UUID and resolved URLs before submission.
+After interruption, use `spatius videos create --resume <operation-id>`;
+do not rerun creation with fresh uploads or a new request UUID.
+
+```sh
+spatius videos wait 00000000-0000-4000-8000-000000000001 --timeout 600
+spatius videos download 00000000-0000-4000-8000-000000000001 --output ./video.mp4
+```
+
+Replace the example job UUID with the returned one. Waiting polls every 15 seconds;
+exit 3 means the job is still pending. Download obtains a fresh link and writes
+the MP4 atomically. It refuses to replace an existing file unless `--force` is
+explicitly supplied.
+
+If a successful job's download-link refresh fails, retry the read/download.
+A terminal `failed` or `expired` job does not restart. Explain its error and only
+create another render when that is the intended next action. A saved operation
+whose source URLs expired after an uncertain submission needs reconciliation,
+not replacement inputs under the old request ID.

package/skills/spatius-video/references/inputs-and-recovery.md

@@ -0,0 +1,35 @@
+# Inputs, presentation, and recovery
+
+| Setting            | Default and allowed range                                      |
+| ------------------ | -------------------------------------------------------------- |
+| Width / height     | 1024 each; even integers 64–1920, total area ≤2,073,600 pixels |
+| Fit                | `crop`; `contain` also supported                               |
+| Background color   | `#000000`; six-digit RGB hex                                   |
+| Background fit     | `cover`; `contain` or `stretch` also supported                 |
+| Lead-in / lead-out | 0; each 0–60 seconds of additional idle time                   |
+
+The service controls encoding. Transitions can make output longer than the
+audio even with zero additional idle time. Audio decoding and duration checks
+happen in the renderer.
+
+Temporary uploads are immutable and available for 24 hours after completion.
+External URLs must remain accessible throughout preparation, which can take
+up to 30 minutes. Source hosts must serve a supported media Content-Type, not
+`application/octet-stream`. Public HTTP(S) and signed URLs work; private-network
+URLs and embedded username/password credentials do not.
+
+Video retry identity includes its normalized request body. The same UUID with
+different resolved URLs conflicts, even if the underlying local file is the same.
+Resume preserves the exact request. Never refresh or replace those input URLs
+after submission became uncertain. A terminal failure requires an intentional
+new operation, not an automatic retry of the failed job.
+
+Output is currently retained seven days after render submission; use the returned
+`job.expiresAt`. Signed output links currently last up to 15 minutes, capped by
+retention. `videos download` refreshes the link. Downloading or refreshing a link
+does not extend output retention.
+
+Downloads require a direct HTTPS output link; the CLI does not follow redirects
+or forward Studio/App credentials to storage. For `DOWNLOAD_UNAVAILABLE`, repeat
+`videos download` to request a fresh link. Do not work around a redirect rejection
+by attaching credentials to another host.