I progetti sono la risorsa di livello più alto in Youka. Ogni progetto possiede il suo file sorgente, le tracce separate, i testi sincronizzati, le esportazioni e le impostazioni del progetto.
Creare un progetto
Nella maggior parte dei casi, usa client.projects.create() — gestisce i caricamenti al posto tuo.
const operation = await client.projects.create({
source: { type: "path", path: "./song.mp3" },
lyricsSource: { type: "transcribe" },
});
// => ProjectOperation
Tipi di sorgente
Legge un file dal disco.source: {
type: "path",
path: "./song.mp3",
contentType: "audio/mpeg", // optional, inferred if omitted
}
Blob, File, ArrayBuffer o Uint8Array in memoria.source: {
type: "bytes",
data: fileBuffer,
filename: "song.mp3",
contentType: "audio/mpeg", // optional
}
URL HTTP o HTTPS remoto.Le pagine ospitate supportate dipendono da yt-dlp. Vedi la lista degli URL supportati.source: {
type: "url",
url: "https://example.com/song.mp4",
maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}
maxVideoQuality controlla la qualità video massima scaricata per le sorgenti
URL. Il valore predefinito è 1080p. L’SDK usa la migliore qualità disponibile
entro quel limite e ripiega sul miglior formato disponibile se la piattaforma
non espone uno stream con limite. Usa best per nessun limite.Su Node.js e Bun, l’SDK assicura automaticamente i binari di dipendenza URL
richiesti (ffmpeg, ffprobe, yt-dlp) al primo utilizzo. L’equivalente
nella CLI è youka deps ensure --for url.
Altri campi
Titolo del progetto. Per impostazione predefinita è il nome del file sorgente.
Applica un preset riutilizzabile al momento della creazione.
Configura la sincronizzazione dei testi. Vedi sotto.
Sorgenti dei testi
// 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() accetta anche una sorgente inputFile di basso livello quando hai già un inputFileId caricato.
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(...) accetta le stesse forme di source di
client.projects.create(...), incluso maxVideoQuality per gli URL. Se conosci già
la durata del contenuto multimediale e non vuoi caricare il file solo per ottenere una stima, passa
la forma REST di basso livello:
const quote = await client.projects.quote({
durationSeconds: 210,
lyricsSource: null,
splitModel: "mdx23c",
});
client.uploads.create(body, options?)
Alloca uno slot di caricamento e ottieni un URL firmato.
const upload = await client.uploads.create({
filename: "song.mp3",
contentType: "audio/mpeg",
contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }
client.uploads.upload(uploadUrl, body, options?)
Esegui una PUT dei byte del file sull’URL firmato.
await client.uploads.upload(upload.uploadUrl, fileBuffer, {
contentType: "audio/mpeg",
signal: abortController.signal,
});
Qualsiasi body compatibile con fetch: Blob, File, ArrayBuffer, Uint8Array,
ReadableStream o string.
YoukaRequestError con codice UPLOAD_FAILED se il caricamento restituisce uno status non 2xx.
client.projects.get(projectId, options?)
Recupera lo stato completo del progetto, incluse tracce, testi ed esportazioni.
const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);
client.projects.update(projectId, body, options?)
Applica una patch ai metadati del progetto.
const project = await client.projects.update("prj_abc123", {
title: "Updated title",
artists: ["Artist name"],
});
title o artists.
client.projects.list(options?)
Elenca tutti i progetti di proprietà dell’account autenticato.
const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));
getProject).
client.projects.delete(projectId, options?)
Elimina un progetto e tutte le tracce, i testi e le esportazioni associati.
await client.projects.delete("prj_abc123", {
idempotencyKey: "delete-prj_abc123",
});
L’eliminazione è permanente. Abbinala a una chiave di idempotenza così i tentativi ripetuti sono sicuri.
Cosa viene dopo
- Stems — riesegui la separazione delle tracce
- Lyrics sync — risincronizza i testi
- Exports — renderizza i video finali
- Tasks — attendi le operazioni del progetto con
client.projects.wait
