Projects - Youka Docs

Projects are the top-level resource in Youka. Each project owns its source file, lyrics, exports, and project settings. Karaoke projects also contain separated stems.

Creating a project

For most cases, use client.projects.create() — it handles uploads for you.

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation

Source types

path
bytes
url

Reads a file from disk.

source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

In-memory Blob, File, ArrayBuffer, or Uint8Array.

source: {
  type: "bytes",
  data: fileBuffer,
  filename: "song.mp3",
  contentType: "audio/mpeg", // optional
}

Remote HTTP or HTTPS URL.Supported hosted pages depend on yt-dlp. See the supported URLs list.

source: {
  type: "url",
  url: "https://example.com/song.mp4",
  maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}

maxVideoQuality controls the maximum downloaded video quality for URL sources. It defaults to 1080p. The SDK uses the best available quality up to that limit, and falls back to the best available format if the platform does not expose a capped stream. Use best for no cap.

On Node.js and Bun, the SDK automatically ensures the required URL dependency binaries (ffmpeg, ffprobe, yt-dlp) on first use. The CLI equivalent is youka deps ensure --for url.

Other fields

string

Project title. Defaults to the source filename.

karaoke | lyric-video

Workflow. Defaults to karaoke. lyric-video uses the original audio without stem separation.

SplitModel

Stem separation model for karaoke. Defaults to mdx23c. Rejected for lyric-video. See Split model reference.

string

Apply a reusable preset at creation time.

LyricsSource

Configure lyrics sync. See below.

Lyrics sources

// Transcribe lyrics from the audio
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// Align exact lyrics to the audio
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

`client.projects.create(input, options?)`

client.projects.create() also accepts a low-level inputFile source when you already have an uploaded inputFileId.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: buffer.byteLength,
});

await client.uploads.upload(upload.uploadUrl, buffer, {
  contentType: "audio/mpeg",
});

const operation = await client.projects.create({
  source: {
    type: "inputFile",
    inputFileId: upload.inputFileId,
    filename: "song.mp3",
  },
  title: "My Song",
});

`client.projects.quote(input, options?)`

Quote the credits required to create a project without creating it.

const quote = await client.projects.quote({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe", language: "en" },
  splitModel: "mdx23c",
});

console.log(quote.creditsRequired, quote.sufficientBalance);

client.projects.quote(...) accepts the same source forms as client.projects.create(...), including URL maxVideoQuality. If you already know the media duration and do not want to upload the file just to quote, pass the low-level REST shape:

const quote = await client.projects.quote({
  durationSeconds: 210,
  lyricsSource: null,
  splitModel: "mdx23c",
});

`client.uploads.create(body, options?)`

Allocate an upload slot and get a signed URL.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }

`client.uploads.upload(uploadUrl, body, options?)`

PUT the file bytes to the signed URL.

await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});

FetchBody

required

Any fetch-compatible body: Blob, File, ArrayBuffer, Uint8Array, ReadableStream, or string.

Throws YoukaRequestError with code UPLOAD_FAILED if the upload returns a non-2xx status.

`client.projects.get(projectId, options?)`

Fetch the full project state, including stems, lyrics, and exports.

const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);

`client.projects.update(projectId, body, options?)`

Patch project metadata.

const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});

Pass at least one of title or artists.

`client.projects.list(options?)`

List every project owned by the authenticated account.

const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));

Returns an array of project list items (a leaner shape than getProject).

`client.projects.delete(projectId, options?)`

Delete a project and all its associated stems, lyrics, and exports.

await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});

Deletion is permanent. Pair with an idempotency key so retries are safe.

What’s next

Stems — re-run stem separation
Lyrics sync — re-sync lyrics
Exports — render finished videos
Tasks — wait on project operations with client.projects.wait

Lyric-video creation and model discovery

const capabilities = await client.capabilities.get();
const operation = await client.projects.create({
  kind: "lyric-video",
  source: { type: "path", path: "./song.wav" },
  lyricsSource: {
    type: "transcribe",
    syncModel: "elevenlabs-transcription",
    lyrics: "Optional reference lyrics",
  },
});
const { project } = await client.projects.wait(operation);
const versions = await client.projects.versions.list(project.id);

The same kind and lyric-processing choices work with projects.quote. Lyric-video quotes charge zero separation credits. Quote and create validate the same model, language, account, and source requirements. Quotes do not reserve credits or capacity. Use lyricsSource: null to skip lyric processing. Reference text in transcription is guidance and may differ from the result. Models that need isolated vocals cannot process a no-separation lyric video. See Automate lyric videos for capabilities, exact timing updates, and catalogue checkpoints.

​Creating a project

​Source types

​Other fields

​Lyrics sources

​client.projects.create(input, options?)

​client.projects.quote(input, options?)

​client.uploads.create(body, options?)

​client.uploads.upload(uploadUrl, body, options?)

​client.projects.get(projectId, options?)

​client.projects.update(projectId, body, options?)

​client.projects.list(options?)

​client.projects.delete(projectId, options?)

​What’s next

​Lyric-video creation and model discovery

Creating a project

Source types

Other fields

Lyrics sources

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

What’s next

Lyric-video creation and model discovery