किसी मीडिया ऐप्लिकेशन से कनेक्ट करना

मीडिया ऐप्लिकेशन से कनेक्ट करने के दो तरीके हैं:

1. MediaController
2. MediaBrowser

MediaController

मीडिया कंट्रोलर, मीडिया सेशन के साथ इंटरैक्ट करता है, ताकि मीडिया ऐप्लिकेशन के प्लेबैक को कंट्रोल किया जा सके और उससे जुड़ी क्वेरी की जा सके. Media3 में, MediaController एपीआई, Player इंटरफ़ेस लागू करता है. मीडिया कंट्रोलर का इस्तेमाल करने वाले क्लाइंट ऐप्लिकेशन के उदाहरणों में ये शामिल हैं:

• Android सिस्टम मीडिया कंट्रोल
• Android Wear OS के साथ काम करने वाला ऐप्लिकेशन
• Android Auto और Automotive OS
• वॉइस असिस्टेंट, जैसे कि Google Assistant
• Media Controller Test ऐप्लिकेशन

मीडिया कंट्रोलर, मीडिया ऐप्लिकेशन में भी काम आ सकता है. उदाहरण के लिए, अगर प्लेयर और मीडिया सेशन, यूज़र इंटरफ़ेस (यूआई) के साथ Activity या Fragment से Service अलग रहते हैं.

एक MediaController बनाएं

MediaController बनाने के लिए, सबसे पहले उससे जुड़े MediaSession के लिए SessionToken बनाएं. इसके लिए, Activity या Fragment की onStart() विधि का इस्तेमाल किया जा सकता है.

Kotlin

val sessionToken =
  SessionToken(context, ComponentName(context, PlaybackService::class.java))

Java

SessionToken sessionToken =
  new SessionToken(context, new ComponentName(context, PlaybackService.class));

इस SessionToken का इस्तेमाल करके MediaController बनाने से, कंट्रोलर को दिए गए सेशन से कनेक्ट किया जाता है. यह प्रोसेस एसिंक्रोनस तरीके से होती है. इसलिए, आपको नतीजे का इंतज़ार करना चाहिए और उपलब्ध होने पर इसका इस्तेमाल करना चाहिए.

Kotlin

val controllerFuture =
  MediaController.Builder(context, sessionToken).buildAsync()
controllerFuture.addListener({
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaController> controllerFuture =
  new MediaController.Builder(context, sessionToken).buildAsync();
controllerFuture.addListener(() -> {
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor());

ध्यान दें: अगर आपको यूज़र इंटरफ़ेस (यूआई) के अलावा किसी दूसरी प्रोसेस में अपनी सेवा चलानी है, तो MoreExecutors.directExecutor() के बजाय ContextCompat.getMainExecutor() का इस्तेमाल करें.

ध्यान दें: एसडीके लेवल 30 या उसके बाद वाले वर्शन को टारगेट करने वाले ऐप्लिकेशन को अपने मेनिफ़ेस्ट में <queries> एलिमेंट शामिल करना होगा, ताकि वे किसी दूसरे ऐप्लिकेशन के MediaSessionService (या इसी तरह के कॉम्पोनेंट) से कनेक्ट हो सकें. ज़्यादा जानकारी के लिए, पैकेज की दृश्यता से जुड़ी गाइड देखें.

MediaController का इस्तेमाल करना

MediaController, Player इंटरफ़ेस लागू करता है. इसलिए, इंटरफ़ेस में तय की गई कमांड का इस्तेमाल करके, कनेक्ट किए गए MediaSession के प्लेबैक को कंट्रोल किया जा सकता है. इसका मतलब है कि MediaController पर play() को कॉल करने से, कनेक्ट किए गए MediaSession को निर्देश भेजा जाएगा. इसके बाद, MediaSession उस निर्देश को अपने Player को सौंप देगा.

अहम जानकारी: मीडिया कंट्रोलर, Player इंटरफ़ेस लागू करता है. इसलिए, इसे अपने यूज़र इंटरफ़ेस (यूआई) में Player के तौर पर इस्तेमाल किया जा सकता है.

Player की स्थिति में होने वाले बदलावों को सुनने के लिए, कंट्रोलर में Player.Listener जोड़ा जा सकता है. Player.Listener का इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, खिलाड़ी के इवेंट गाइड देखें.

MediaController.Listener इंटरफ़ेस, कनेक्ट किए गए MediaSession से इवेंट और कस्टम कमांड के लिए अतिरिक्त कॉलबैक तय करता है. उदाहरण के लिए, onCustomCommand() जब सेशन कोई कस्टम कमांड भेजता है, onAvailableSessionCommandsChanged() जब सेशन, उपलब्ध सेशन कमांड बदलता है या onDisconnected() जब कंट्रोलर, सेशन से डिसकनेक्ट हो जाता है.

MediaController.Listener को Builder की मदद से कंट्रोलर बनाते समय सेट किया जा सकता है:

Kotlin

MediaController.Builder(context, sessionToken)
    .setListener(
      object : MediaController.Listener {
        override fun onCustomCommand(
          controller: MediaController,
          command: SessionCommand,
          args: Bundle,
        ): ListenableFuture<SessionResult> {
          // Handle custom command.
          return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
        }

        override fun onDisconnected(controller: MediaController) {
          // Handle disconnection.
        }
      }
    )
    .buildAsync()

Java

new MediaController.Builder(context, sessionToken)
    .setListener(
        new MediaController.Listener() {
          @Override
          public ListenableFuture<SessionResult> onCustomCommand(
              MediaController controller, SessionCommand command, Bundle args) {
            // Handle custom command.
            return Futures.immediateFuture(new SessionResult(SessionResult.RESULT_SUCCESS));
          }

          @Override
          public void onDisconnected(MediaController controller) {
            // Handle disconnection.
          }
        })
    .buildAsync();

अन्य कॉम्पोनेंट की तरह ही, जब MediaController की ज़रूरत न हो, तब उसे रिलीज़ करना न भूलें. जैसे, Activity या Fragment के onStop() तरीके में.

Kotlin

MediaController.releaseFuture(controllerFuture)

Java

MediaController.releaseFuture(controllerFuture);

कंट्रोलर को रिलीज़ करने पर भी, सेशन को भेजी गई सभी प्रोसेस नहीं की गई कमांड डिलीवर की जाएंगी. साथ ही, सेशन सेवा से सिर्फ़ तब अनबाइंड किया जाएगा, जब इन कमांड को हैंडल कर लिया गया हो या टाइमआउट की अवधि खत्म हो गई हो. इनमें से जो भी पहले होगा.

MediaBrowser

MediaBrowser, MediaController की सुविधाओं के साथ-साथ मीडिया ऐप्लिकेशन के MediaLibraryService की मीडिया लाइब्रेरी को ब्राउज़ करने की सुविधा भी देता है.

एक MediaBrowser बनाएं

Kotlin

val browserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
browserFuture.addListener({
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaBrowser> browserFuture =
  new MediaBrowser.Builder(context, sessionToken).buildAsync();
browserFuture.addListener(() -> {
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor());

MediaBrowser का इस्तेमाल करना

मीडिया ऐप्लिकेशन की कॉन्टेंट लाइब्रेरी ब्राउज़ करने के लिए, सबसे पहले getLibraryRoot() का इस्तेमाल करके रूट नोड पाएं:

Kotlin

// Get the library root to start browsing the library tree.
val rootFuture = mediaBrowser.getLibraryRoot(/* params= */ null)
rootFuture.addListener({
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor())

Java

// Get the library root to start browsing the library tree.
ListenableFuture<LibraryResult<MediaItem>> rootFuture =
  mediaBrowser.getLibraryRoot(/* params= */ null);
rootFuture.addListener(() -> {
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor());

इसके बाद, मीडिया लाइब्रेरी में मौजूद MediaItem के बच्चों को getChildren() की मदद से वापस पाकर, मीडिया लाइब्रेरी में नेविगेट किया जा सकता है. उदाहरण के लिए, रूट नोड MediaItem के बच्चों को वापस पाने के लिए:

Kotlin

// Get the library root to start browsing the library tree.
val childrenFuture = 
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Int.MAX_VALUE, null)
childrenFuture.addListener({
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor())

Java

ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> childrenFuture =
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Integer.MAX_VALUE, null);
childrenFuture.addListener(() -> {
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor());

किसी दूसरे मीडिया ऐप्लिकेशन के लिए, प्लेबैक कंट्रोल दिखाना

किसी दूसरे मीडिया ऐप्लिकेशन के लिए बटन वाले यूज़र इंटरफ़ेस (यूआई) कंट्रोल दिखाते समय, यह ज़रूरी है कि उस ऐप्लिकेशन के लिए, मीडिया बटन की तय की गई सेटिंग का पालन किया जाए.

अपने यूज़र इंटरफ़ेस (यूआई) की सीमाओं और ज़रूरी शर्तों के हिसाब से, ऐप्लिकेशन की प्राथमिकताओं को सेट करने के लिए CommandButton.DisplayConstraints का इस्तेमाल करें. यूज़र इंटरफ़ेस (यूआई) की सीमाओं और पाबंदियों को तय किया जा सकता है. साथ ही, resolve तरीके से, आइकॉन, पोज़िशन, और ज़रूरी कार्रवाई के साथ दिखाने के लिए बटनों की सूची दी जा सकती है. अगर कोई उपयोगकर्ता इनमें से किसी बटन पर क्लिक करता है, तो मीडिया ऐप्लिकेशन में इससे जुड़ी कार्रवाई को ट्रिगर करने के लिए, CommandButton.executeAction का इस्तेमाल किया जा सकता है.

Kotlin

// Get media button preferences from media app
val mediaButtonPreferences = controller.getMediaButtonPreferences()
// Declare constraints of UI (example: limit overflow button to one)
val displayConstraints =
  DisplayConstraints.Builder().setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1).build()
// Resolve media app preferences with constraints
val resolvedButtons = displayConstraints.resolve(mediaButtonPreferences, controller)
// Display buttons in UI
for (button in resolvedButtons) {
  generateUiButton(
    uiPosition = button.slots[0],
    icon = getIconRes(button.icon),
    onClick = { button.executeAction(controller) },
  )
}

Java

// Get media button preferences from media app
List<CommandButton> mediaButtonPreferences = controller.getMediaButtonPreferences();
// Declare constraints of UI (example: limit overflow button to one)
DisplayConstraints displayConstraints =
    new DisplayConstraints.Builder()
        .setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1)
        .build();
// Resolve media app preferences with constraints
List<CommandButton> resolvedButtons =
    displayConstraints.resolve(mediaButtonPreferences, controller);
// Display buttons in UI
for (CommandButton button : resolvedButtons) {
  generateUiButton(
      /* uiPosition= */ button.slots.get(0),
      /* icon= */ getIconRes(button.icon),
      /* onClick= */ () -> button.executeAction(controller));
}