Skip to content

Commit 723ab74

Browse files
authored
Merge pull request #50 from shotstack/derk/analyze-on-generate
[1/2] Analyze tracks through /generate
2 parents 3529014 + e50285d commit 723ab74

5 files changed

Lines changed: 83 additions & 35 deletions

File tree

‎skills/shotstack/SKILL.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ If a check fails (no network, no npm, a sandbox), skip it and carry on.
2424

2525
**Open-ended first render? Ask before composing.** If the ask doesn't state what the video is (subject, format or destination) — e.g. "render my first video", "make me a video", "set up Shotstack" — read [`references/onboarding.md`](references/onboarding.md) and ask its discovery questions, then WAIT for answers. Do not write an Edit first. An open-ended ask is not a specification, and a stray JSON file in the project doesn't make the user experienced. Compose without asking only when the user has stated what the video is, or explicitly says to just show anything.
2626

27-
Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one. `models` lists the generation models for prompt-driven assets and whether this key can use each one; `models <id>` prints the options a model accepts. `generate <model> "<prompt>"` generates one asset on its own and prints its URL. `analyze <url>` measures a music track's tempo, beats, bars, drops and sections, free and without a key.
27+
Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one. `models` lists the generation models for prompt-driven assets and whether this key can use each one; `models <id>` prints the options a model accepts. `generate <model> "<prompt>"` generates one asset on its own and prints its URL. `analyze <url>` measures a music track's tempo, beats, bars, drops and sections, free, and needs an API key.
2828

29-
**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
29+
**Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`, `analyze`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
3030

3131
## Authentication
3232

@@ -45,7 +45,7 @@ Or set an environment variable (overrides the saved key — best for CI):
4545
export SHOTSTACK_API_KEY=...
4646
```
4747

48-
Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
48+
Resolution precedence: **`SHOTSTACK_API_KEY` env var → saved key for the target `--env` → error.** Get a key at <https://app.shotstack.io>. **`validate` and `studio` need no key** — only the API-backed commands (`render`, `status`, `ingest`, `models`, `generate`, `analyze`) require one; without a key *those* exit 1, while compose → validate → studio keeps working.
4949

5050
## Environments
5151

‎skills/shotstack/references/beat-sync.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Host a local file with `shotstack ingest upload <file> --watch`. Generate a trac
1818

1919
Analysis is free, takes 15–30 s and reads the first 10 minutes of the track.
2020

21-
It needs no API key. The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
21+
It needs an API key (`shotstack login`). The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
2222
<!-- surface:cli -->
2323
```sh
2424
shotstack analyze https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3 --output json > map.json

‎src/commands/analyze.ts‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { Command } from "commander";
2+
import { requireApiKey } from "../http/auth.ts";
23
import { createClient, type Client } from "../http/client.ts";
34
import { resolveEnv, ENV_NAMES } from "../http/env.ts";
45
import { emit, type OutputFormat, parseOutputFormat } from "../output.ts";
@@ -20,7 +21,7 @@ export interface MusicMap {
2021
export interface Analysis {
2122
id: string;
2223
status: "queued" | "processing" | "done" | "failed";
23-
result?: MusicMap;
24+
url?: string;
2425
error?: string;
2526
}
2627

@@ -36,8 +37,9 @@ export const analyzeCommand = new Command("analyze")
3637
.action(async (src: string, options: { env?: string; output: string }) => {
3738
await withRecording("analyze", commandArgv("analyze"), async () => {
3839
const format = parseOutputFormat(options.output);
39-
// Analysis is free and needs no API key.
40-
const client = createClient({ env: resolveEnv(options.env) });
40+
// Analysis costs no credits, but /generate requires a key to identify the account.
41+
const env = resolveEnv(options.env);
42+
const client = createClient({ apiKey: requireApiKey(env.name), env });
4143
return runAnalyze(client, src, format);
4244
});
4345
});
@@ -49,21 +51,33 @@ export async function runAnalyze(
4951
format: OutputFormat,
5052
intervalMs: number = POLL_INTERVAL_MS,
5153
): Promise<CommandResult> {
52-
let job = await client.post<Analysis>("/analysis", { src });
54+
let job = await client.post<Analysis>("/generate", {
55+
asset: { type: "audio", model: "shotstack-music-analysis", src },
56+
});
5357
while (!TERMINAL_STATES.has(job.status)) {
5458
if (format !== "json") console.error(`${job.status} ${job.id}`);
5559
await sleep(intervalMs);
56-
job = await client.get<Analysis>(`/analysis/${encodeURIComponent(job.id)}`);
60+
job = await client.get<Analysis>(`/generate/${encodeURIComponent(job.id)}`);
5761
}
5862
if (job.status === "failed") {
5963
emit(format, job, `failed error: ${job.error ?? "unknown error"}`);
6064
return { response: job, exitCode: 1 };
6165
}
62-
emit(format, job.result, `done ${formatSummary(job.result ?? {})}`);
66+
// The map is public JSON on the CDN: fetch it without the API key.
67+
if (!job.url) return fail(job, "analysis finished without a map URL");
68+
const res = await fetch(job.url);
69+
if (!res.ok) return fail(job, `could not fetch the analysis map (${res.status}) from ${job.url}`);
70+
const map = (await res.json()) as MusicMap;
71+
emit(format, map, `done ${formatSummary(map)}`);
6372
if (format !== "json") console.error("Print the full map with --output json.");
6473
return { response: job, exitCode: 0 };
6574
}
6675

76+
function fail(job: Analysis, message: string): CommandResult {
77+
console.error(message);
78+
return { response: job, exitCode: 1 };
79+
}
80+
6781
export function formatSummary(m: MusicMap): string {
6882
const counts = `${m.drops?.length ?? 0} drops, ${m.sections?.length ?? 0} sections`;
6983
if (!m.steady) {

‎src/http/client.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@ export class ApiError extends Error {
1717
}
1818

1919
export interface ClientOptions {
20-
// Absent for keyless endpoints such as /analysis.
21-
apiKey?: string;
20+
apiKey: string;
2221
env: ResolvedEnv;
2322
}
2423

@@ -31,7 +30,7 @@ export function createClient(options: ClientOptions) {
3130
const response = await fetch(`${baseUrl}${path}`, {
3231
method,
3332
headers: {
34-
...(options.apiKey !== undefined ? { "x-api-key": options.apiKey } : {}),
33+
"x-api-key": options.apiKey,
3534
"x-shotstack-origin": "cli",
3635
"x-shotstack-environment": options.env.name,
3736
"user-agent": userAgent,

‎tests/analyze.test.ts‎

Lines changed: 57 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { describe, test, expect, mock, spyOn } from "bun:test";
22
import { formatSummary, runAnalyze, type Analysis } from "../src/commands/analyze.ts";
3-
import { createClient, type Client } from "../src/http/client.ts";
3+
import { type Client } from "../src/http/client.ts";
44

55
const steady = {
66
bpm: 120.01,
@@ -25,26 +25,51 @@ async function capture(run: () => Promise<unknown>) {
2525
const err = spyOn(console, "error").mockImplementation(() => {});
2626
try {
2727
const result = await run();
28-
return { result, lines: log.mock.calls.map((c) => String(c[0])) };
28+
return { result, lines: log.mock.calls.map((c) => String(c[0])), errors: err.mock.calls.map((c) => String(c[0])) };
2929
} finally {
3030
log.mockRestore();
3131
err.mockRestore();
3232
}
3333
}
3434

35+
const MAP_URL = "https://cdn.example.com/a.json";
36+
const body = { asset: { type: "audio", model: "shotstack-music-analysis", src: "https://example.com/lit.mp3" } };
37+
38+
async function withMapFetch(run: (fetchMock: ReturnType<typeof spyOn>) => Promise<void>) {
39+
const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async () => new Response(JSON.stringify(steady)));
40+
try {
41+
await run(fetchMock);
42+
} finally {
43+
fetchMock.mockRestore();
44+
}
45+
}
46+
3547
describe("runAnalyze", () => {
36-
test("submits the src, polls until done, and prints only the map as JSON", async () => {
48+
test("posts the analysis model, polls until done, then prints the map fetched without a key", async () => {
3749
const { client, post, get } = fakeClient(
3850
{ id: "a", status: "queued" },
3951
{ id: "a", status: "processing" },
40-
{ id: "a", status: "done", result: steady },
52+
{ id: "a", status: "done", url: MAP_URL },
4153
);
42-
const { result, lines } = await capture(() => runAnalyze(client, "https://example.com/lit.mp3", "json", 0));
43-
expect(post).toHaveBeenCalledWith("/analysis", { src: "https://example.com/lit.mp3" });
44-
expect(get).toHaveBeenCalledWith("/analysis/a");
45-
expect(get).toHaveBeenCalledTimes(2);
46-
expect(lines).toEqual([JSON.stringify(steady)]);
47-
expect(result).toMatchObject({ exitCode: 0 });
54+
await withMapFetch(async (fetchMock) => {
55+
const { result, lines } = await capture(() => runAnalyze(client, "https://example.com/lit.mp3", "json", 0));
56+
expect(post).toHaveBeenCalledWith("/generate", body);
57+
expect(get).toHaveBeenCalledWith("/generate/a");
58+
expect(get).toHaveBeenCalledTimes(2);
59+
expect(fetchMock.mock.calls).toEqual([[MAP_URL]]);
60+
expect(lines).toEqual([JSON.stringify(steady)]);
61+
expect(result).toMatchObject({ exitCode: 0 });
62+
});
63+
});
64+
65+
test("a cached 200 done response fetches the map without polling", async () => {
66+
const { client, get } = fakeClient({ id: "a", status: "done", url: MAP_URL });
67+
await withMapFetch(async (fetchMock) => {
68+
const { lines } = await capture(() => runAnalyze(client, "https://example.com/lit.mp3", "json", 0));
69+
expect(get).not.toHaveBeenCalled();
70+
expect(fetchMock).toHaveBeenCalledTimes(1);
71+
expect(lines).toEqual([JSON.stringify(steady)]);
72+
});
4873
});
4974

5075
test("exits 1 with the API's error when the track can't be read", async () => {
@@ -56,6 +81,28 @@ describe("runAnalyze", () => {
5681
});
5782
});
5883

84+
describe("map fetch", () => {
85+
test("a non-2xx map response exits 1 with a clear message", async () => {
86+
const { client } = fakeClient({ id: "a", status: "done", url: MAP_URL });
87+
const fetchMock = spyOn(globalThis, "fetch").mockResolvedValue(new Response("nope", { status: 403 }));
88+
try {
89+
const { result, lines, errors } = await capture(() => runAnalyze(client, "https://example.com/a.mp3", "json", 0));
90+
expect(result).toMatchObject({ exitCode: 1 });
91+
expect(lines).toEqual([]);
92+
expect(errors).toEqual([`could not fetch the analysis map (403) from ${MAP_URL}`]);
93+
} finally {
94+
fetchMock.mockRestore();
95+
}
96+
});
97+
98+
test("a done job with no url exits 1 with a clear message", async () => {
99+
const { client } = fakeClient({ id: "a", status: "done" });
100+
const { result, errors } = await capture(() => runAnalyze(client, "https://example.com/a.mp3", "json", 0));
101+
expect(result).toMatchObject({ exitCode: 1 });
102+
expect(errors).toEqual(["analysis finished without a map URL"]);
103+
});
104+
});
105+
59106
describe("formatSummary", () => {
60107
test("describes a steady grid", () => {
61108
expect(formatSummary(steady)).toBe("120.01 BPM, 4/4, bar 2.00 s from 0.06 s, 111 bars, 3 drops, 7 sections");
@@ -66,15 +113,3 @@ describe("formatSummary", () => {
66113
expect(formatSummary(varies)).toBe("tempo varies (about 120 BPM): 822 beats, 227 downbeats, 2 drops, 9 sections");
67114
});
68115
});
69-
70-
describe("createClient", () => {
71-
test("sends no API key when it has none", async () => {
72-
const fetchMock = spyOn(globalThis, "fetch").mockResolvedValue(new Response("{}"));
73-
try {
74-
await createClient({ env: { name: "v1", baseUrl: "https://api.example.com" } }).get("/x");
75-
expect(fetchMock.mock.calls[0]![1]!.headers).not.toHaveProperty("x-api-key");
76-
} finally {
77-
fetchMock.mockRestore();
78-
}
79-
});
80-
});

0 commit comments

Comments
 (0)