Esportazioni

Le esportazioni eseguono il rendering di un video karaoke o lyric a partire da un progetto. Usa client.exports.create(...) come punto di ingresso principale. Scegli target: "local" quando vuoi che l’SDK esegua il rendering direttamente sulla macchina corrente; altrimenti l’esportazione cloud è l’impostazione predefinita.

`client.exports.create(projectId, input, options?)`

Scegli la destinazione di esportazione con target: "cloud" | "local".

const cloud = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});
// => ExportOperation

const local = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
});
// => { outputPath, fileSize, duration, ... }

Usa il cloud quando vuoi un’esportazione asincrona gestita. Usa il local quando vuoi eseguire il rendering direttamente sulla macchina del chiamante.

Campi comuni

Campo	Tipo	Descrizione
`versionId`	`string`	Versione del progetto. Per impostazione predefinita usa la versione principale.
`resolution`	`"540p" \| "720p" \| "1080p" \| "4k"`	Risoluzione di output.
`quality`	`"low" \| "average" \| "high"`	Qualità di codifica.
`fps`	`25 \| 30 \| 60`	Frame al secondo. Predefinito `30`. Usa `60` per un movimento più fluido.
`playbackRate`	`number`	Moltiplicatore di velocità (ad es. `0.9`).
`toneFrequency`	`number`	Trasposizione dell’intonazione in semitoni.
`transparent`	`boolean`	Esegui il rendering con sfondo trasparente.
`presetId`	`string`	Applica un preset prima del rendering.
`stemVolumes`	`Record<string, number>`	Override del volume per stem, indicizzati per id dello stem.
`settingsOverride`	`object`	Applica una patch alle impostazioni del progetto solo per questa esportazione.

Usa fps: 60 per un movimento più fluido. I preventivi cloud applicano un moltiplicatore di crediti 1.5x a 60 fps. Le esportazioni cloud trasparenti a 60 fps sono disponibili quando durata e risoluzione selezionate rientrano nei limiti del cloud.

Esempio con volumi degli stem

const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  stemVolumes: {
    vocals: 0,
    instrumental: 1,
    backing: 0.5,
  },
});

Esempio con override delle impostazioni

const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  settingsOverride: {
    trim: { startSeconds: 5, endSeconds: 180 },
    style: {
      background: { type: "color", color: "#101010" },
    },
  },
});

Vedi Render settings reference per la shape completa di settingsOverride.

`client.exports.quote(projectId, input, options?)`

Calcola il preventivo dei crediti necessari per un’esportazione cloud senza avviare l’esportazione.

const quote = await client.exports.quote("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  transparent: false,
});

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

Le esportazioni locali girano sulla macchina del chiamante e non usano crediti di esportazione cloud, quindi quote(...) è solo per le esportazioni cloud.

`client.exports.list(projectId, input?, options?)`

Elenca le esportazioni di un progetto, con paginazione.

const exports = await client.exports.list("prj_abc123", {
  page: 1,
  pageSize: 50,
});

number

Numero di pagina. Predefinito 1 sul server.

number

Dimensione della pagina. Predefinita 100. Massimo 100.

`client.exports.get(exportId, options?)`

Recupera un’esportazione solo tramite ID, senza conoscere il progetto padre.

const exported = await client.exports.get("exp_xyz");

Esportazione locale

const result = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
  onProgress(progress) {
    console.log(progress.stage, progress.percent);
  },
});

console.log(result.outputPath);

Usa onDependencyProgress se vuoi aggiornamenti mentre la toolchain di rendering locale viene installata o verificata.

`client.exports.prepareLocal(projectId, body, options?)`

Restituisce il payload preparato necessario per eseguire il rendering di un’esportazione in locale. Usalo quando integri con @youka/remotion o un altro renderer locale. Il server restituisce gli input della composizione, gli URL degli asset e i parametri di rendering senza mettere in coda un render cloud.

const payload = await client.exports.prepareLocal("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});

// Hand payload off to your local renderer
await renderLocally(payload);

client.exports.prepareLocal(...) non avvia un render cloud. Non viene consumato alcun compute fatturabile lato Youka.

Attendere un’esportazione

Le esportazioni cloud sono asincrone. Usa client.exports.wait(...):

const operation = await client.exports.create("prj_abc123", {
  resolution: "1080p",
});

const finalized = await client.exports.wait(operation, {
  pollIntervalMs: 3_000,
});
console.log("Download from", finalized.url);

Scaricare il risultato

Le esportazioni cloud terminano con un url firmato. Usa l’helper integrato per fare streaming del file su disco. output può essere una directory o un percorso file completo, e filename è opzionale:

await client.exports.download(finalized, {
  output: "./exports",
});

Cosa fare dopo

Tasks — handle delle operazioni e polling avanzato delle task
Presets — configurazioni di rendering riutilizzabili
Project settings — applica una patch alle impostazioni attive di un progetto

Snapshot di versione e timing

Elenca le versioni con client.projects.versions.list(projectId). Passa versionId a exports.create, exports.quote o exports.prepareLocal. Lo styling appartiene a quella versione, mentre l’allineamento selezionato appartiene al progetto. Gli handle delle operazioni di esportazione cloud e i payload locali includono versionId, alignmentId e alignmentRevision. Questi campi identificano lo stesso snapshot di timing usato per costruire la composizione. Una preparazione o un’esportazione successiva potrebbe vedere modifiche più recenti. Salva il payload preparato se un renderer esterno deve usare esattamente quello snapshot, e aggiorna gli URL firmati dei media scaduti. Per silenziare ogni stem, costruisci stemVolumes a partire dagli stem ID del progetto impostando ogni valore a zero. L’esportazione locale trasparente usa ProRes 4444 in un contenitore MOV. Un output silenzioso potrebbe comunque avere uno stream audio. Vedi Automate lyric videos per l’esempio completo di esportazione.

Overview

How To

Customization

Audio

Settings

Exporting

Account

`client.exports.create(projectId, input, options?)`

Campi comuni

Esempio con volumi degli stem

Esempio con override delle impostazioni

`client.exports.quote(projectId, input, options?)`

`client.exports.list(projectId, input?, options?)`

`client.exports.get(exportId, options?)`

Esportazione locale

`client.exports.prepareLocal(projectId, body, options?)`

Attendere un’esportazione

Scaricare il risultato

Cosa fare dopo

Snapshot di versione e timing

​client.exports.create(projectId, input, options?)

​Campi comuni

​Esempio con volumi degli stem

​Esempio con override delle impostazioni

​client.exports.quote(projectId, input, options?)

​client.exports.list(projectId, input?, options?)

​client.exports.get(exportId, options?)

​Esportazione locale

​client.exports.prepareLocal(projectId, body, options?)

​Attendere un’esportazione

​Scaricare il risultato

​Cosa fare dopo

​Snapshot di versione e timing

`client.exports.create(projectId, input, options?)`

Campi comuni

Esempio con volumi degli stem

Esempio con override delle impostazioni

`client.exports.quote(projectId, input, options?)`

`client.exports.list(projectId, input?, options?)`

`client.exports.get(exportId, options?)`

Esportazione locale

`client.exports.prepareLocal(projectId, body, options?)`

Attendere un’esportazione

Scaricare il risultato

Cosa fare dopo

Snapshot di versione e timing