disband 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +118 -2
- package/dist/api.d.ts +20 -0
- package/dist/api.js +56 -0
- package/dist/client.d.ts +24 -0
- package/dist/client.js +26 -0
- package/dist/create.d.ts +14 -0
- package/dist/create.js +50 -0
- package/dist/error.d.ts +10 -0
- package/dist/error.js +20 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.js +3 -0
- package/dist/key.d.ts +1 -0
- package/dist/key.js +8 -0
- package/dist/read.d.ts +4 -0
- package/dist/read.js +5 -0
- package/dist/separations.d.ts +23 -0
- package/dist/separations.js +50 -0
- package/dist/sleep.d.ts +1 -0
- package/dist/sleep.js +14 -0
- package/dist/types/audio.d.ts +1 -0
- package/dist/types/audio.js +1 -0
- package/dist/types/problem.d.ts +14 -0
- package/dist/types/problem.js +1 -0
- package/dist/types/separation.d.ts +58 -0
- package/dist/types/separation.js +1 -0
- package/dist/types/stem.d.ts +10 -0
- package/dist/types/stem.js +1 -0
- package/dist/types/usage.d.ts +19 -0
- package/dist/types/usage.js +1 -0
- package/dist/watch.d.ts +4 -0
- package/dist/watch.js +20 -0
- package/dist/webhook.d.ts +5 -0
- package/dist/webhook.js +32 -0
- package/package.json +52 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Disband
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,119 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://disband.io/favicon.svg" alt="" width="128">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">Disband</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
TypeScript SDK for the stem separation API at <a href="https://disband.io">disband.io</a>
|
|
9
|
+
<br><br>
|
|
10
|
+
<a href="https://www.npmjs.com/package/disband"><img src="https://img.shields.io/npm/v/disband?color=blue" alt="Version"></a>
|
|
11
|
+
<a href="LICENSE"><img src="https://img.shields.io/github/license/disbandio/disband-js?color=blue" alt="License"></a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
## Usage
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm install disband
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Create a key on [API keys](https://disband.io/app/keys) and set it as `DISBAND_KEY`.
|
|
21
|
+
|
|
22
|
+
## Examples
|
|
23
|
+
|
|
24
|
+
### Split a song
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { Disband } from "disband";
|
|
28
|
+
import { openAsBlob } from "node:fs";
|
|
29
|
+
import { writeFile } from "node:fs/promises";
|
|
30
|
+
|
|
31
|
+
// reads DISBAND_KEY
|
|
32
|
+
const disband = new Disband();
|
|
33
|
+
|
|
34
|
+
const song = await openAsBlob("song.mp3");
|
|
35
|
+
const { id } = await disband.separations.create(song, {
|
|
36
|
+
stems: ["vocals", "instrumental"],
|
|
37
|
+
formats: ["mp3"],
|
|
38
|
+
});
|
|
39
|
+
const separation = await disband.separations.wait(id);
|
|
40
|
+
if (separation.status === "failed") {
|
|
41
|
+
throw new Error(separation.problem.type);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
for (const [stem, files] of Object.entries(separation.stems)) {
|
|
45
|
+
// silent stems have no files
|
|
46
|
+
const mp3 = files?.mp3;
|
|
47
|
+
if (mp3 === undefined) continue;
|
|
48
|
+
|
|
49
|
+
const response = await disband.download(mp3);
|
|
50
|
+
if (response.body) {
|
|
51
|
+
await writeFile(`${stem}.mp3`, response.body);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Follow its progress
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
// 3, 2, 1, queued, processing, ready
|
|
60
|
+
for await (const state of disband.separations.watch(id)) {
|
|
61
|
+
console.log((state.status === "queued" && state.position) || state.status);
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### List recent separations
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
for await (const separation of disband.separations.list({ limit: 20 })) {
|
|
69
|
+
console.log(separation.id, separation.status);
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Handle errors
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { ApiError } from "disband";
|
|
77
|
+
|
|
78
|
+
try {
|
|
79
|
+
const { id } = await disband.separations.create(song, { stems: ["vocals"] });
|
|
80
|
+
const separation = await disband.separations.wait(id);
|
|
81
|
+
if (separation.status === "failed" && separation.problem.type === "bad-audio") {
|
|
82
|
+
console.log("The file couldn't be decoded");
|
|
83
|
+
}
|
|
84
|
+
} catch (error) {
|
|
85
|
+
if (!(error instanceof ApiError && error.type === "out-of-credits")) throw error;
|
|
86
|
+
console.log(error.problem?.detail);
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Receive a webhook
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { verifyWebhook } from "disband";
|
|
94
|
+
|
|
95
|
+
await disband.separations.create(song, {
|
|
96
|
+
stems: ["vocals"],
|
|
97
|
+
webhook: "https://example.com/disband",
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
// at https://example.com/disband
|
|
101
|
+
export default {
|
|
102
|
+
async fetch(request: Request, env: { DISBAND_WEBHOOK_SECRET: string }) {
|
|
103
|
+
const separation = await verifyWebhook(request, env.DISBAND_WEBHOOK_SECRET);
|
|
104
|
+
if (separation === undefined) return new Response(null, { status: 400 });
|
|
105
|
+
return new Response(null, { status: 204 });
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Requirements
|
|
111
|
+
|
|
112
|
+
- Node.js 22.12 or later
|
|
113
|
+
- Bun
|
|
114
|
+
- Deno
|
|
115
|
+
- Cloudflare Workers
|
|
116
|
+
|
|
117
|
+
## Docs
|
|
118
|
+
|
|
119
|
+
[disband.io/docs](https://disband.io/docs)
|
package/dist/api.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { Audio } from "./types/audio.ts";
|
|
2
|
+
export type RequestOptions = {
|
|
3
|
+
signal?: AbortSignal;
|
|
4
|
+
};
|
|
5
|
+
type Init = RequestOptions & {
|
|
6
|
+
method?: "POST" | "DELETE";
|
|
7
|
+
headers?: Record<string, string>;
|
|
8
|
+
body?: Audio;
|
|
9
|
+
};
|
|
10
|
+
export declare class Api {
|
|
11
|
+
#private;
|
|
12
|
+
constructor({ origin, key, retries }: {
|
|
13
|
+
origin: string;
|
|
14
|
+
key: string;
|
|
15
|
+
retries: number;
|
|
16
|
+
});
|
|
17
|
+
send(target: string, init?: Init): Promise<Response>;
|
|
18
|
+
json<T>(target: string, init?: Init): Promise<T>;
|
|
19
|
+
}
|
|
20
|
+
export {};
|
package/dist/api.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { errorOf } from "./error.js";
|
|
2
|
+
import { sleep } from "./sleep.js";
|
|
3
|
+
const backoff = (attempt) => 2 ** attempt * 1000;
|
|
4
|
+
export class Api {
|
|
5
|
+
#origin;
|
|
6
|
+
#key;
|
|
7
|
+
#retries;
|
|
8
|
+
constructor({ origin, key, retries }) {
|
|
9
|
+
this.#origin = new URL(origin).origin;
|
|
10
|
+
this.#key = key;
|
|
11
|
+
this.#retries = retries;
|
|
12
|
+
}
|
|
13
|
+
// an API path, or a file URL from a response
|
|
14
|
+
async send(target, init = {}) {
|
|
15
|
+
const url = new URL(target, this.#origin);
|
|
16
|
+
if (url.origin !== this.#origin)
|
|
17
|
+
throw new Error(`${url.origin} is not the API's origin`);
|
|
18
|
+
const headers = { ...init.headers, authorization: `Bearer ${this.#key}` };
|
|
19
|
+
// a create may already be charged, so only reads and deletes retry these errors
|
|
20
|
+
const repeatable = init.method !== "POST";
|
|
21
|
+
for (let attempt = 0;; attempt++) {
|
|
22
|
+
const last = attempt >= this.#retries;
|
|
23
|
+
let response;
|
|
24
|
+
try {
|
|
25
|
+
response = await fetch(url, { ...init, headers, redirect: "manual" });
|
|
26
|
+
}
|
|
27
|
+
catch (error) {
|
|
28
|
+
// sleep rejects on abort, which ends the retries
|
|
29
|
+
if (!repeatable || last)
|
|
30
|
+
throw error;
|
|
31
|
+
await sleep(backoff(attempt), init.signal);
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
if (response.ok)
|
|
35
|
+
return response;
|
|
36
|
+
const error = await errorOf(response);
|
|
37
|
+
if (last)
|
|
38
|
+
throw error;
|
|
39
|
+
// busy is returned before anything is created, so any method retries
|
|
40
|
+
if (error.type === "busy") {
|
|
41
|
+
await sleep(Number(response.headers.get("retry-after") ?? 1) * 1000, init.signal);
|
|
42
|
+
}
|
|
43
|
+
else if (repeatable && error.status >= 500) {
|
|
44
|
+
await sleep(backoff(attempt), init.signal);
|
|
45
|
+
}
|
|
46
|
+
else {
|
|
47
|
+
throw error;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
// not validated at run time, so a new field never breaks an older client
|
|
52
|
+
async json(target, init) {
|
|
53
|
+
const response = await this.send(target, init);
|
|
54
|
+
return (await response.json());
|
|
55
|
+
}
|
|
56
|
+
}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { StemFile } from "./types/separation.ts";
|
|
2
|
+
import { type RequestOptions } from "./api.ts";
|
|
3
|
+
import { Separations } from "./separations.ts";
|
|
4
|
+
import type { Catalog } from "./types/stem.ts";
|
|
5
|
+
import type { Usage } from "./types/usage.ts";
|
|
6
|
+
export type DisbandOptions = {
|
|
7
|
+
/** `DISBAND_KEY` from the environment when omitted. */
|
|
8
|
+
apiKey?: string;
|
|
9
|
+
/** `https://api.disband.io` when omitted. */
|
|
10
|
+
origin?: string;
|
|
11
|
+
/** Retries for busy responses, and for network and server errors on reads and deletes. */
|
|
12
|
+
maxRetries?: number;
|
|
13
|
+
};
|
|
14
|
+
export declare class Disband {
|
|
15
|
+
#private;
|
|
16
|
+
readonly separations: Separations;
|
|
17
|
+
constructor({ apiKey, origin, maxRetries }?: DisbandOptions);
|
|
18
|
+
/** Fetches a stem file with the API key. */
|
|
19
|
+
download(file: StemFile, options?: RequestOptions): Promise<Response>;
|
|
20
|
+
/** The stems a separation can request. */
|
|
21
|
+
catalog(options?: RequestOptions): Promise<Catalog>;
|
|
22
|
+
/** The account's credits and limits. */
|
|
23
|
+
usage(options?: RequestOptions): Promise<Usage>;
|
|
24
|
+
}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { Api } from "./api.js";
|
|
2
|
+
import { Separations } from "./separations.js";
|
|
3
|
+
import { keyOf } from "./key.js";
|
|
4
|
+
export class Disband {
|
|
5
|
+
separations;
|
|
6
|
+
#api;
|
|
7
|
+
constructor({ apiKey, origin = "https://api.disband.io", maxRetries = 3 } = {}) {
|
|
8
|
+
if (!Number.isInteger(maxRetries) || maxRetries < 0) {
|
|
9
|
+
throw new RangeError("maxRetries must be a whole number of 0 or more");
|
|
10
|
+
}
|
|
11
|
+
this.#api = new Api({ origin, key: keyOf(apiKey), retries: maxRetries });
|
|
12
|
+
this.separations = new Separations(this.#api);
|
|
13
|
+
}
|
|
14
|
+
/** Fetches a stem file with the API key. */
|
|
15
|
+
download(file, options = {}) {
|
|
16
|
+
return this.#api.send(file.url, options);
|
|
17
|
+
}
|
|
18
|
+
/** The stems a separation can request. */
|
|
19
|
+
catalog(options = {}) {
|
|
20
|
+
return this.#api.json("/v1/catalog", options);
|
|
21
|
+
}
|
|
22
|
+
/** The account's credits and limits. */
|
|
23
|
+
usage(options = {}) {
|
|
24
|
+
return this.#api.json("/v1/usage", options);
|
|
25
|
+
}
|
|
26
|
+
}
|
package/dist/create.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Separation } from "./types/separation.ts";
|
|
2
|
+
import type { Format, StemId } from "./types/stem.ts";
|
|
3
|
+
import type { Api, RequestOptions } from "./api.ts";
|
|
4
|
+
import type { Audio } from "./types/audio.ts";
|
|
5
|
+
export type CreateOptions = RequestOptions & {
|
|
6
|
+
stems: StemId[];
|
|
7
|
+
/** Both formats when omitted. */
|
|
8
|
+
formats?: Format[];
|
|
9
|
+
/** The File's name when omitted. */
|
|
10
|
+
name?: string;
|
|
11
|
+
/** An `https` URL the separation is posted to once it is `ready` or `failed`. */
|
|
12
|
+
webhook?: string;
|
|
13
|
+
};
|
|
14
|
+
export declare function create(api: Api, audio: Audio, { stems, formats, name, webhook, signal }: CreateOptions): Promise<Separation>;
|
package/dist/create.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { read, separationPath } from "./read.js";
|
|
2
|
+
import { errorOf } from "./error.js";
|
|
3
|
+
// the largest file sent as the request body
|
|
4
|
+
const bodyLimit = 100_000_000;
|
|
5
|
+
export async function create(api, audio, { stems, formats = [], name, webhook, signal }) {
|
|
6
|
+
const query = new URLSearchParams();
|
|
7
|
+
for (const stem of stems)
|
|
8
|
+
query.append("stems", stem);
|
|
9
|
+
for (const format of formats)
|
|
10
|
+
query.append("formats", format);
|
|
11
|
+
const named = name ?? nameOf(audio);
|
|
12
|
+
if (named !== undefined)
|
|
13
|
+
query.set("name", named);
|
|
14
|
+
// a header, as request logs record query strings and a webhook URL may carry a token
|
|
15
|
+
const headers = webhook === undefined ? {} : { "disband-webhook": webhook };
|
|
16
|
+
const bytes = audio instanceof Blob ? audio.size : audio.byteLength;
|
|
17
|
+
if (bytes <= bodyLimit) {
|
|
18
|
+
return api.json(`/v1/separations?${query}`, {
|
|
19
|
+
method: "POST",
|
|
20
|
+
headers: { ...headers, "content-type": "application/octet-stream" },
|
|
21
|
+
body: audio,
|
|
22
|
+
signal,
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
query.set("bytes", String(bytes));
|
|
26
|
+
const reserved = await api.json(`/v1/separations?${query}`, { method: "POST", headers, signal });
|
|
27
|
+
try {
|
|
28
|
+
// a presigned URL, so the key isn't sent
|
|
29
|
+
const upload = await fetch(reserved.upload_url, { method: "PUT", body: audio, signal });
|
|
30
|
+
if (!upload.ok)
|
|
31
|
+
throw await errorOf(upload);
|
|
32
|
+
}
|
|
33
|
+
catch (error) {
|
|
34
|
+
// an unused reservation counts as an upload until it expires
|
|
35
|
+
await api.send(separationPath(reserved.id), { method: "DELETE" }).catch(() => undefined);
|
|
36
|
+
throw error;
|
|
37
|
+
}
|
|
38
|
+
// the separation can still be uploading for a moment after the PUT
|
|
39
|
+
let state = await read(api, reserved.id, signal);
|
|
40
|
+
while (state.status === "uploading")
|
|
41
|
+
state = await read(api, reserved.id, signal, true);
|
|
42
|
+
return state;
|
|
43
|
+
}
|
|
44
|
+
// the API refuses an empty name or one over 255 characters
|
|
45
|
+
function nameOf(audio) {
|
|
46
|
+
if (!(audio instanceof File))
|
|
47
|
+
return undefined;
|
|
48
|
+
const name = audio.name.trim().slice(0, 255);
|
|
49
|
+
return name === "" ? undefined : name;
|
|
50
|
+
}
|
package/dist/error.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { Problem, ProblemType } from "./types/problem.ts";
|
|
2
|
+
/** An error response, with the API's problem details. `type` is undefined for a response without them. */
|
|
3
|
+
export declare class ApiError extends Error {
|
|
4
|
+
readonly status: number;
|
|
5
|
+
readonly problem?: Problem | undefined;
|
|
6
|
+
readonly name = "ApiError";
|
|
7
|
+
readonly type?: ProblemType;
|
|
8
|
+
constructor(status: number, problem?: Problem | undefined);
|
|
9
|
+
}
|
|
10
|
+
export declare function errorOf(response: Response): Promise<ApiError>;
|
package/dist/error.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** An error response, with the API's problem details. `type` is undefined for a response without them. */
|
|
2
|
+
export class ApiError extends Error {
|
|
3
|
+
status;
|
|
4
|
+
problem;
|
|
5
|
+
name = "ApiError";
|
|
6
|
+
type;
|
|
7
|
+
constructor(status, problem) {
|
|
8
|
+
super(problem === undefined ? `HTTP ${status}` : [problem.title, problem.detail].filter(Boolean).join(": "));
|
|
9
|
+
this.status = status;
|
|
10
|
+
this.problem = problem;
|
|
11
|
+
this.type = problem?.type;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
export async function errorOf(response) {
|
|
15
|
+
if (!response.headers.get("content-type")?.includes("application/problem+json")) {
|
|
16
|
+
await response.body?.cancel();
|
|
17
|
+
return new ApiError(response.status);
|
|
18
|
+
}
|
|
19
|
+
return new ApiError(response.status, (await response.json()));
|
|
20
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export type { Failed, Processing, Queued, Ready, Separation, StemFile, StemFiles, Uploading, } from "./types/separation.ts";
|
|
2
|
+
export type { Catalog, Format, Stem, StemId } from "./types/stem.ts";
|
|
3
|
+
export type { Failure, Problem, ProblemType } from "./types/problem.ts";
|
|
4
|
+
export type { Credits, Usage } from "./types/usage.ts";
|
|
5
|
+
export { Disband, type DisbandOptions } from "./client.ts";
|
|
6
|
+
export type { ListOptions, Separations } from "./separations.ts";
|
|
7
|
+
export type { CreateOptions } from "./create.ts";
|
|
8
|
+
export type { RequestOptions } from "./api.ts";
|
|
9
|
+
export type { Audio } from "./types/audio.ts";
|
|
10
|
+
export { ApiError } from "./error.ts";
|
|
11
|
+
export { verifyWebhook, webhookSecret } from "./webhook.ts";
|
package/dist/index.js
ADDED
package/dist/key.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function keyOf(apiKey: string | undefined): string;
|
package/dist/key.js
ADDED
package/dist/read.d.ts
ADDED
package/dist/read.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export const separationPath = (id) => `/v1/separations/${encodeURIComponent(id)}`;
|
|
2
|
+
// a held read returns once the separation changes, its place in line included, at most 60 s later
|
|
3
|
+
export function read(api, id, signal, held = false) {
|
|
4
|
+
return api.json(separationPath(id), { signal, headers: held ? { prefer: "wait=60" } : {} });
|
|
5
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { Failed, Ready, Separation } from "./types/separation.ts";
|
|
2
|
+
import { type CreateOptions } from "./create.ts";
|
|
3
|
+
import type { Api, RequestOptions } from "./api.ts";
|
|
4
|
+
import type { Audio } from "./types/audio.ts";
|
|
5
|
+
export type ListOptions = RequestOptions & {
|
|
6
|
+
/** The most separations to list. */
|
|
7
|
+
limit?: number;
|
|
8
|
+
};
|
|
9
|
+
export declare class Separations {
|
|
10
|
+
#private;
|
|
11
|
+
constructor(api: Api);
|
|
12
|
+
/** Resolves once the separation is queued, not when it is done. */
|
|
13
|
+
create(audio: Audio, options: CreateOptions): Promise<Separation>;
|
|
14
|
+
get(id: string, options?: RequestOptions): Promise<Separation>;
|
|
15
|
+
/** Newest first, fetching each page as the loop reaches it. */
|
|
16
|
+
list({ limit, ...options }?: ListOptions): AsyncGenerator<Separation>;
|
|
17
|
+
/** Cancels a running separation. A queued one's charge is returned. */
|
|
18
|
+
delete(id: string, options?: RequestOptions): Promise<void>;
|
|
19
|
+
/** Yields the current state, then each change of its status or place in line, until `ready` or `failed`. */
|
|
20
|
+
watch(id: string, options?: RequestOptions): AsyncGenerator<Separation>;
|
|
21
|
+
/** Resolves once the separation is `ready` or `failed`. */
|
|
22
|
+
wait(id: string, options?: RequestOptions): Promise<Ready | Failed>;
|
|
23
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { create } from "./create.js";
|
|
2
|
+
import { read, separationPath } from "./read.js";
|
|
3
|
+
import { wait, watch } from "./watch.js";
|
|
4
|
+
// the API's largest page and its default
|
|
5
|
+
const largestPage = 100;
|
|
6
|
+
export class Separations {
|
|
7
|
+
#api;
|
|
8
|
+
constructor(api) {
|
|
9
|
+
this.#api = api;
|
|
10
|
+
}
|
|
11
|
+
/** Resolves once the separation is queued, not when it is done. */
|
|
12
|
+
create(audio, options) {
|
|
13
|
+
return create(this.#api, audio, options);
|
|
14
|
+
}
|
|
15
|
+
get(id, options = {}) {
|
|
16
|
+
return read(this.#api, id, options.signal);
|
|
17
|
+
}
|
|
18
|
+
/** Newest first, fetching each page as the loop reaches it. */
|
|
19
|
+
async *list({ limit = Infinity, ...options } = {}) {
|
|
20
|
+
let left = limit;
|
|
21
|
+
let cursor;
|
|
22
|
+
while (left > 0) {
|
|
23
|
+
const query = new URLSearchParams();
|
|
24
|
+
if (cursor !== undefined)
|
|
25
|
+
query.set("cursor", cursor);
|
|
26
|
+
// a full page unless fewer are left, so a small limit costs a small page
|
|
27
|
+
if (left < largestPage)
|
|
28
|
+
query.set("limit", String(left));
|
|
29
|
+
const search = query.size > 0 ? `?${query}` : "";
|
|
30
|
+
const page = await this.#api.json(`/v1/separations${search}`, options);
|
|
31
|
+
yield* page.separations.slice(0, left);
|
|
32
|
+
left -= page.separations.length;
|
|
33
|
+
if (page.next === undefined)
|
|
34
|
+
return;
|
|
35
|
+
cursor = page.next;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
/** Cancels a running separation. A queued one's charge is returned. */
|
|
39
|
+
async delete(id, options = {}) {
|
|
40
|
+
await this.#api.send(separationPath(id), { method: "DELETE", signal: options.signal });
|
|
41
|
+
}
|
|
42
|
+
/** Yields the current state, then each change of its status or place in line, until `ready` or `failed`. */
|
|
43
|
+
watch(id, options) {
|
|
44
|
+
return watch(this.#api, id, options);
|
|
45
|
+
}
|
|
46
|
+
/** Resolves once the separation is `ready` or `failed`. */
|
|
47
|
+
wait(id, options) {
|
|
48
|
+
return wait(this.#api, id, options);
|
|
49
|
+
}
|
|
50
|
+
}
|
package/dist/sleep.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
|
package/dist/sleep.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export function sleep(ms, signal) {
|
|
2
|
+
return new Promise((resolve, reject) => {
|
|
3
|
+
signal?.throwIfAborted();
|
|
4
|
+
const abort = () => {
|
|
5
|
+
clearTimeout(timer);
|
|
6
|
+
reject(signal?.reason);
|
|
7
|
+
};
|
|
8
|
+
const timer = setTimeout(() => {
|
|
9
|
+
signal?.removeEventListener("abort", abort);
|
|
10
|
+
resolve();
|
|
11
|
+
}, ms);
|
|
12
|
+
signal?.addEventListener("abort", abort, { once: true });
|
|
13
|
+
});
|
|
14
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export type Audio = Blob | ArrayBuffer | Uint8Array<ArrayBuffer>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export type ProblemType = "invalid-request" | "unauthenticated" | "out-of-credits" | "account-suspended" | "account-locked" | "not-found" | "length-required" | "range-not-satisfiable" | "unsupported-audio" | "bad-audio" | "busy" | "internal" | "capacity" | "timeout" | (string & {});
|
|
2
|
+
/** RFC 9457 problem details. */
|
|
3
|
+
export type Problem = {
|
|
4
|
+
type: ProblemType;
|
|
5
|
+
title: string;
|
|
6
|
+
status: number;
|
|
7
|
+
detail?: string;
|
|
8
|
+
request_id: string;
|
|
9
|
+
errors?: {
|
|
10
|
+
path: string;
|
|
11
|
+
message: string;
|
|
12
|
+
}[];
|
|
13
|
+
};
|
|
14
|
+
export type Failure = Pick<Problem, "type" | "detail">;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { Format, StemId } from "./stem.ts";
|
|
2
|
+
import type { Failure } from "./problem.ts";
|
|
3
|
+
export type StemFile = {
|
|
4
|
+
url: string;
|
|
5
|
+
bytes: number;
|
|
6
|
+
};
|
|
7
|
+
/** `silent` when the stem has no audio, which then has no files. */
|
|
8
|
+
export type StemFiles = ({
|
|
9
|
+
silent?: never;
|
|
10
|
+
} & {
|
|
11
|
+
[F in Format]?: StemFile;
|
|
12
|
+
}) | ({
|
|
13
|
+
silent: true;
|
|
14
|
+
} & {
|
|
15
|
+
[F in Format]?: never;
|
|
16
|
+
});
|
|
17
|
+
type Common = {
|
|
18
|
+
id: string;
|
|
19
|
+
name?: string;
|
|
20
|
+
created_at: string;
|
|
21
|
+
expires_at: string;
|
|
22
|
+
};
|
|
23
|
+
export type Uploading = Common & {
|
|
24
|
+
status: "uploading";
|
|
25
|
+
upload_url: string;
|
|
26
|
+
};
|
|
27
|
+
export type Queued = Common & {
|
|
28
|
+
status: "queued";
|
|
29
|
+
charge?: number;
|
|
30
|
+
/** The place in line, 1 being next. Absent in `list`. */
|
|
31
|
+
position?: number;
|
|
32
|
+
};
|
|
33
|
+
export type Processing = Common & {
|
|
34
|
+
status: "processing";
|
|
35
|
+
charge: number;
|
|
36
|
+
};
|
|
37
|
+
export type Ready = Common & {
|
|
38
|
+
status: "ready";
|
|
39
|
+
charge: number;
|
|
40
|
+
/** In seconds. */
|
|
41
|
+
duration: number;
|
|
42
|
+
stems: {
|
|
43
|
+
[S in StemId]?: StemFiles;
|
|
44
|
+
};
|
|
45
|
+
};
|
|
46
|
+
export type Failed = Common & {
|
|
47
|
+
status: "failed";
|
|
48
|
+
charge: number;
|
|
49
|
+
problem: Failure;
|
|
50
|
+
};
|
|
51
|
+
export type Separation = Uploading | Queued | Processing | Ready | Failed;
|
|
52
|
+
export type SeparationPage = {
|
|
53
|
+
separations: Separation[];
|
|
54
|
+
/** Absent on the last page. */
|
|
55
|
+
next?: string;
|
|
56
|
+
};
|
|
57
|
+
export declare const ended: (separation: Separation) => separation is Ready | Failed;
|
|
58
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const ended = (separation) => separation.status === "ready" || separation.status === "failed";
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export type StemId = "vocals" | "vocals.lead" | "vocals.backing" | "instrumental" | "instrumental.drums" | "instrumental.drums.kick" | "instrumental.drums.snare" | "instrumental.drums.toms" | "instrumental.drums.hihat" | "instrumental.drums.cymbals" | "instrumental.drums.other" | "instrumental.bass" | "instrumental.guitar" | "instrumental.piano" | "instrumental.other" | (string & {});
|
|
2
|
+
export type Format = "wav" | "mp3";
|
|
3
|
+
export type Stem = {
|
|
4
|
+
id: StemId;
|
|
5
|
+
name: string;
|
|
6
|
+
parent: StemId | "mix";
|
|
7
|
+
};
|
|
8
|
+
export type Catalog = {
|
|
9
|
+
stems: Stem[];
|
|
10
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export type Credits = {
|
|
2
|
+
free: number;
|
|
3
|
+
bought: number;
|
|
4
|
+
};
|
|
5
|
+
export type Usage = {
|
|
6
|
+
balance: Credits;
|
|
7
|
+
limits: {
|
|
8
|
+
/** Free credits a day, absent while free use is paused. */
|
|
9
|
+
daily?: number;
|
|
10
|
+
/** The longest file, in seconds. */
|
|
11
|
+
seconds: number;
|
|
12
|
+
/** The largest file, in bytes. */
|
|
13
|
+
bytes: number;
|
|
14
|
+
/** Separations at once, absent when there is no limit. */
|
|
15
|
+
jobs?: number;
|
|
16
|
+
/** Uploads at once. */
|
|
17
|
+
uploads: number;
|
|
18
|
+
};
|
|
19
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/watch.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { type Failed, type Ready, type Separation } from "./types/separation.ts";
|
|
2
|
+
import type { Api, RequestOptions } from "./api.ts";
|
|
3
|
+
export declare function watch(api: Api, id: string, { signal }?: RequestOptions): AsyncGenerator<Separation>;
|
|
4
|
+
export declare function wait(api: Api, id: string, { signal }?: RequestOptions): Promise<Ready | Failed>;
|
package/dist/watch.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { ended } from "./types/separation.js";
|
|
2
|
+
import { read } from "./read.js";
|
|
3
|
+
// the place in line, which only a queued separation has
|
|
4
|
+
const placeOf = (separation) => (separation.status === "queued" ? separation.position : undefined);
|
|
5
|
+
export async function* watch(api, id, { signal } = {}) {
|
|
6
|
+
let state = await read(api, id, signal);
|
|
7
|
+
yield state;
|
|
8
|
+
while (!ended(state)) {
|
|
9
|
+
const next = await read(api, id, signal, true);
|
|
10
|
+
if (next.status !== state.status || placeOf(next) !== placeOf(state))
|
|
11
|
+
yield next;
|
|
12
|
+
state = next;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
export async function wait(api, id, { signal } = {}) {
|
|
16
|
+
let state = await read(api, id, signal);
|
|
17
|
+
while (!ended(state))
|
|
18
|
+
state = await read(api, id, signal, true);
|
|
19
|
+
return state;
|
|
20
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { Failed, Ready } from "./types/separation.ts";
|
|
2
|
+
/** The webhook secret of an API key, the same as when the key was created. */
|
|
3
|
+
export declare function webhookSecret(apiKey: string): Promise<string>;
|
|
4
|
+
/** The separation a webhook posted, or `undefined` when its signature or timestamp doesn't verify. */
|
|
5
|
+
export declare function verifyWebhook(request: Request, secret: string): Promise<Ready | Failed | undefined>;
|
package/dist/webhook.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// Standard Webhooks: HMAC-SHA256 over `id.timestamp.body`, a secret written as `whsec_` and its base64
|
|
2
|
+
const encoder = new TextEncoder();
|
|
3
|
+
const tolerance = 5 * 60;
|
|
4
|
+
const decode = (base64) => Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
|
|
5
|
+
const encode = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes)));
|
|
6
|
+
const hmac = (key) => crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
|
|
7
|
+
/** The webhook secret of an API key, the same as when the key was created. */
|
|
8
|
+
export async function webhookSecret(apiKey) {
|
|
9
|
+
const mac = await crypto.subtle.sign("HMAC", await hmac(encoder.encode(apiKey)), encoder.encode("disband webhooks"));
|
|
10
|
+
return `whsec_${encode(mac)}`;
|
|
11
|
+
}
|
|
12
|
+
/** The separation a webhook posted, or `undefined` when its signature or timestamp doesn't verify. */
|
|
13
|
+
export async function verifyWebhook(request, secret) {
|
|
14
|
+
const id = request.headers.get("webhook-id");
|
|
15
|
+
const timestamp = request.headers.get("webhook-timestamp");
|
|
16
|
+
const signatures = request.headers.get("webhook-signature");
|
|
17
|
+
if (id === null || timestamp === null || signatures === null)
|
|
18
|
+
return undefined;
|
|
19
|
+
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerance)
|
|
20
|
+
return undefined;
|
|
21
|
+
const body = await request.text();
|
|
22
|
+
// with or without its prefix, as Standard Webhooks libraries take it
|
|
23
|
+
const key = await hmac(decode(secret.replace(/^whsec_/, "")));
|
|
24
|
+
const content = encoder.encode(`${id}.${timestamp}.${body}`);
|
|
25
|
+
for (const entry of signatures.split(" ")) {
|
|
26
|
+
const [version, mac] = entry.split(",");
|
|
27
|
+
if (version === "v1" && mac !== undefined && (await crypto.subtle.verify("HMAC", key, decode(mac), content))) {
|
|
28
|
+
return JSON.parse(body);
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
return undefined;
|
|
32
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,53 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "disband",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "TypeScript client for the Disband stem separation API",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"homepage": "https://disband.io/docs",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/disbandio/disband-js.git"
|
|
11
|
+
},
|
|
12
|
+
"keywords": [
|
|
13
|
+
"stem separation",
|
|
14
|
+
"vocal remover",
|
|
15
|
+
"audio",
|
|
16
|
+
"music",
|
|
17
|
+
"api"
|
|
18
|
+
],
|
|
19
|
+
"exports": {
|
|
20
|
+
".": {
|
|
21
|
+
"types": "./dist/index.d.ts",
|
|
22
|
+
"default": "./dist/index.js"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
"files": [
|
|
26
|
+
"dist"
|
|
27
|
+
],
|
|
28
|
+
"sideEffects": false,
|
|
29
|
+
"engines": {
|
|
30
|
+
"node": ">=22.12"
|
|
31
|
+
},
|
|
32
|
+
"packageManager": "pnpm@11.4.0",
|
|
33
|
+
"scripts": {
|
|
34
|
+
"build": "rm -rf dist && tsc -p tsconfig.build.json",
|
|
35
|
+
"prepack": "pnpm build",
|
|
36
|
+
"check": "tsc",
|
|
37
|
+
"test": "vitest run",
|
|
38
|
+
"lint": "eslint .",
|
|
39
|
+
"format": "eslint --fix . && prettier --write ."
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@eslint/js": "^10.0.1",
|
|
43
|
+
"@types/node": "^24.19.2",
|
|
44
|
+
"eslint": "^10.15.0",
|
|
45
|
+
"eslint-config-prettier": "^10.1.8",
|
|
46
|
+
"eslint-plugin-perfectionist": "^5.13.0",
|
|
47
|
+
"prettier": "^3.10.1",
|
|
48
|
+
"standardwebhooks": "^1.1.1",
|
|
49
|
+
"typescript": "^6.0.3",
|
|
50
|
+
"typescript-eslint": "^8.72.2",
|
|
51
|
+
"vitest": "^4.1.12"
|
|
52
|
+
}
|
|
53
|
+
}
|