Automatizzare video con testi

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.

youka capabilities --json

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

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.

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.

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.

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.

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

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.

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 accetta ID di file di input pre-caricati e persiste un checkpoint per elemento. Un manifest appare così.

[
  {
    "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.

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.

Guides

API Reference

Automatizzare video con testi

Scegli un workflow e un modello

Crea e quota i progetti

Correggi le tempistiche senza job di elaborazione

Esporta una versione scelta

Gestisci un catalogo in modo sicuro

​Scegli un workflow e un modello

​Crea e quota i progetti

​Correggi le tempistiche senza job di elaborazione

​Esporta una versione scelta

​Gestisci un catalogo in modo sicuro

Scegli un workflow e un modello

Crea e quota i progetti

Correggi le tempistiche senza job di elaborazione

Esporta una versione scelta

Gestisci un catalogo in modo sicuro