Visualizzare l'anteprima delle modifiche con CompositionPlayer

La libreria Jetpack Media3 fornisce l'API CompositionPlayer, una potente implementazione Player per visualizzare l'anteprima delle modifiche video in tempo reale. Se la tua app consente agli utenti di modificare i video, ad esempio applicando effetti, tagliando o componendo più elementi multimediali di input, CompositionPlayer ti aiuta a mostrare un'anteprima accurata dell'output. Questo può essere utile nei casi in cui non è necessario salvare le modifiche applicate o per verificare che le modifiche siano configurate come previsto prima di eseguirne il commit nel video finale per l'esportazione.

Che cos'è CompositionPlayer?

CompositionPlayer è un'implementazione specializzata dell' interfaccia Player, progettata specificamente per riprodurre gli oggetti Composition. Un oggetto Composition definisce la disposizione degli asset multimediali di input, come clip video e tracce audio, e gli effetti audio e video da applicare. Per scoprire di più sull'API Composition, consulta Definire una Composition di elementi multimediali.

Lo scopo principale di CompositionPlayer è eseguire il rendering di questa Composition, completa di tutte le modifiche specificate, in tempo reale, consentendo agli utenti di vedere esattamente l'aspetto delle modifiche prima di eseguire il commit nel processo di esportazione, che potrebbe richiedere tempo e risorse. Lo stesso Composition oggetto può quindi essere utilizzato con un'Transformer istanza per l'esportazione, di cui puoi scoprire di più in Esportare un Composition.

CompositionPlayer rispetto a ExoPlayer

Sebbene sia CompositionPlayer sia ExoPlayer siano implementazioni Player in Media3, sono ottimizzate per casi d'uso diversi:

Funzionalità

CompositionPlayer

ExoPlayer

Contenuti multimediali di input

Accetta un singolo oggetto Composition, che può essere costituito da più istanze EditedMediaItem con effetti per elemento.

Accetta un singolo MediaItem o una playlist di istanze MediaItem.

Cronologia

La cronologia e la durata si basano sull'intera composizione.

La cronologia e la durata corrispondono a MediaItem in riproduzione attiva.

Effetti

Gli effetti sono definiti all'interno della composizione e possono essere applicati a un singolo EditedMediaItem o all'intera composizione.

Gli effetti vengono impostati sull'istanza ExoPlayer stessa con setVideoEffects() e ogni effetto viene applicato singolarmente a ogni elemento della playlist.

In sostanza, CompositionPlayer è più utile quando devi eseguire il rendering di una complessa Composition di contenuti multimediali ed effetti, in genere in un contesto di modifica. Utilizza ExoPlayer per la riproduzione generica di contenuti audio o video o per visualizzare l'anteprima delle modifiche di un singolo asset con setVideoEffects().

CompositionPlayer per l'anteprima

L'integrazione di CompositionPlayer nella tua app prevede alcuni passaggi chiave. Innanzitutto, utilizza il pattern Builder per creare un'istanza di CompositionPlayer, quindi imposta la Composition da riprodurre:

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()

Per indicazioni su come creare una Composition, consulta la Creare una Composition sezione.

Tieni presente che, poiché CompositionPlayer implementa l'interfaccia Player, puoi quindi impostare l'output di destinazione e controllare il player tramite i metodi Player standard.

Gestione degli errori

Collega un'istanza Player.Listener a CompositionPlayer per reagire agli eventi e agli errori di riproduzione. Il onPlayerError() callback mostrerà anche eventuali problemi provenienti da componenti specifici per la modifica, come la Composition o VideoGraph.Factory. Per ulteriori dettagli, consulta la documentazione sugli eventi del Player.

Considerazioni importanti

Ecco alcune funzionalità e limitazioni da tenere presenti quando utilizzi CompositionPlayer:

  • Sebbene CompositionPlayer sia basato sull'interfaccia Player, alcuni dei suoi comportamenti differiscono da ExoPlayer perché dipende da una Composition per la riproduzione. Ad esempio, CompositionPlayer supporta solo l'impostazione della modalità di ripetizione su REPEAT_MODE_OFF o REPEAT_MODE_ALL.
  • Per impostazione predefinita, CompositionPlayer utilizza un SingleInputVideoGraph.Factory, ma se la composizione utilizza più di una sequenza con elementi immagine o video, devi utilizzare setVideoGraphFactory() quando crei l'istanza CompositionPlayer per utilizzare invece un MultipleInputVideoGraph.Factory. Un SingleInputVideoGraph.Factory è sufficiente se solo una sequenza ha elementi immagine o video e le altre sono solo audio.
  • La durata di tutti gli elementi multimediali nella composizione deve essere impostata in modo esplicito, con MediaItem.Builder.setImageDurationMs() per le immagini o con EditedMediaItem.Builder.setDurationUs() per audio o video.

Sono supportati i seguenti casi d'uso:

  • Anteprima di un singolo asset.
  • Anteprima di una singola sequenza (ovvero elementi multimediali sequenziali).
  • Anteprima di una singola sequenza video + una singola sequenza audio (ad esempio, audio di sottofondo).

I seguenti casi d'uso sono in fase di sviluppo attivo:

  • Anteprima di più asset, inclusi layout come picture-in-picture, side-by-side e griglia, in cui sono coinvolte più sequenze video.
  • Personalizzazione della pipeline di modifica con un motore grafico diverso.

Richieste di funzionalità

Se hai richieste di funzionalità o feedback per CompositionPlayer, segnala un problema nel repository GitHub di Media3.