Skip to content

Commit 7d8a519

Browse files
committed
feat: analyze tracks through /generate
1 parent 3529014 commit 7d8a519

5 files changed

Lines changed: 75 additions & 20 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: 12 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,17 +51,21 @@ 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+
const map = (await (await fetch(job.url!)).json()) as MusicMap;
68+
emit(format, map, `done ${formatSummary(map)}`);
6369
if (format !== "json") console.error("Print the full map with --output json.");
6470
return { response: job, exitCode: 0 };
6571
}

‎src/http/client.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ export class ApiError extends Error {
1717
}
1818

1919
export interface ClientOptions {
20-
// Absent for keyless endpoints such as /analysis.
20+
// Absent for endpoints that take no key.
2121
apiKey?: string;
2222
env: ResolvedEnv;
2323
}

‎tests/analyze.test.ts‎

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

55
const steady = {
@@ -32,19 +32,44 @@ async function capture(run: () => Promise<unknown>) {
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,30 @@ describe("runAnalyze", () => {
5681
});
5782
});
5883

84+
describe("analyze command", () => {
85+
test("sends the account's API key to /generate but not to the map URL", async () => {
86+
const saved = process.env.SHOTSTACK_API_KEY;
87+
process.env.SHOTSTACK_API_KEY = "test-key";
88+
const log = spyOn(console, "log").mockImplementation(() => {});
89+
const fetchMock = spyOn(globalThis, "fetch").mockImplementation(async (input) =>
90+
String(input).endsWith("/generate")
91+
? new Response(JSON.stringify({ id: "a", status: "done", url: MAP_URL }))
92+
: new Response(JSON.stringify(steady)),
93+
);
94+
try {
95+
await analyzeCommand.parseAsync(["node", "analyze", "https://example.com/a.mp3", "--output", "json"]);
96+
const [generate, map] = fetchMock.mock.calls;
97+
expect((generate![1]!.headers as Record<string, string>)["x-api-key"]).toBe("test-key");
98+
expect(map).toEqual([MAP_URL]);
99+
} finally {
100+
fetchMock.mockRestore();
101+
log.mockRestore();
102+
if (saved === undefined) delete process.env.SHOTSTACK_API_KEY;
103+
else process.env.SHOTSTACK_API_KEY = saved;
104+
}
105+
});
106+
});
107+
59108
describe("formatSummary", () => {
60109
test("describes a steady grid", () => {
61110
expect(formatSummary(steady)).toBe("120.01 BPM, 4/4, bar 2.00 s from 0.06 s, 111 bars, 3 drops, 7 sections");

0 commit comments

Comments
 (0)