Attività

Ogni operazione asincrona in Youka alla fine viene eseguita come un’attività, ma la superficie principale dell’SDK ora restituisce handle di operazione invece di ID attività grezzi. La maggior parte dei chiamanti dovrebbe usare client.projects.wait(...) o client.exports.wait(...) e ricorrere a client.tasks.* solo quando serve un’ispezione di basso livello delle attività.

`client.tasks.get(taskId, options?)`

Recupera lo stato corrente di un’attività tramite ID.

const task = await client.tasks.get("tsk_abc123");
console.log(task.status, task.type);

Stati dell’attività

Stato	Terminale?	Significato
`created`	No	L’attività è stata creata ma non è ancora in coda.
`queued`	No	L’attività è in attesa di essere eseguita.
`in-progress`	No	L’attività è attualmente in esecuzione.
`completed`	Sì	L’attività è terminata con successo.
`finalized`	Sì	L’attività è terminata e la post-elaborazione è completata.
`failed`	Sì	L’attività è fallita con un errore.
`cancelled`	Sì	L’attività è stata annullata.
`timed-out`	Sì	L’attività ha raggiunto il suo limite di tempo.

`client.tasks.wait(taskId, options?)`

Esegue il polling di un’attività finché non raggiunge uno stato terminale. Restituisce l’attività finale in caso di successo, genera YoukaTaskError in caso di errore.

const task = await client.tasks.wait("tsk_abc123", {
  pollIntervalMs: 3_000,
  signal: abortController.signal,
});

Opzioni

number

Millisecondi tra un polling e l’altro. Il valore predefinito è 2000.

AbortSignal

Annulla l’attesa. La richiesta in corso e qualsiasi ritardo in sospeso vengono annullati immediatamente.

Errori

client.tasks.wait(...) genera YoukaTaskError quando l’attività termina in failed, cancelled o timed-out:

import { YoukaTaskError } from "@youka/sdk";

try {
  await client.tasks.wait("tsk_abc123");
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error(error.code); // TASK_FAILED | TASK_CANCELLED | TASK_TIMED_OUT
    console.error(error.task); // Payload completo RestTask
  }
  throw error;
}

`client.projects.wait(operation, options?)`

Attende il completamento di un’operazione con ambito progetto, quindi recupera nuovamente il progetto. Restituisce l’handle dell’operazione, l’attività terminale e il progetto aggiornato.

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

const { project, task } = await client.projects.wait(operation, {
  pollIntervalMs: 2_500,
});

console.log("Project ready:", project.id);
console.log("Task finished in state:", task.status);

ProjectOperation

required

Di solito il risultato di client.projects.create(...), client.projects.separateStems(...) o client.projects.syncLyrics(...).

`client.exports.wait(operationOrId, options?)`

Attende che un’esportazione cloud raggiunga uno stato terminale. Passa l’ExportOperation restituito da client.exports.create(...) oppure una stringa exportId.

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

const finalized = await client.exports.wait(operation, {
  pollIntervalMs: 3_000,
});

console.log(finalized.status, finalized.url);

Annullamento

Passa un AbortSignal per annullare un’attesa di lunga durata:

const controller = new AbortController();

setTimeout(() => controller.abort(), 60_000);

try {
  await client.projects.wait(operation, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Wait cancelled after 60s");
  } else {
    throw error;
  }
}

Lo stesso segnale annulla anche la richiesta di polling sottostante dell’attività o dell’esportazione.

Cosa fare dopo

Errors — gestire YoukaTaskError ed errori ritentabili
Exports — attendere il completamento di un’esportazione
API async jobs — lo stesso pattern in HTTP grezzo

Overview

How To

Customization

Audio

Settings

Exporting

Account

`client.tasks.get(taskId, options?)`

Stati dell’attività

`client.tasks.wait(taskId, options?)`

Opzioni

Errori

`client.projects.wait(operation, options?)`

`client.exports.wait(operationOrId, options?)`

Annullamento

Cosa fare dopo

​client.tasks.get(taskId, options?)

​Stati dell’attività

​client.tasks.wait(taskId, options?)

​Opzioni

​Errori

​client.projects.wait(operation, options?)

​client.exports.wait(operationOrId, options?)

​Annullamento

​Cosa fare dopo

`client.tasks.get(taskId, options?)`

Stati dell’attività

`client.tasks.wait(taskId, options?)`

Opzioni

Errori

`client.projects.wait(operation, options?)`

`client.exports.wait(operationOrId, options?)`

Annullamento

Cosa fare dopo