Projetos são o recurso de nível superior no Youka. Cada projeto contém seu arquivo de origem, stems separados, letras sincronizadas, exportações e configurações do projeto.
Criando um projeto
Na maioria dos casos, use client.projects.create() — ele cuida dos uploads para você.
const operation = await client.projects.create({
source: { type: "path", path: "./song.mp3" },
lyricsSource: { type: "transcribe" },
});
// => ProjectOperation
Tipos de source
Lê um arquivo do disco.source: {
type: "path",
path: "./song.mp3",
contentType: "audio/mpeg", // optional, inferred if omitted
}
Blob, File, ArrayBuffer ou Uint8Array em memória.source: {
type: "bytes",
data: fileBuffer,
filename: "song.mp3",
contentType: "audio/mpeg", // optional
}
URL HTTP ou HTTPS remota.As páginas hospedadas compatíveis dependem do yt-dlp. Veja a lista de URLs suportadas.source: {
type: "url",
url: "https://example.com/song.mp4",
maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}
maxVideoQuality controla a qualidade máxima de vídeo baixada para sources
do tipo URL. O padrão é 1080p. O SDK usa a melhor qualidade disponível até
esse limite e recorre ao melhor formato disponível se a plataforma não
disponibilizar um stream com limite. Use best para não impor limite.No Node.js e no Bun, o SDK garante automaticamente os binários de dependência
necessários para URL (ffmpeg, ffprobe, yt-dlp) no primeiro uso. O
equivalente na CLI é youka deps ensure --for url.
Outros campos
Título do projeto. O padrão é o nome do arquivo de origem.
Aplique um preset reutilizável no momento da criação.
Configure a sincronização de letras. Veja abaixo.
Sources de letras
// 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() também aceita um source inputFile de baixo nível quando você já tem um inputFileId enviado.
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",
});
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(...) aceita as mesmas formas de source que
client.projects.create(...), incluindo maxVideoQuality para URL. Se você já
souber a duração da mídia e não quiser enviar o arquivo apenas para estimar, passe
o formato REST de baixo nível:
const quote = await client.projects.quote({
durationSeconds: 210,
lyricsSource: null,
splitModel: "mdx23c",
});
client.uploads.create(body, options?)
Alocar um slot de upload e obter uma URL assinada.
const upload = await client.uploads.create({
filename: "song.mp3",
contentType: "audio/mpeg",
contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }
client.uploads.upload(uploadUrl, body, options?)
Faça PUT dos bytes do arquivo para a URL assinada.
await client.uploads.upload(upload.uploadUrl, fileBuffer, {
contentType: "audio/mpeg",
signal: abortController.signal,
});
Qualquer body compatível com fetch: Blob, File, ArrayBuffer, Uint8Array,
ReadableStream ou string.
YoukaRequestError com o código UPLOAD_FAILED se o upload retornar um status não-2xx.
client.projects.get(projectId, options?)
Buscar o estado completo do projeto, incluindo stems, letras e exportações.
const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);
client.projects.update(projectId, body, options?)
Aplique patch nos metadados do projeto.
const project = await client.projects.update("prj_abc123", {
title: "Updated title",
artists: ["Artist name"],
});
title ou artists.
client.projects.list(options?)
Liste todos os projetos pertencentes à conta autenticada.
const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));
getProject).
client.projects.delete(projectId, options?)
Exclua um projeto e todos os stems, letras e exportações associados.
await client.projects.delete("prj_abc123", {
idempotencyKey: "delete-prj_abc123",
});
A exclusão é permanente. Use junto uma chave de idempotência para que novas tentativas sejam seguras.
Próximos passos
- Stems — executar novamente a separação de stems
- Lyrics sync — sincronizar letras novamente
- Exports — renderizar vídeos finalizados
- Tasks — aguardar operações do projeto com
client.projects.wait
