> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Esportazioni

> Renderizza video karaoke nel cloud o in locale

Le esportazioni renderizzano un karaoke completato come file video. Usa `client.exports.create(...)` come punto di ingresso principale. Scegli `target: "local"` quando vuoi che l’SDK renderizzi 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"`.

```ts theme={null}
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 locale quando vuoi renderizzare direttamente sulla macchina del chiamante.

### Campi comuni

| Campo              | Tipo                                  | Descrizione                                                                                |
| ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `resolution`       | `"540p" \| "720p" \| "1080p" \| "4k"` | Risoluzione di output.                                                                     |
| `quality`          | `"low" \| "average" \| "high"`        | Qualità di codifica.                                                                       |
| `fps`              | `30 \| 60`                            | Fotogrammi al secondo. Il valore predefinito è `30`. Usa `60` per un movimento più fluido. |
| `playbackRate`     | `number`                              | Moltiplicatore di velocità (es. `0.9`).                                                    |
| `toneFrequency`    | `number`                              | Trasposizione dell’intonazione in semitoni.                                                |
| `transparent`      | `boolean`                             | Renderizza con uno sfondo trasparente.                                                     |
| `presetId`         | `string`                              | Applica un preset prima del rendering.                                                     |
| `stemVolumes`      | `Record<string, number>`              | Override del volume per stem, indicizzati per stem id.                                     |
| `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 crediti di `1.5x` a `60 fps`. Le esportazioni cloud trasparenti a 60 fps sono disponibili quando durata e risoluzione selezionate rientrano nei limiti cloud.

### Esempio con volumi degli stem

```ts theme={null}
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

```ts theme={null}
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](/en/render-settings-reference) per la forma completa di
`settingsOverride`.

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

Preventiva i crediti richiesti per un’esportazione cloud senza avviare l’esportazione.

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

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

Le esportazioni locali vengono eseguite sulla macchina del chiamante e non usano crediti di esportazione cloud,
quindi `quote(...)` vale solo per le esportazioni cloud.

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

Elenca le esportazioni per un progetto, con paginazione.

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

<ParamField path="page" type="number">
  Numero di pagina. Per impostazione predefinita è `1` sul server.
</ParamField>

<ParamField path="pageSize" type="number">
  Dimensione della pagina. Il valore predefinito è `100`. Massimo `100`.
</ParamField>

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

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

```ts theme={null}
const exported = await client.exports.get("exp_xyz");
```

## Esportazione locale

```ts theme={null}
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 renderizzare 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.

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

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

<Note>
  `client.exports.prepareLocal(...)` non avvia un render cloud. Non viene consumato
  alcun calcolo fatturabile lato Youka.
</Note>

## Attendere un’esportazione

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

```ts theme={null}
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 sia una directory sia un percorso completo del file, e `filename` è facoltativo:

```ts theme={null}
await client.exports.download(finalized, {
  output: "./exports",
});
```

## Cosa viene dopo

* [Tasks](/it/sdk/tasks) — handle delle operazioni e polling avanzato delle task
* [Presets](/it/sdk/presets) — configurazioni di rendering riutilizzabili
* [Project settings](/it/sdk/project-settings) — applica una patch alle impostazioni attive di un progetto