> ## 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.

# Projects

> Carica contenuti multimediali e crea, ispeziona, elenca ed elimina progetti karaoke

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.

```ts theme={null}
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation
```

### Tipi di sorgente

<Tabs>
  <Tab title="path">
    Legge un file dal disco.

    ```ts theme={null}
    source: {
      type: "path",
      path: "./song.mp3",
      contentType: "audio/mpeg", // optional, inferred if omitted
    }
    ```
  </Tab>

  <Tab title="bytes">
    `Blob`, `File`, `ArrayBuffer` o `Uint8Array` in memoria.

    ```ts theme={null}
    source: {
      type: "bytes",
      data: fileBuffer,
      filename: "song.mp3",
      contentType: "audio/mpeg", // optional
    }
    ```
  </Tab>

  <Tab title="url">
    URL HTTP o HTTPS remoto.

    Le pagine ospitate supportate dipendono da yt-dlp. Vedi la [lista degli URL supportati](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).

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

    <Note>
      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`.
    </Note>
  </Tab>
</Tabs>

### Altri campi

<ParamField path="title" type="string">
  Titolo del progetto. Per impostazione predefinita è il nome del file sorgente.
</ParamField>

<ParamField path="splitModel" type="SplitModel">
  Modello di separazione delle tracce. Il valore predefinito è `mdx23c`. Vedi il [riferimento del modello di split](/it/desktop/split-model).
</ParamField>

<ParamField path="presetId" type="string">
  Applica un preset riutilizzabile al momento della creazione.
</ParamField>

<ParamField path="lyricsSource" type="LyricsSource">
  Configura la sincronizzazione dei testi. Vedi sotto.
</ParamField>

### Sorgenti dei testi

```ts theme={null}
// 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(input, options?)`

`client.projects.create()` accetta anche una sorgente `inputFile` di basso livello quando hai già un `inputFileId` caricato.

```ts theme={null}
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",
});
```

## `client.projects.quote(input, options?)`

Stima i crediti necessari per creare un progetto senza crearlo.

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

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

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

```ts theme={null}
await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});
```

<ParamField path="body" type="FetchBody" required>
  Qualsiasi body compatibile con `fetch`: `Blob`, `File`, `ArrayBuffer`, `Uint8Array`,
  `ReadableStream` o `string`.
</ParamField>

Genera `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.

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

```ts theme={null}
const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});
```

Passa almeno uno tra `title` o `artists`.

## `client.projects.list(options?)`

Elenca tutti i progetti di proprietà dell’account autenticato.

```ts theme={null}
const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));
```

Restituisce un array di elementi dell’elenco progetti (una forma più snella rispetto a `getProject`).

## `client.projects.delete(projectId, options?)`

Elimina un progetto e tutte le tracce, i testi e le esportazioni associati.

```ts theme={null}
await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});
```

<Warning>
  L’eliminazione è permanente. Abbinala a una chiave di idempotenza così i tentativi ripetuti sono sicuri.
</Warning>

## Cosa viene dopo

* [Stems](/it/sdk/stems) — riesegui la separazione delle tracce
* [Lyrics sync](/it/sdk/lyrics-sync) — risincronizza i testi
* [Exports](/it/sdk/exports) — renderizza i video finali
* [Tasks](/it/sdk/tasks) — attendi le operazioni del progetto con `client.projects.wait`