feat: add preview command to open Shotstack Edit JSON in browser editor

Author: dazzatronus

README.md

@@ -67,6 +67,23 @@ shotstack status 01ja7-x8m2k-... --watch
 shotstack status 01ja7-x8m2k-... --output json
 ```
 
+### `shotstack preview <file>`
+
+Opens a `shotstack.studio` URL that loads the Edit JSON directly into the browser-based editor. No API call, no key, no charge — pure client-side encoding via the URL hash. Use it to hand a generated edit off to a human for review or quick tweaks before rendering.
+
+```sh
+shotstack preview my-template.json
+# → opens browser silently
+
+shotstack preview my-template.json --copy        # also copies URL to clipboard
+shotstack preview my-template.json --no-open     # print URL, don't open browser
+shotstack preview my-template.json --output json # emit {"url":"..."} on stdout
+```
+
+When a browser can be launched, the command is silent — the URL only opens in the browser. On a headless server (no `$DISPLAY`, no `xdg-open`), the URL is printed to stdout instead so you can copy it elsewhere.
+
+Templates whose encoded URL exceeds ~6KB print a stderr warning. Browser URL limits vary; if you regularly exceed it, host the JSON publicly and link to it via `https://shotstack.studio/#src=<https-url>`.
+
 ### `shotstack feedback`
 
 Opens a pre-filled GitHub issue with a sanitised dossier of your last 5 CLI invocations (render IDs, errors, exit codes). API keys and signed URLs are stripped at write time. You review and submit in your browser; nothing is transmitted automatically. Inspect the log at `~/.shotstack/log.jsonl`.

SKILL.md

@@ -4,26 +4,25 @@ description: |
   Render video and poll render status via the Shotstack API.
   Use when generating clips, building automated video pipelines, or orchestrating
   cloud video renders from a script, agent, or CI workflow.
-  NOT for: real-time streaming, live broadcasting, or in-browser editing UIs.
+  NOT for: real-time streaming, or live broadcasting.
 license: Apache-2.0
 ---
 
 # Shotstack CLI
 
-Two commands for the Shotstack video rendering API. `render` submits a timeline JSON and returns a render ID; `status` polls a render until done.
+Two commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done.
 
 ## Authentication
 
 ```sh
-export SHOTSTACK_API_KEY=sk_...
+export SHOTSTACK_API_KEY=...
 ```
 
-Get a key at <https://dashboard.shotstack.io>. Without a key, every command exits with code 1.
+Get a key at <https://app.shotstack.io>. Without a key, every command exits with code 1.
 
 ## Environments
 
 ```
---env dev      → https://api.shotstack.io/edit/dev
 --env stage    → https://api.shotstack.io/edit/stage   (test credits, free)
 --env v1       → https://api.shotstack.io/edit/v1      (production, default)
 ```
@@ -39,26 +38,42 @@ shotstack render template.json --output json --env stage
 
 # Poll until terminal state.
 shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch --env stage
-# → done  https://shotstack-api-stage-output.s3.amazonaws.com/.../out.mp4
+# → done  https://shotstack-api-stage-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
 ```
 
-## Three CLI rules
+## Hand-off to a human before rendering
+
+When a human is in the loop and may want to tweak the result, prefer **`shotstack preview <file>`** over `shotstack render`. By default it opens the browser to `https://shotstack.studio/#json=<base64url>` and prints the URL — the timeline loads directly into the browser-based editor. No API call, no key, no charge. The human can play, edit, and decide whether to render — saving credits when the AI's first attempt isn't quite right.
+
+```sh
+shotstack preview template.json              # opens browser + prints URL
+shotstack preview template.json --no-open    # headless: just print the URL
+shotstack preview template.json --output json # piping: {"url":"..."}, no browser
+```
+
+On headless systems (no `xdg-open`, no `$DISPLAY`) the browser launch silently no-ops; the URL is still printed. Safe to run anywhere.
+
+Use `render` only when you're confident the JSON is final, or there's no human to review.
+
+## Four CLI rules
 
 1. **Pipe → `--output json`.** Default output is human-readable. When parsing programmatically or piping to another command, always pass `--output json`. The text format is not stable across versions.
 
 2. **Use `--watch`, not a polling loop.** `shotstack status <id> --watch` exits when the render reaches `done` (exit 0) or `failed` (exit 1). Don't write `while true; do ...; sleep 3; done`.
 
-3. **Fetch the current docs before generating timeline JSON.** The Shotstack API evolves; LLM training data is often stale. Pull <https://shotstack.io/docs/guide/llms-full.txt> for the current schema and examples before composing a timeline from scratch.
+3. **Fetch the current docs before generating Edit JSON.** The Shotstack API evolves; LLM training data is often stale. Pull <https://shotstack.io/docs/guide/llms-full.txt> for the current schema and examples before composing an Edit from scratch.
+
+4. **Hand off to a human via `preview` when uncertain.** Don't burn render credits iterating. Generate JSON → `shotstack preview` → human reviews/tweaks → render only when right.
 
-## Authoring timeline JSON
+## Authoring Edit JSON
 
-These are the conventions agents most often get wrong. Read this section before generating any timeline JSON.
+These are the conventions agents most often get wrong. Read this section before generating any Edit JSON.
 
 ### Before composing JSON: check the schema
 
 Don't invent property names or enum values. The Shotstack schema is published — fetch one of these before composing JSON from scratch:
 
-- <https://shotstack.io/docs/api/api.bundled.json> — single-file JSON Schema. Machine-validatable; load it once and validate locally instead of round-tripping the API.
+- <https://shotstack.io/docs/api/api.edit.json> — single-file OpenAPI Schema. Machine-validatable; load it once and validate locally instead of round-tripping the API.
 - <https://shotstack.io/docs/api/> — interactive HTML reference. Fastest for human scanning.
 - <https://shotstack.io/docs/guide/llms-full.txt> — single-file LLM-friendly version of the full guide + reference.
 - <https://github.com/shotstack/oas-api-definition/tree/main/schemas> — raw OpenAPI YAML, source of truth.
@@ -167,7 +182,7 @@ The render API supports many asset types. Use only the **current** ones; the dep
 
 ### AI-generated assets
 
-`image-to-video` and `text-to-image` are billed per generation **even when invoked through the sandbox stage endpoint** (which is otherwise free). They are async — the render submits the AI job and waits. Renders containing AI assets take longer.
+`image-to-video`, `text-to-speech`, and `text-to-image` are billed per generation **even when invoked through the sandbox stage endpoint** (which is otherwise free). They are async — the render submits the AI job and waits. Renders containing AI assets take longer.
 
 ## Fonts
 
@@ -220,10 +235,11 @@ The `font.family` value is the **font file basename** (without `.ttf`/`.otf`).
 Authoritative sources, in order of preference:
 
 - `shotstack --help` and `shotstack <command> --help` — current CLI flag listing
-- <https://shotstack.io/docs/api/api.bundled.json> — JSON Schema for the render API (machine-validatable)
+- <https://shotstack.io/docs/api/api.edit.json> — OpenAPI Schema for the render API (machine-validatable)
 - <https://shotstack.io/docs/guide/llms-full.txt> — full API docs in LLM-friendly single file
 - <https://github.com/shotstack/oas-api-definition/tree/main/schemas> — raw OpenAPI YAML, source of truth for property names and enums
-- <https://shotstack.io/docs/api/> — interactive HTML reference
+- <https://shotstack.io/docs/guide/> — interactive HTML docs and guides
+- <https://shotstack.io/docs/api/> — interactive HTML API reference
 - <https://github.com/shotstack/shotstack-cli> — CLI source
 
 This skill ships sub-references for the gnarly bits:

references/timeline.md

@@ -1,6 +1,6 @@
 # Timeline conventions
 
-Detailed guide to track layering, the soundtrack vs audio distinction, and `timeline.fonts[]`. Read this when building any non-trivial timeline JSON.
+Detailed guide to track layering, the soundtrack vs audio distinction, and `timeline.fonts[]`. Read this when building any non-trivial Edit JSON.
 
 ## Contents
 
@@ -74,13 +74,7 @@ If you put the video first and the captions last, the video covers the captions
 
 ## Soundtrack vs audio asset
 
-There are two ways to add audio. Pick the right one.
-
-| Use `timeline.soundtrack` when | Use `audio` asset when |
-|---|---|
-| One background music track for the entire timeline | Sound effects at specific times |
-| Loop or fade the music | Voiceover synced to specific clips |
-| You don't need to control timing | Multiple audio sources at different times |
+Prefer `Audio` assets — they support custom timing, keyframes, and effects, and can do everything `timeline.soundtrack` can. Use `timeline.soundtrack` only when you want a single background track spanning the whole edit.
 
 ```json
 {
@@ -94,7 +88,9 @@ There are two ways to add audio. Pick the right one.
 }
 ```
 
-Soundtrack supported `effect` values: `fadeIn`, `fadeOut`, `fadeInFadeOut`.
+`soundtrack.effect` accepts `fadeIn`, `fadeOut`, or `fadeInFadeOut`.
+
+An `audio` clip with `length: "end"` is functionally identical to `timeline.soundtrack`.
 
 ## `timeline.fonts[]` for custom fonts
 

references/troubleshooting.md

@@ -13,7 +13,7 @@ Common errors and the fix for each. If your error isn't here, run `shotstack fee
 - "Invalid asset URL"
 - "Render failed" with no other detail
 - Render takes much longer than expected
-- Stage credits exhausted
+- Credits exhausted on stage environment
 
 ## "Unknown property: alignment" (and similar)
 
@@ -28,7 +28,7 @@ You used a property name from CSS or HTML instinct — `alignment`, `font.name`,
 | `duration` | `length` |
 | `transitions: [...]` (array) | `transition: { in, out }` (object) |
 
-Always check <https://shotstack.io/docs/api/api.bundled.json> (JSON Schema) or <https://shotstack.io/docs/guide/llms-full.txt> before composing timeline JSON. Don't guess from CSS conventions.
+Always check <https://shotstack.io/docs/api/api.edit.json> (OpenAPI Schema) or <https://shotstack.io/docs/guide/llms-full.txt> before composing Edit JSON. Don't guess from CSS conventions.
 
 ## "Invalid option: expected one of top|middle|bottom"
 
@@ -91,11 +91,11 @@ Renders containing AI-generation assets (`text-to-image`, `image-to-video`) take
 
 **Fix:** if you're iterating quickly, render with `output.resolution: "preview"` first (512×288 @ 15fps) to validate the timeline shape before spending credits on full-resolution output.
 
-## Stage credits exhausted
+## Credits exhausted on stage environment
 
-The `stage` environment uses test credits. They reset on a regular cadence but can be exhausted if you run many renders.
+The `stage` environment uses no credits, but you do require a positive credit balance to make use of the sandbox.
 
-**Fix:** wait for the reset, or run against `--env v1` (production credits, real money). Check current credit balance at <https://dashboard.shotstack.io>.
+**Fix:** add more credits to your account. Check current credit balance at <https://app.shotstack.io>.
 
 ## Filing a useful bug report
 

src/commands/preview.ts

@@ -0,0 +1,93 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { spawn, execSync } from "node:child_process";
+import { Command } from "commander";
+import { emit, parseOutputFormat } from "../output.ts";
+
+const STUDIO_URL = "https://shotstack.studio";
+const URL_WARN_THRESHOLD = 6000;
+
+export const previewCommand = new Command("preview")
+  .description("Open a shotstack.studio URL that loads the Edit JSON in the browser editor")
+  .argument("<file>", "Path to a Shotstack Edit JSON file")
+  .option("--copy", "Copy the URL to the clipboard")
+  .option("--no-open", "Do not try to open the URL in a browser")
+  .option("--output <format>", "Output format: text | json", "text")
+  .action(async (file: string, options: { copy?: boolean; open: boolean; output: string }) => {
+    const format = parseOutputFormat(options.output);
+
+    const path = resolve(process.cwd(), file);
+    const raw = await readFile(path, "utf8");
+    const template = JSON.parse(raw) as unknown;
+    assertTemplateShape(template);
+
+    const url = buildPreviewUrl(template);
+
+    if (url.length > URL_WARN_THRESHOLD) {
+      console.error(`warning: encoded URL is ${url.length} characters; large templates may exceed browser URL limits.`);
+    }
+
+    if (options.copy) await copyToClipboard(url);
+
+    const opened = options.open && browserAvailable() && openInBrowser(url);
+
+    if (format === "json" || !opened) {
+      emit(format, { url }, url);
+    }
+  });
+
+export function buildPreviewUrl(template: unknown): string {
+  const encoded = Buffer.from(JSON.stringify(template), "utf8").toString("base64url");
+  return `${STUDIO_URL}/#json=${encoded}`;
+}
+
+function assertTemplateShape(t: unknown): asserts t is { timeline: unknown; output: unknown } {
+  if (!t || typeof t !== "object") throw new Error("Template must be a JSON object.");
+  if (!("timeline" in t)) throw new Error("Template missing required field: timeline.");
+  if (!("output" in t)) throw new Error("Template missing required field: output.");
+}
+
+async function copyToClipboard(text: string): Promise<void> {
+  const { cmd, args } = clipboardCommand();
+  await new Promise<void>((res, rej) => {
+    const proc = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+    proc.on("error", rej);
+    proc.on("exit", (code) => (code === 0 ? res() : rej(new Error(`${cmd} exited ${code}`))));
+    proc.stdin.end(text);
+  });
+}
+
+function clipboardCommand(): { cmd: string; args: string[] } {
+  if (process.platform === "darwin") return { cmd: "pbcopy", args: [] };
+  if (process.platform === "win32") return { cmd: "clip", args: [] };
+  return { cmd: "xclip", args: ["-selection", "clipboard"] };
+}
+
+function openInBrowser(url: string): boolean {
+  const { cmd, args } = browserCommand(url);
+  try {
+    const proc = spawn(cmd, args, { detached: true, stdio: "ignore" });
+    proc.on("error", () => {});
+    proc.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function browserCommand(url: string): { cmd: string; args: string[] } {
+  if (process.platform === "win32") return { cmd: "cmd", args: ["/c", "start", "", url] };
+  if (process.platform === "darwin") return { cmd: "open", args: [url] };
+  return { cmd: "xdg-open", args: [url] };
+}
+
+function browserAvailable(): boolean {
+  if (process.platform === "darwin" || process.platform === "win32") return true;
+  if (!process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return false;
+  try {
+    execSync("command -v xdg-open", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}

src/commands/render.ts

@@ -14,8 +14,8 @@ interface RenderResponse {
 }
 
 export const renderCommand = new Command("render")
-  .description("Submit a Shotstack timeline JSON to the render API")
-  .argument("<file>", "Path to a Shotstack timeline JSON file")
+  .description("Submit a Shotstack Edit JSON to the render API")
+  .argument("<file>", "Path to a Shotstack Edit JSON file")
   .option(`--env <name>`, `Environment: ${ENV_NAMES.join(" | ")}`)
   .option("--output <format>", "Output format: text | json", "text")
   .action(async (file: string, options: { env?: string; output: string }) => {

src/index.ts

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { renderCommand } from "./commands/render.ts";
 import { statusCommand } from "./commands/status.ts";
 import { feedbackCommand } from "./commands/feedback.ts";
+import { previewCommand } from "./commands/preview.ts";
 import { ApiError } from "./http/client.ts";
 import { MissingApiKeyError } from "./http/auth.ts";
 import { InvalidEnvError } from "./http/env.ts";
@@ -13,6 +14,7 @@ const program = new Command()
   .version(version)
   .addCommand(renderCommand)
   .addCommand(statusCommand)
+  .addCommand(previewCommand)
   .addCommand(feedbackCommand);
 
 try {

tests/preview.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "bun:test";
+import { buildPreviewUrl } from "../src/commands/preview.ts";
+
+const sample = {
+  timeline: {
+    background: "#000000",
+    tracks: [
+      {
+        clips: [
+          {
+            asset: { type: "rich-text", text: "hello", font: { family: "Roboto", size: 22 } },
+            start: 0,
+            length: 5,
+          },
+        ],
+      },
+    ],
+  },
+  output: { size: { width: 1920, height: 1080 }, format: "mp4" },
+};
+
+describe("buildPreviewUrl", () => {
+  test("emits a shotstack.studio URL with #json= hash", () => {
+    const url = buildPreviewUrl(sample);
+    expect(url.startsWith("https://shotstack.studio/#json=")).toBe(true);
+  });
+
+  test("encoded payload uses base64url alphabet (no +, /, =)", () => {
+    const url = buildPreviewUrl(sample);
+    const encoded = url.split("#json=")[1]!;
+    expect(encoded).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  test("decoding the hash returns identical JSON", () => {
+    const url = buildPreviewUrl(sample);
+    const encoded = url.split("#json=")[1]!;
+    const decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    expect(decoded).toEqual(sample);
+  });
+
+  test("handles unicode in text fields", () => {
+    const tpl = { ...sample, timeline: { ...sample.timeline, tracks: [{ clips: [{ asset: { type: "rich-text", text: "héllo 🌏 中文" }, start: 0, length: 1 }] }] } };
+    const url = buildPreviewUrl(tpl);
+    const encoded = url.split("#json=")[1]!;
+    const decoded = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    expect(decoded).toEqual(tpl);
+  });
+});