MediaRouter – Übersicht

Wenn du das MediaRouter-Framework in deiner App verwenden möchtest, musst du eine Instanz des MediaRouter-Objekts abrufen und ein MediaRouter.Callback-Objekt anhängen, um auf Routing-Ereignisse zu warten. Inhalte, die über eine Medienroute gesendet werden, werden über den zugehörigen MediaRouteProvider der Route geleitet (außer in einigen Sonderfällen, z. B. bei einem Bluetooth-Ausgabegerät). Abbildung 1 bietet eine allgemeine Übersicht über die Klassen, die zum Weiterleiten von Inhalten zwischen Geräten verwendet werden.

Abbildung 1. Übersicht über die wichtigsten MediaRouter-Klassen, die von Apps verwendet werden.

Hinweis: Wenn Ihre App Google Cast-Geräte unterstützen soll, sollten Sie das Cast SDK verwenden und Ihre App als Cast-Sender erstellen. Folge der Anleitung in der Cast-Dokumentation, anstatt das MediaRouter-Framework direkt zu verwenden.

Schaltfläche „MediaRouteButton“

Android-Apps sollten eine Schaltfläche für die Medienroute verwenden, um das Medienrouting zu steuern. Das MediaRouter-Framework bietet eine Standardschnittstelle für die Schaltfläche, die Nutzern hilft, das Routing zu erkennen und zu verwenden, wenn es verfügbar ist. Die Schaltfläche für die Medienroute befindet sich normalerweise auf der rechten Seite der Aktionsleiste Ihrer App, wie in Abbildung 2 dargestellt.

Abbildung 2: Schaltfläche „Medienroute“ in der Aktionsleiste.

Wenn der Nutzer auf die Schaltfläche für die Medienroute drückt, werden die verfügbaren Medienrouten in einer Liste angezeigt, wie in Abbildung 3 dargestellt.

Abbildung 3: Eine Liste der verfügbaren Medienrouten, die nach dem Drücken der Medienroutenschaltfläche angezeigt wird.

So erstellen Sie eine Schaltfläche für das Medien-Routing:

  1. AppCompatActivity verwenden
  2. Menüpunkt für die Schaltfläche „Medienroute“ definieren
  3. MediaRouteSelector erstellen
  4. Schaltfläche „Medien-Routing“ zur Aktionsleiste hinzufügen
  5. MediaRouter.Callback-Methoden im Lebenszyklus Ihrer Aktivität erstellen und verwalten

In diesem Abschnitt werden die ersten vier Schritte beschrieben. Im nächsten Abschnitt werden Callback-Methoden beschrieben.

AppCompatActivity verwenden

Wenn du das MediaRouter-Framework in einer Aktivität verwendest, solltest du die Aktivität von AppCompatActivity erweitern und das Paket androidx.appcompat.app importieren. Sie müssen Ihrem App-Entwicklungsprojekt die Support-Bibliotheken androidx.appcompat:appcompat und androidx.mediarouter:mediarouter hinzufügen. Weitere Informationen zum Hinzufügen von Support-Bibliotheken zu Ihrem Projekt finden Sie unter Erste Schritte mit Android Jetpack.

Achtung: Verwende die androidx-Implementierung des Media Router-Frameworks. Verwenden Sie nicht das ältere android.media-Paket.

Erstelle eine XML-Datei, die einen Menüpunkt für die Schaltfläche „Medien-Streaming“ definiert. Die Aktion des Elements sollte die Klasse MediaRouteActionProvider sein. Hier sehen Sie eine Beispieldatei:

<menu xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      >

    <item android:id="@+id/media_route_menu_item"
        android:title="@string/media_route_menu_title"
        app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"
        app:showAsAction="always"
    />
</menu>

MediaRouteSelector erstellen

Die Routen, die im Menü der Schaltfläche für Medienrouten angezeigt werden, werden durch ein MediaRouteSelector bestimmt. Erweitern Sie Ihre Aktivität von AppCompatActivity und erstellen Sie die Auswahl, wenn die Aktivität erstellt wird. Rufen Sie dazu MediaRouteSelector.Builder über die Methode „onCreate()“ auf, wie im folgenden Codebeispiel gezeigt. Beachten Sie, dass die Auswahl in einer Klassenvariable gespeichert wird und die zulässigen Routentypen durch Hinzufügen von MediaControlIntent-Objekten angegeben werden:

class MediaRouterPlaybackActivity : AppCompatActivity() {

    private var mSelector: MediaRouteSelector? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Create a route selector for the type of routes your app supports.
        mSelector = MediaRouteSelector.Builder()
            // These are the framework-supported intents.
            .addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            .build()
    }
}

Für die meisten Anwendungen ist der einzige erforderliche Routentyp CATEGORY_REMOTE_PLAYBACK. Bei diesem Routentyp wird das Gerät, auf dem Ihre App ausgeführt wird, als Fernbedienung behandelt. Das verbundene Empfängergerät übernimmt das Abrufen, Decodieren und Wiedergeben aller Inhaltsdaten. So funktionieren Apps, die Google Cast unterstützen, z. B. Chromecast.

Einige Hersteller unterstützen eine spezielle Routingoption namens „Sekundäre Ausgabe“. Bei diesem Routing ruft deine Medien-App Videos oder Musik ab, rendert sie und streamt sie direkt auf den Bildschirm und/oder die Lautsprecher des ausgewählten Remote-Empfängergeräts. Über die sekundäre Ausgabe kannst du Inhalte an WLAN-fähige Musiksysteme oder Videodisplays senden. Damit diese Geräte gefunden und ausgewählt werden können, müssen Sie dem MediaRouteSelector die Steuerkategorien CATEGORY_LIVE_AUDIO oder CATEGORY_LIVE_VIDEO hinzufügen. Außerdem müssen Sie einen eigenen Presentation-Dialog erstellen und verwalten.

Schaltfläche „Medien-Routing“ zur Aktionsleiste hinzufügen

Nachdem Sie das Menü für das Medienrouting und den MediaRouteSelector definiert haben, können Sie die Schaltfläche für das Medienrouting einer Aktivität hinzufügen. Überschreibe die Methode onCreateOptionsMenu() für jede deiner Aktivitäten, um ein Optionsmenü hinzuzufügen.

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    super.onCreateOptionsMenu(menu)

    // Inflate the menu and configure the media router action provider.
    menuInflater.inflate(R.menu.sample_media_router_menu, menu)

    // Attach the MediaRouteSelector to the menu item.
    val mediaRouteMenuItem = menu.findItem(R.id.media_route_menu_item)
    val mediaRouteActionProvider =
        MenuItemCompat.getActionProvider(mediaRouteMenuItem) as MediaRouteActionProvider

    // Attach the MediaRouteSelector that you built in onCreate().
    selector?.also(mediaRouteActionProvider::setRouteSelector)

    // Return true to show the menu.
    return true
}

Weitere Informationen zum Implementieren der Aktionsleiste in Ihrer App finden Sie im Entwicklerleitfaden zur Aktionsleiste.

Du kannst auch eine Schaltfläche für die Medienausgabe als MediaRouteButton in einer beliebigen Ansicht hinzufügen. Du musst der Schaltfläche mit der Methode setRouteSelector() einen MediaRouteSelector hinzufügen. In der Google Cast-Design-Checkliste finden Sie Richtlinien zum Einbinden der Schaltfläche für die Medienroute in Ihre Anwendung.

MediaRouter-Callbacks

Alle Apps, die auf demselben Gerät ausgeführt werden, teilen sich eine einzige MediaRouter-Instanz und ihre Routen (gefiltert pro App durch den MediaRouteSelector der App). Jede Aktivität kommuniziert mit dem MediaRouter über ihre eigene Implementierung von MediaRouter.Callback-Methoden. Der MediaRouter ruft die Callback-Methoden auf, wenn der Nutzer eine Route auswählt, ändert oder trennt.

Es gibt mehrere Methoden im Callback, die Sie überschreiben können, um Informationen zu Routingereignissen zu erhalten. Ihre Implementierung der Klasse MediaRouter.Callback sollte mindestens onRouteSelected() und onRouteUnselected() überschreiben.

Da der MediaRouter eine gemeinsam genutzte Ressource ist, muss deine App die MediaRouter-Callbacks als Reaktion auf die üblichen Aktivitätslebenszyklus-Callbacks verwalten:

  • Wenn die Aktivität erstellt wird (onCreate(Bundle)), rufen Sie einen Zeiger auf die MediaRouter ab und behalten Sie ihn für die Lebensdauer der App bei.
  • Hänge Callbacks an MediaRouter an, wenn die Aktivität sichtbar wird (onStart()), und trenne sie, wenn sie ausgeblendet wird (onStop()).

Im folgenden Codebeispiel wird gezeigt, wie Sie das Callback-Objekt erstellen und speichern, eine Instanz von MediaRouter abrufen und Callbacks verwalten. Beachten Sie die Verwendung des Flags CALLBACK_FLAG_REQUEST_DISCOVERY beim Anhängen der Callbacks in onStart(). Dadurch kann der MediaRouteSelector die Liste der verfügbaren Routen für die Schaltfläche „Medienroute“ aktualisieren.

class MediaRouterPlaybackActivity : AppCompatActivity() {

    private var mediaRouter: MediaRouter? = null
    private var mSelector: MediaRouteSelector? = null

    // Variables to hold the currently selected route and its playback client.
    private var mRoute: MediaRouter.RouteInfo? = null
    private var remotePlaybackClient: RemotePlaybackClient? = null

    // Define the Callback object and its methods, save the object in a class variable.
    private val mediaRouterCallback = object : MediaRouter.Callback() {

        override fun onRouteSelected(
            router: MediaRouter,
            route: MediaRouter.RouteInfo,
            reason: Int
        ) {
            Log.d(TAG, "onRouteSelected: route=$route")
            if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
                // Stop local playback (if necessary).
                // ...

                // Save the new route.
                mRoute = route

                // Attach a new playback client.
                remotePlaybackClient =
                    RemotePlaybackClient(this@MediaRouterPlaybackActivity, route)

                // Start remote playback (if necessary).
                // ...
            }
        }

        override fun onRouteUnselected(
            router: MediaRouter,
            route: MediaRouter.RouteInfo,
            reason: Int
        ) {
            Log.d(TAG, "onRouteUnselected: route=$route")
            if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {

                // Changed route: tear down previous client.
                mRoute?.also {
                    remotePlaybackClient?.release()
                    remotePlaybackClient = null
                }

                // Save the new route.
                mRoute = route

                when {
                    reason != MediaRouter.UNSELECT_REASON_ROUTE_CHANGED -> {
                        // Resume local playback (if necessary).
                        // ...
                    }
                }
            }
        }
    }

    // Retain a pointer to the MediaRouter.
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Get the media router service.
        mediaRouter = MediaRouter.getInstance(this)
        // ...
    }

    // Use this callback to run your MediaRouteSelector to generate the
    // list of available media routes.
    override fun onStart() {
        mSelector?.also { selector ->
            mediaRouter?.addCallback(
                selector, mediaRouterCallback,
                MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY
            )
        }
        super.onStart()
    }

    // Remove the selector on stop to tell the media router that it no longer
    // needs to discover routes for your app.
    override fun onStop() {
        mediaRouter?.removeCallback(mediaRouterCallback)
        super.onStop()
    }
    // ...
}

Das Media Router-Framework bietet auch eine MediaRouteDiscoveryFragment-Klasse, die das Hinzufügen und Entfernen des Callbacks für eine Aktivität übernimmt.

Hinweis: Wenn du eine App für die Musikwiedergabe schreibst und möchtest, dass die App Musik im Hintergrund abspielt, musst du einen Service für die Wiedergabe erstellen und das Media Router-Framework über die Lebenszyklus-Callbacks des Dienstes aufrufen.

Remote-Wiedergaberoute steuern

Wenn Sie eine Remote-Wiedergaberoute auswählen, fungiert Ihre App als Fernbedienung. Das Gerät am anderen Ende der Route übernimmt alle Funktionen zum Abrufen, Decodieren und Wiedergeben von Inhalten. Die Steuerelemente in der Benutzeroberfläche deiner App kommunizieren über ein RemotePlaybackClient-Objekt mit dem Empfängergerät.

Die Klasse RemotePlaybackClient bietet zusätzliche Methoden zum Verwalten der Wiedergabe von Inhalten. Hier sind einige der wichtigsten Wiedergabemethoden der Klasse RemotePlaybackClient:

  • play(): Eine bestimmte Mediendatei abspielen, die durch eine Uri angegeben wird.
  • pause() – Pausiert den aktuell wiedergegebenen Medientrack.
  • resume() – Setzt die Wiedergabe des aktuellen Titels nach einem Pause-Befehl fort.
  • seek(): Zu einer bestimmten Position im aktuellen Titel wechseln.
  • release(): Die Verbindung zwischen deiner App und dem Remote-Wiedergabegerät wird getrennt.

Mit diesen Methoden kannst du Aktionen an die Wiedergabesteuerung in deiner App anhängen. Bei den meisten dieser Methoden kannst du auch ein Callback-Objekt einfügen, um den Fortschritt der Wiedergabeaufgabe oder Steuerungsanfrage zu überwachen.

Die Klasse RemotePlaybackClient unterstützt auch das Einreihen mehrerer Mediendateien in die Wiedergabeliste und die Verwaltung der Wiedergabeliste.

Beispielcode

Die Beispiele Android BasicMediaRouter und MediaRouter veranschaulichen die Verwendung der MediaRouter API.