Interfaccia del player

Un player è il componente della tua app che facilita la riproduzione di elementi multimediali. L'interfaccia Player di Media3 definisce una struttura per le funzionalità generalmente gestite da un player. È incluso quanto segue:

• Interessano i controlli di riproduzione, ad esempio la riproduzione, la messa in pausa e la ricerca
• Eseguire query sulle proprietà dei contenuti multimediali attualmente in riproduzione, ad esempio la posizione di riproduzione
• Gestione di una playlist/coda di elementi multimediali
• Configurazione delle proprietà di riproduzione, come riproduzione casuale, ripetizione, velocità e volume
• Rendering del video sullo schermo

Media3 fornisce anche un'implementazione dell'interfaccia Player, chiamata ExoPlayer.

Suggerimento: se vuoi implementare un'app di media player utilizzando ExoPlayer, consulta la guida Crea un'app di media player di base utilizzando Media3 ExoPlayer.

Un'interfaccia comune tra i componenti

Diversi componenti di Media3 implementano l'interfaccia Player, ad esempio:

Componente	Descrizione e note sul comportamento
ExoPlayer	Un'API del media player e l'implementazione predefinita dell'interfaccia Player.
MediaController	Interagisce con un MediaSession per inviare comandi di riproduzione. Se Player e MediaSession si trovano in un Service separato da Activity o Fragment in cui si trova la UI del player, puoi assegnare MediaController come player per il tuo componente UI, ad esempio PlayerView o Player componibile. Le chiamate ai metodi di riproduzione e playlist vengono inviate alla tua Player tramite la tua MediaSession.
MediaBrowser	Oltre alla funzionalità offerta da un MediaController, interagisce con un MediaLibrarySession per sfogliare i contenuti multimediali disponibili.
SimpleBasePlayer	Un'implementazione di Player che riduce al minimo il numero di metodi da implementare. Utile quando utilizzi un player personalizzato che vuoi collegare a un MediaSession.
ForwardingSimpleBasePlayer	Una sottoclasse SimpleBasePlayer progettata per inoltrare le operazioni di riproduzione a un altro Player, consentendo al contempo le stesse personalizzazioni del comportamento coerenti di SimpleBasePlayer. Utilizza questa classe per eliminare o modificare operazioni di riproduzione specifiche.
RemoteCastPlayer	Un'implementazione di Player per controllare la riproduzione su un'app ricevitore Cast remota.
CastPlayer	Un'implementazione di Player per controllare la riproduzione di Cast sia in locale che da remoto.

Sebbene un MediaSession non implementi l'interfaccia Player, richiede un Player durante la creazione. Il suo scopo è fornire l'accesso a Player da altri processi o thread.

Architettura di riproduzione Media3

Se hai accesso a un Player, devi chiamare direttamente i suoi metodi per inviare comandi di riproduzione. Puoi pubblicizzare la tua riproduzione e concedere il controllo della riproduzione a fonti esterne implementando un MediaSession. Queste origini esterne implementano un MediaController, che facilita la connessione a una sessione multimediale e l'invio di richieste di comandi di riproduzione.

Quando riproduci contenuti multimediali in background, devi inserire la sessione multimediale e il player all'interno di un MediaSessionService o MediaLibraryService che viene eseguito come servizio in primo piano. In questo modo, puoi separare il player dall'Activity nella tua app che contiene la UI per i controlli di riproduzione. Ciò potrebbe richiedere l'utilizzo di un controller multimediale.

Figura 1: l'interfaccia Player svolge un ruolo chiave nell'architettura di Media3.

Stato del player

Lo stato di un media player che implementa l'interfaccia Player è costituito principalmente da quattro categorie di informazioni:

1. Stato della riproduzione
   • Recupera con getPlaybackState().
   • I valori di stato definiti dall'interfaccia sono STATE_IDLE, STATE_BUFFERING, STATE_READY e STATE_ENDED.
2. Playlist di elementi multimediali
   • Una sequenza di istanze MediaItem per la riproduzione.
   • Recupera con getCurrentTimeline()
   • Le istanze Player possono fornire metodi di operazione della playlist come aggiunta o rimozione di un MediaItem e metodi di convenienza come getCurrentMediaItem().
3. Proprietà di riproduzione/pausa, ad esempio:
   • playWhenReady: un'indicazione che specifica se l'utente vuole che i contenuti multimediali vengano riprodotti quando possibile o rimangano in pausa
   • Motivo della soppressione della riproduzione: un'indicazione del motivo per cui la riproduzione è soppressa, se applicabile, anche se playWhenReady è true
   • isPlaying: un'indicazione che mostra se il player è attualmente in riproduzione, che sarà true solo se lo stato di riproduzione è STATE_READY, playWhenReady è true e la riproduzione non è soppressa
4. Posizione di riproduzione, tra cui:
   • Indice dell'elemento multimediale corrente: l'indice dell'elemento MediaItem corrente nella playlist.
   • isPlayingAd: un'indicazione che segnala se un annuncio inserito è in riproduzione.
   • Posizione di riproduzione corrente: la posizione di riproduzione corrente all'interno dell'annuncio MediaItem o inserito corrente.

Inoltre, l'interfaccia Player consente di accedere alle tracce disponibili, ai metadati dei contenuti multimediali, alla velocità di riproduzione, al volume e ad altre proprietà ausiliarie della riproduzione.

Nota: le istanze Player non devono supportare tutte le funzionalità dell'interfaccia. Puoi controllare i comandi disponibili per vedere quale funzionalità è supportata e quale metodo può essere chiamato.

Ascolta le modifiche

Utilizza un Player.Listener per rilevare le modifiche in un Player. Per informazioni dettagliate su come creare e utilizzare un listener, consulta la documentazione di ExoPlayer sugli eventi del player.

Tieni presente che l'interfaccia del listener non include callback per monitorare la normale progressione della riproduzione. Per monitorare continuamente l'avanzamento della riproduzione, ad esempio per configurare un'interfaccia utente con barra di avanzamento, devi eseguire query sulla posizione corrente a intervalli appropriati.

Kotlin

fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs,
  )
Player.kt

Java

boolean checkPlaybackPosition(long delayMs) {
  return handler.postDelayed(
      () -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
      },
      delayMs);
}
Player.java

Controllare la riproduzione

L'interfaccia Player offre molti modi per manipolare lo stato e controllare la riproduzione:

• Controlli di riproduzione di base come play(), pause(), prepare() e stop().
• Operazioni sulle playlist come addMediaItem() o removeMediaItem().
• Ricerca per modificare l'elemento o la posizione corrente.
• Impostare le modalità repeat e la modalità shuffle.
• Aggiorna le preferenze di selezione delle tracce.
• Imposta la velocità di riproduzione.

Nota: le istanze Player non devono supportare tutte le funzionalità dell'interfaccia. Puoi controllare i comandi disponibili per vedere quale funzionalità è supportata e quale metodo può essere chiamato.

Implementazioni personalizzate di Player

Per creare un player personalizzato, puoi estendere SimpleBasePlayer incluso in Media3. Questa classe fornisce un'implementazione di base dell'interfaccia Player per ridurre al minimo il numero di metodi da implementare.

Inizia eseguendo l'override del metodo getState(). Questo metodo deve compilare lo stato attuale del player quando viene chiamato, tra cui:

• L'insieme di comandi disponibili
• Proprietà di riproduzione, ad esempio se il player deve avviare la riproduzione quando lo stato di riproduzione è STATE_READY, l'indice dell'elemento multimediale attualmente in riproduzione e la posizione di riproduzione all'interno dell'elemento corrente

Kotlin

class CustomPlayer(looper: Looper) : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}
Player.kt

Java

private static final class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
        .setAvailableCommands(Commands.EMPTY) // Set which playback commands the player can handle
        // Configure additional playback properties
        .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
        .setCurrentMediaItemIndex(0)
        .setContentPositionMs(0)
        .build();
  }
}
Player.java

SimpleBasePlayer imporrà che State venga creato con una combinazione valida di valori di stato. Inoltre, gestirà i listener e li informerà delle modifiche di stato. Se devi attivare manualmente un aggiornamento dello stato, chiama invalidateState().

Oltre al metodo getState(), devi implementare solo i metodi utilizzati per i comandi che il tuo player dichiara di avere a disposizione. Trova il metodo del gestore sostituibile che corrisponde alla funzionalità che vuoi implementare. Ad esempio, esegui l'override del metodo handleSeek() per supportare operazioni come COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM e COMMAND_SEEK_TO_NEXT_MEDIA_ITEM.

Modifica le implementazioni di Player

Anziché creare un Player completamente personalizzato, puoi utilizzare ForwardingSimpleBasePlayer per modificare lo stato e il comportamento di un Player esistente. Per maggiori dettagli, consulta la guida nella pagina Personalizzazione.