> ## 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. # Automatizzare video con testi > Scegli i modelli, correggi le tempistiche ed esporta una versione di progetto scelta Usa `@youka/sdk` e `@youka/cli` versione 0.2.0 o successiva per questi esempi. I progetti creati tramite l’API restano disponibili nella tua libreria Youka. ## Scegli un workflow e un modello `kind` seleziona il workflow del progetto. `karaoke` separa le tracce (stems). `lyric-video` usa l’audio originale e non addebita costi per la separazione. Se `kind` viene omesso, mantiene il comportamento karaoke esistente. L’elaborazione dei testi è una scelta separata tra allineamento, trascrizione o nessuna elaborazione. Scopri i modelli e l’idoneità dell’account prima di scegliere un modello. ```sh theme={null} youka capabilities --json ``` ```ts theme={null} const capabilities = await client.capabilities.get(); const eligibleModels = capabilities.models.filter( (model) => model.eligible && model.workflows.includes("lyric-video"), ); ``` La risposta descrive ID dei modelli, operazioni, input audio, semantica del testo fornito, workflow, supporto linguistico e funzionalità richieste. `suppliedTextHandling` distingue tra allineamento, keyterm del provider e correzione dopo la trascrizione. L’idoneità riflette l’account autenticato. La discovery descrive il supporto configurato, non una garanzia di disponibilità del provider. La validazione delle richieste e i preventivi di prezzo restano l’autorità. I modelli che richiedono voci isolate non possono elaborare un lyric video senza separazione. Usali in un workflow karaoke con un modello di separazione che produca le voci. Wav2Vec2 è un modello di allineamento. ElevenLabs Scribe è un modello di trascrizione. Il testo di trascrizione fornito è una guida, non una garanzia di output testuale identico. ## Crea e quota i progetti ```ts theme={null} import { AlignmentModel, YoukaClient } from "@youka/sdk"; const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! }); const operation = await client.projects.create( { kind: "lyric-video", source: { type: "path", path: "./song.wav" }, title: "Example song", lyricsSource: { type: "transcribe", syncModel: AlignmentModel.ElevenLabsTranscription, lyrics: "Optional reference lyrics", }, }, { idempotencyKey: "example-song-create-v1" }, ); const { project } = await client.projects.wait(operation); ``` Allinea i testi forniti con un modello pubblicizzato per i lyric video. ```sh theme={null} youka project create ./song.wav --kind lyric-video --mode align \ --sync-model audioshake-alignment --lyrics 'Line one Line two' --json ``` Mantieni la separazione per i progetti karaoke. Ometti `--kind` oppure passa `--kind karaoke` e scegli `--split-model`. Usa `--mode none` per creare senza elaborazione dei testi. Le richieste lyric-video rifiutano le opzioni di separazione. Quota la stessa sorgente, lo stesso workflow e le stesse opzioni di elaborazione prima della creazione. ```sh theme={null} youka project quote ./song.wav --kind lyric-video --mode transcribe \ --sync-model elevenlabs-transcription --json ``` Un preventivo verifica la stessa compatibilità dei modelli, policy linguistiche, funzionalità dell’account, durata e regole di archiviazione della creazione. Il suo dettaglio crediti ha zero crediti di separazione per i lyric video. Un preventivo non riserva capacità o crediti; lo stato dell’account può cambiare prima della creazione. ## Correggi le tempistiche senza job di elaborazione Leggi gli allineamenti tramite `GET /projects/{projectId}/alignments`, quindi ottieni la risorsa scelta tramite `GET /projects/{projectId}/alignments/{alignmentId}`. L’elenco contiene `alignments`, `selectedAlignmentId` e `selectionRevision`. Ogni risorsa include il payload delle tempistiche, `revision`, `selected` e `selectionRevision`. Gli aggiornamenti sostituiscono l’oggetto `alignment` completo. Non eseguono la sincronizzazione né creano un blocco crediti di elaborazione. Mantieni ID, testo, indici di riga/parola/sottoparola, informazioni del cantante e traduzioni durante la modifica. I tempi sono secondi decimali assoluti. Applica qualsiasi correzione desiderata una sola volta nei valori inviati. Non aggiungere di nuovo la stessa correzione come offset di esportazione. ```ts theme={null} const snapshot = await client.projects.alignments.list(project.id); const current = snapshot.alignments.find( (alignment) => alignment.id === snapshot.selectedAlignmentId, ); if (!current) throw new Error("Project has no alignment to edit"); const corrected = structuredClone(current.alignment); corrected.items[0]!.start = 0.75; corrected.items[0]!.end = 1.25; const saved = await client.projects.alignments.update(project.id, current.id, { alignment: corrected, expectedRevision: current.revision, select: true, expectedSelectionRevision: snapshot.selectionRevision, }); ``` Usa `select: true` per salvare e selezionare in modo atomico. Per selezionare tempistiche esistenti senza sostituirle, chiama `client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision })`. La revisione dell’allineamento protegge i contenuti delle tempistiche. La revisione di selezione protegge quale allineamento è attivo. Un token obsoleto produce HTTP 409. Recupera la risorsa più recente, confronta le modifiche e invia una sostituzione deliberata. Non aggiornare automaticamente il token e sovrascrivere le modifiche di un altro editor. La CLI accetta un file JSON o lo standard input. Un file di import contiene `{ "alignment": { "items": [...] }, "expectedRevision": "..." }`. Includi `select` ed `expectedSelectionRevision` quando selezioni in modo atomico. Le risorse esportate contengono anche metadati di risposta, quindi estrai i campi della richiesta prima di importare. ```sh theme={null} youka project timings list proj_example --json youka project timings get proj_example aln_example --json > timing-resource.json youka project timings import proj_example aln_example --body corrected-request.json --json youka project timings select proj_example aln_example \ --expected-revision "$ALIGNMENT_REVISION" \ --expected-selection-revision "$SELECTION_REVISION" --json ``` Le importazioni accettano fino a 100.000 elementi. Ogni tempo di fine deve essere strettamente maggiore del suo inizio. Numeri non validi, tempi negativi, indici non validi, intervalli di durata zero o invertiti e tempistiche oltre una durata nota del progetto vengono rifiutati. Sovrapposizioni legittime e tempistiche di duetto restano supportate. Riapri o aggiorna un progetto app già aperto dopo una modifica esterna. ## Esporta una versione scelta ```sh theme={null} youka project versions proj_example --json youka export create proj_example --version-id ver_example --local \ --transparent --mute-all --fps 30 --output ./overlay.mov --json ``` `versionId` è facoltativo nelle richieste di esportazione e negli aggiornamenti delle impostazioni, e nella query GET delle impostazioni. Se omesso, mantiene il comportamento della versione primaria. L’allineamento selezionato appartiene al progetto, mentre stile e impostazioni appartengono alla versione scelta. ```ts theme={null} const versions = await client.projects.versions.list(project.id); const versionId = versions[0]!.id; const stemVolumes = Object.fromEntries( project.stems.map((stem) => [stem.id, 0]), ); const payload = await client.exports.prepareLocal(project.id, { versionId, transparent: true, stemVolumes, fps: 30, }); console.log(payload.versionId, payload.alignmentId, payload.alignmentRevision); await client.exports.create(project.id, { target: "local", versionId, transparent: true, stemVolumes, fps: 30, outputPath: "./overlay.mov", }); ``` Gli handle delle operazioni di export cloud e i payload locali includono `versionId`, `alignmentId` e `alignmentRevision`. Questi campi identificano lo snapshot delle tempistiche usato per quell’esportazione o per il payload preparato. Ogni preparazione legge lo stato corrente, quindi una successiva esportazione separata può osservare modifiche più recenti. Salva il payload restituito quando un renderer esterno deve renderizzare esattamente quello snapshot preparato e aggiornalo quando scadono gli URL firmati dei media. L’output locale trasparente usa ProRes 4444 in un container MOV. `--mute-all` mappa tutte le tracce del progetto a volume zero. Il silenzio e l’assenza di una traccia audio sono proprietà di output diverse; ispeziona il file renderizzato se uno strumento a valle ne richiede una in particolare. Il rendering locale non consuma crediti di export cloud e resta soggetto all’idoneità delle funzionalità esistenti. Le tempistiche delle parole, gli offset audio globali e l’anticipazione dei testi sono impostazioni separate. I layout esistenti controllano la visibilità delle righe. Questa release non promette un intervallo di rivelazione fisso per ogni riga né aggiunge un’API separata per l’allegato di backing track. ## Gestisci un catalogo in modo sicuro Mantieni un manifest con un ID elemento stabile, impronta della sorgente, impostazioni dell’operazione, chiave di idempotenza, ID progetto/task e l’ultimo risultato terminale. Riutilizza una chiave solo per i retry della stessa richiesta. Persistere i risultati della creazione prima di attendere il completamento, così un riavvio può riprendere il polling. Gli upload e la preparazione dei file locali hanno un proprio ciclo di vita; una chiave di idempotenza di creazione non deduplica ogni upload. L’eseguibile [catalogue example](/examples/catalogue.js) accetta ID di file di input pre-caricati e persiste un checkpoint per elemento. Un manifest appare così. ```json theme={null} [ { "id": "song-001", "request": { "kind": "lyric-video", "inputFileId": "owned-upload-id", "title": "Example song", "lyricsSource": { "type": "transcribe", "syncModel": "elevenlabs-transcription" } } } ] ``` Scarica l’esempio come `catalogue.ts`. Installa le sue dipendenze e imposta `YOUKA_API_KEY`. Usa un progetto Node.js con `"type": "module"` nel suo `package.json`. ```sh theme={null} npm install @youka/sdk@^0.2.0 tsx npx tsx ./catalogue.ts ./manifest.json ./catalogue-state 1 ``` Esegui di nuovo con lo stesso manifest e la stessa directory di stato per riprendere il polling dei job accettati o ritentare un invio incerto con la sua chiave originale. I job completati e falliti vengono registrati e saltati. Le richieste modificate richiedono nuovi ID elemento. Il lock della directory impedisce a due processi di inviare lo stesso manifest in contemporanea. Dopo un crash improvviso, rimuovi un `.lock` obsoleto solo dopo aver confermato che il PID memorizzato al suo interno non è più in esecuzione. Inizia con un solo elemento in-flight. Aumenta un numero di worker limitato solo dopo aver misurato la latenza di elaborazione e le risposte di rate-limit per il tuo account. Ritenta gli errori di trasporto e i rate limit con backoff, rispettando `Retry-After`. Non ritentare alla cieca errori di validazione, conflitti di tempistiche o fallimenti terminali di elaborazione. Gli errori di autenticazione richiedono credenziali valide; non significano che un job di elaborazione sia fallito. Mantieni il polling esistente dei task cloud e la gestione dei crediti in caso di fallimento. Qui non viene introdotto alcun endpoint batch, promessa di webhook, cambiamento di prezzo, cambiamento di licenza o policy di retention.