This package bundles an SDK to allow basic usage of the Music.AI API.
Here's how you can easily create a job, wait for its completion, process it against the music-ai/generate-chords workflow, and then delete it:
import MusicAi from "@music.ai/sdk"
const musicAi = new MusicAi({ apiKey: process.env.MUSIC_AI_API_KEY })
const songUrl = await musicAi.uploadFile("./song.mp3")
const jobId = await musicAi.addJob({
name: "My first job",
workflow: "music-ai/generate-chords",
params: {
inputUrl: songUrl,
}
})
const job = await musicAi.waitForJobCompletion(jobId)
if (job.status === "SUCCEEDED") {
const files = await musicAi.downloadJobResults(job, "./chords")
console.log("Result:", files)
} else {
console.log("Job failed!")
}
await musicAi.deleteJob(jobId)npm i @musicai/sdk --savetype Status = "QUEUED" | "STARTED" | "SUCCEEDED" | "FAILED"
interface Job {
id: string
app: string
workflow: string
status: Status
batchName: string | null
workflowParams: {
inputUrl: string
[key: string]: string
}
metadata: {
[key: string]: string
}
result: {
[key: string]: string
}
name: string
createdAt: string
startedAt: string
completedAt: string | null
}
interface Workflow {
id: string
name: string
slug: string
description: string
createdAt: string
updatedAt: string
}Uploads a local file to our temporary file server. Returns an temporary download url you can use on other methods.
uploadFile(fileLocation: string): Promise<string>const downloadUrl = await musicAi.uploadFile(fileLocation)Creates a new job and returns its corresponding ID.
addJob(
name: string,
workflow: string,
workflowParams: Record<string, unknown>,
options?: {
copyResultsTo: Record<string, unknown>,
metadata: Record<string, unknown>
}
): Promise<string>const songUrl = "https://your-website.com/song.mp3"
const jobId = await musicAi.addJob("job-1", "music-ai/isolate-drums", {
inputUrl: songUrl,
})Check the documentation for all the existing workflows and expected correspondent parameters.
You can optionally store outputs in your own storage by providing upload URLs. To do that, use the copyResultsTo option, defining one upload URL for each output of the workflow.
await musicAi.addJob(
"job-1",
"music-ai/isolate-drums",
{
inputUrl: songUrl,
},
{
copyResultsTo: {
"Kick drum": "https://example.com/my-upload-url-1",
"Snare drum": "https://example.com/my-upload-url-2"
}
}
)The example above uses the music-ai/isolate-drums workflow, which has 3 outputs, Kick drum, Snare drum, and Other. We have provided upload URLs for the first two. Since we haven't provided a URL for the third output, it will be stored in Music AI's storage, as usual.
The JSON below contains the data for the job created above. Note that we don't provide download URLs for the outputs directed to your custom storage.
{
// ...
"result": {
"Kick drum": "[custom storage]",
"Snare drum": "[custom storage]",
"Other": "https://cdn.music.ai/example/vocals.wav"
}
}Gets a job information by its id.
getJob(id: string): Promise<Job>const job = await musicAi.getJob(/* jobId */)The job variable value:
{
"id": "2e35babc-91c4-4121-89f4-5a2acf956b28",
"app": "Your app name",
"workflow": {
"id": "2ae5eea3-63dd-445e-9a3f-ff0473e82fd2",
"name": "Stems Isolations - Vocals & accompaniments"
},
"status": "SUCCEEDED",
"batchName": null,
"workflowParams": {
"inputUrl": "https://your-server.com/audio-input.m4a"
},
"metadata": {},
"result": {
"vocals": "https://cdn.music.ai/example/vocals.wav",
"accompaniments": "https://cdn.music.ai/example/accompaniments.wav"
},
"name": "My job 123",
"createdAt": "2022-12-07T19:21:42.170Z",
"startedAt": "2022-12-07T19:21:42.307Z",
"completedAt": "2022-12-07T19:22:00.325Z"
}Return all existing jobs associated with the provided apiKey. You can optionally filter by status and workflow:
listJobs(filters?: { status?: Status[]; workflow?: string[] }): Promise<Job[]>const jobs = await musicAi.listJobs()const jobs = await musicAi.listJobs({
status: ["FAILED"],
workflow: ["workflow-a", "workflow-b"],
})Delete a job by its id.
deleteJob(id: string): Promise<void>Waits until the job status is either SUCCEEDED or FAILED, and returns its information.
waitForJobCompletion(id: string): Promise<Job>const job = await musicAi.waitForJobCompletion(/* jobId */)
if (job.status === "SUCCEEDED") {
console.log("Job succeeded!")
} else {
console.log("Job failed!")
}Download all the job results to a local folder.
downloadJobResults(jobIdOrJobData: string | Job, outputFolder: string): Promise<{ [key: string]: string }>This function also creates a file called workflow.result.json containing the result in the JSON format. When an output is a file, that field will contain the relative path to the file.
const resultPaths = await musicAi.downloadJobResults(/* jobId */, "./stems")Or, if you already have the job object...
const job = await musicAi.waitForJobCompletion(/* jobId */)
const resultPaths = await musicAi.downloadJobResults(job, "./stems")If the workflows has two outputs, vocals in WAVE format and bpm, two files will be created at the given folder: vocals.wav and workflow.result.json.
// workflow.result.json
{
"vocals": "./vocals.wav",
"bpm": "64"
}Retrieves a paginated list of the existing workflows from the provided apiKey. You can optionally filter by page (defaults to 0) and size (defaults to 100):
listWorkflows(filters?: { page?: number; size?: number }): Promise<Workflow[]>const workflows = await musicAi.listWorkflows()const workflows = await musicAi.listWorkflows({
page: 1,
size: 20,
})