Definisci una composizione di elementi multimediali

La libreria Media3 Transformer fornisce una suite di strumenti per modificare e manipolare i contenuti multimediali. Un componente principale per la modifica di più asset è l'API Composition. Questa API ti consente di disporre più elementi multimediali di input, come clip video, immagini e tracce audio, in una singola struttura coerente che può essere elaborata, visualizzata in anteprima o esportata. Una Composition può essere considerata una sequenza temporale che contiene una o più sequenze di contenuti multimediali. Ogni sequenza (definita da un EditedMediaItemSequence) contiene singoli elementi multimediali (definiti come istanze EditedMediaItem). Le trasformazioni e gli effetti possono essere applicati a un singolo EditedMediaItem, o a un'intera Composition.

Struttura di un oggetto Composizione
La struttura di un oggetto Composition

Una Composition è il punto di accesso per una serie di casi d'uso con Media3 Transformer, ad esempio:

  • Combinazione sequenziale di asset audio, immagine e video.
  • Sovrapposizione di un video su un altro video (picture-in-picture).
  • Mixaggio di una traccia audio di sottofondo con una sequenza video.
  • Applicazione di effetti visivi o audio a un intero brano modificato.
  • Gestione di scenari complessi come l'elaborazione di video HDR.

Questa guida si concentra su come definire e creare oggetti Composition, incluse le classi chiave coinvolte, come creare composizioni di base e più complesse con una o più sequenze e come applicare effetti a diversi livelli.

Concetti e classi chiave

Per utilizzare in modo efficace l'API Composition, è importante comprendere le classi principali coinvolte nella creazione di una composizione multimediale:

Effects:

  • Scopo: un oggetto Effects è una raccolta di processori audio ed effetti video.
  • Modalità di utilizzo: nel contesto di una Composition, è possibile impostare un Effects su singole istanze EditedMediaItem per modificare clip specifici o sulla Composition nel suo complesso (in genere per gli effetti Presentation che influiscono sull'output finale, ad esempio la regolazione della risoluzione di visualizzazione o della frequenza fotogrammi).
  • Perché è importante: Effects è il meccanismo per applicare trasformazioni, filtri e altre elaborazioni ai contenuti multimediali sia a livello di singolo elemento sia a livello di composizione complessiva. Per saperne di più, consulta Transformations.

EditedMediaItem:

  • Scopo: questa classe rappresenta un singolo contenuto multimediale (ad esempio un file video, immagine o audio) e le modifiche da applicare.
  • Modalità di utilizzo: Un EditedMediaItem raggruppa un MediaItem (che rimanda ai contenuti multimediali effettivi) con un oggetto Effects.
  • Perché è importante: questo è il componente di base della tua composizione. Ti consente di definire con precisione quali contenuti multimediali includere e come ogni singolo elemento deve apparire e suonare prima di essere combinato con altri in una sequenza.

EditedMediaItemSequence:

  • Scopo: rappresenta una sequenza lineare di oggetti EditedMediaItem destinati alla riproduzione uno dopo l'altro.
  • Modalità di utilizzo: Un EditedMediaItemSequence viene creato con un elenco di EditedMediaItem oggetti. Ogni sequenza all'interno di una Composition è simile a una traccia o a un livello in una sequenza temporale di editing video multitraccia. Ad esempio, una sequenza potrebbe contenere le clip video principali, mentre un'altra sequenza, che si sovrappone nel tempo, potrebbe contenere clip video da sovrapporre alla prima e un'altra sequenza potrebbe contenere solo una traccia audio per la musica di sottofondo.
  • Perché è importante: un EditedMediaItemSequence raggruppa gli elementi multimediali correlati che devono seguire direttamente l'uno l'altro. Utilizzando più sequenze, puoi creare disposizioni più complesse, come la stratificazione dell'audio o la creazione di overlay visivi.

Composition:

  • Scopo: questo è l'oggetto di primo livello che rappresenta l'intera sequenza temporale dei contenuti multimediali da elaborare. Funge da container per tutte le sequenze multimediali e per tutte le impostazioni o gli effetti globali che si applicano all'intero output.
  • Modalità di utilizzo: una Composition è costituita da uno o più EditedMediaItemSequence oggetti. Puoi anche applicare effetti a livello di composizione e impostare configurazioni globali come la modalità HDR direttamente sulla Composition. Se una Composition contiene più oggetti EditedMediaItemSequence, queste sequenze possono essere disposte in modo da essere riprodotte in sequenza o possono sovrapporsi nel tempo, consentendo layout sovrapposti come picture-in-picture o transizioni da una sequenza all'altra.
  • Perché è importante: una Composition definisce la struttura complessiva dei contenuti multimediali di input da elaborare ed è un oggetto comune che puoi utilizzare sia per visualizzare l'anteprima delle modifiche con un CompositionPlayer sia per esportare un video di output con le modifiche applicate utilizzando Transformer.

Creare ed esportare una Composition

Ecco un esempio di creazione di un asset video costituito da due clip video modificate, sovrapposte a una traccia audio, e della sua esportazione:

Kotlin

val video1 = EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build()

val video2 = EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build()

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

val backgroundAudio = EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build()

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

val composition = Composition.Builder(videoSequence, backgroundAudioSequence).build()

transformer.start(composition, filePath)

Java

EditedMediaItem video1 = new EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build();

EditedMediaItem video2 = new EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build();

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

EditedMediaItem backgroundAudio =
    new EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build();

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

Composition composition =
    new Composition.Builder(videoSequence, backgroundAudioSequence).build();

transformer.start(composition, filePath);

Esempi di casi d'uso supportati

Questo è un elenco non esaustivo di casi d'uso che l'API Transformer supporta con Composition:

  • Combinazione sequenziale di asset audio, immagine e video.
  • Aggiunta di audio di sottofondo a un asset video.
  • Aggiunta di effetti a una composizione.
  • Mappatura tonale dell'input HDR in SDR per generare un output SDR di migliore qualità visiva.

Limitazioni attuali

Le sequenze all'interno di una composizione devono soddisfare le condizioni descritte in Transformer.start(). Inoltre, le seguenti operazioni non sono ancora supportate quando si lavora con le composizioni:

  • Dissolvenza incrociata di tracce video o audio

Richieste di funzionalità

Se hai richieste di funzionalità per le API Transformer, segnala un problema nel repository GitHub di Media3.