प्लेयर इंटरफ़ेस

प्लेयर, आपके ऐप्लिकेशन का वह कॉम्पोनेंट होता है जो मीडिया आइटम चलाने में मदद करता है. Media3 Player इंटरफ़ेस, आम तौर पर प्लेयर से मैनेज की जाने वाली सुविधाओं के लिए एक आउटलाइन सेट अप करता है. इसमें ये शामिल हैं:

• प्लेबैक कंट्रोल पर असर डालना. जैसे, वीडियो चलाना, रोकना, और आगे-पीछे करना
• फ़िलहाल चल रहे मीडिया की प्रॉपर्टी के बारे में क्वेरी करना. जैसे, वीडियो चलाने की पोज़िशन
• मीडिया आइटम की प्लेलिस्ट/सूची को मैनेज करना
• वीडियो चलाने की प्रॉपर्टी कॉन्फ़िगर करना. जैसे, शफ़ल करना, दोहराना, स्पीड, और आवाज़
• स्क्रीन पर वीडियो रेंडर करना

Media3, Player इंटरफ़ेस को लागू करने की सुविधा भी देता है. इसे ExoPlayer कहा जाता है.

अहम जानकारी: अगर आपको ExoPlayer का इस्तेमाल करके मीडिया प्लेयर ऐप्लिकेशन बनाना है, तो Media3 ExoPlayer का इस्तेमाल करके बेसिक मीडिया प्लेयर ऐप्लिकेशन बनाना गाइड देखें.

कॉम्पोनेंट के बीच एक कॉमन इंटरफ़ेस

Media3 के कई कॉम्पोनेंट, प्लेयर इंटरफ़ेस को लागू करते हैं. उदाहरण के लिए:

कॉम्पोनेंट	ब्यौरा और व्यवहार से जुड़े नोट
ExoPlayer	यह एक मीडिया प्लेयर एपीआई है. साथ ही, यह Player इंटरफ़ेस का डिफ़ॉल्ट वर्शन है.
MediaController	वीडियो चलाने के निर्देश भेजने के लिए, MediaSession के साथ इंटरैक्ट करता है. अगर आपका Player और MediaSession, Service में है, जो Activity या Fragment से अलग है, जहां आपके प्लेयर का यूज़र इंटरफ़ेस (यूआई) मौजूद है, तो आपके पास MediaController को अपने यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट के लिए प्लेयर के तौर पर असाइन करने का विकल्प है. जैसे, PlayerView या Player कंपोज़ेबल. वीडियो चलाने और प्लेलिस्ट के तरीके के कॉल, MediaSession के ज़रिए आपके Player पर भेजे जाते हैं.
MediaBrowser	MediaController की सुविधाओं के अलावा, यह MediaLibrarySession के साथ इंटरैक्ट करता है, ताकि उपलब्ध मीडिया कॉन्टेंट को ब्राउज़ किया जा सके.
SimpleBasePlayer	Player को लागू करने का ऐसा तरीका जिससे लागू करने के तरीकों की संख्या कम से कम हो जाती है. यह तब मददगार होता है, जब आपको किसी कस्टम प्लेयर को MediaSession से कनेक्ट करना हो.
ForwardingSimpleBasePlayer	SimpleBasePlayer का एक सबक्लास, जिसे वीडियो चलाने की कार्रवाइयों को किसी दूसरे Player पर फ़ॉरवर्ड करने के लिए डिज़ाइन किया गया है. साथ ही, यह SimpleBasePlayer की तरह ही, एक जैसा व्यवहार करने वाले कस्टमाइज़ेशन की अनुमति देता है. इस क्लास का इस्तेमाल करके, वीडियो चलाने से जुड़ी कुछ कार्रवाइयों को दबाया या उनमें बदलाव किया जा सकता है.
RemoteCastPlayer	रिमोट Cast रिसीवर ऐप्लिकेशन पर वीडियो चलाने की सुविधा को कंट्रोल करने के लिए, Player को लागू करना.
CastPlayer	लोकल और रिमोट, दोनों तरह के Cast प्लेबैक को कंट्रोल करने के लिए, Player का इस्तेमाल किया जाता है.

हालांकि, MediaSession, Player इंटरफ़ेस को लागू नहीं करता है, लेकिन इसे बनाते समय Player की ज़रूरत होती है. इसका मकसद, अन्य प्रोसेस या थ्रेड से Player को ऐक्सेस देना है.

Media3 प्लेबैक आर्किटेक्चर

अगर आपके पास Player का ऐक्सेस है, तो वीडियो चलाने के निर्देश देने के लिए, आपको सीधे इसके तरीके इस्तेमाल करने चाहिए. MediaSession को लागू करके, प्लेबैक का विज्ञापन दिखाया जा सकता है. साथ ही, बाहरी सोर्स को प्लेबैक कंट्रोल करने की अनुमति दी जा सकती है. ये बाहरी सोर्स, MediaController को लागू करते हैं. इससे मीडिया सेशन से कनेक्ट करने और वीडियो चलाने के निर्देश के अनुरोध जारी करने में मदद मिलती है.

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

पहली इमेज: Player इंटरफ़ेस, Media3 के आर्किटेक्चर में अहम भूमिका निभाता है.

प्लेयर की स्थिति

Player इंटरफ़ेस को लागू करने वाले मीडिया प्लेयर की स्थिति में, मुख्य रूप से चार कैटगरी की जानकारी शामिल होती है:

1. वीडियो चलाने की स्थिति
   • getPlaybackState() की मदद से वापस पाएं.
   • इंटरफ़ेस से तय की गई स्टेट वैल्यू ये हैं: STATE_IDLE, STATE_BUFFERING, STATE_READY, और STATE_ENDED.
2. मीडिया आइटम की प्लेलिस्ट
   • वीडियो चलाने के लिए, MediaItem इंस्टेंस का क्रम.
   • getCurrentTimeline() की मदद से वापस पाएं
   • Player इंस्टेंस, प्लेलिस्ट से जुड़े ऑपरेशन के तरीके उपलब्ध करा सकते हैं. जैसे, MediaItem को जोड़ना या हटाना. साथ ही, getCurrentMediaItem() जैसे आसान तरीके भी उपलब्ध करा सकते हैं.
3. प्रॉपर्टी चलाने/रोकने की सुविधा, जैसे:
   • playWhenReady: इससे पता चलता है कि उपयोगकर्ता को मीडिया चलाना है या उसे रोके रखना है
   • वीडियो चलाने पर रोक लगाने की वजह: अगर लागू हो, तो वीडियो चलाने पर रोक लगाने की वजह का संकेत. भले ही, playWhenReady को true पर सेट किया गया हो
   • isPlaying: इससे पता चलता है कि प्लेयर में फ़िलहाल वीडियो चल रहा है या नहीं. यह सिर्फ़ तब true होगा, जब वीडियो चलाने की स्थिति STATE_READY हो, playWhenReady true हो, और वीडियो चलाने की सुविधा को दबाया न गया हो
4. वीडियो चलाने की स्थिति, जिसमें ये शामिल हैं:
   • मौजूदा मीडिया आइटम का इंडेक्स: प्लेलिस्ट में मौजूदा MediaItem का इंडेक्स.
   • isPlayingAd: इससे पता चलता है कि इंसर्ट किया गया विज्ञापन चल रहा है या नहीं.
   • वीडियो चलाने की मौजूदा जगह: मौजूदा MediaItem या डाले गए विज्ञापन में, वीडियो चलाने की मौजूदा जगह.

इसके अलावा, Player इंटरफ़ेस की मदद से, उपलब्ध ट्रैक, मीडिया मेटाडेटा, वीडियो चलाने की स्पीड, वॉल्यूम, और वीडियो चलाने से जुड़ी अन्य सहायक प्रॉपर्टी को ऐक्सेस किया जा सकता है.

ध्यान दें: Player के इंस्टेंस के लिए, इंटरफ़ेस की सभी सुविधाओं के साथ काम करना ज़रूरी नहीं है. उपलब्ध कमांड को देखकर यह पता लगाया जा सकता है कि कौनसी सुविधा काम करती है और किस तरीके को कॉल करने की अनुमति है.

बदलावों को सुनें

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

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

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

प्लेबैक कंट्रोल करना

Player इंटरफ़ेस, स्थिति में बदलाव करने और वीडियो चलाने को कंट्रोल करने के कई तरीके उपलब्ध कराता है:

• बुनियादी प्लेबैक कंट्रोल, जैसे कि play(), pause(), prepare(), और stop().
• प्लेलिस्ट से जुड़ी कार्रवाइयां, जैसे कि addMediaItem() या removeMediaItem().
• मौजूदा आइटम या पोज़िशन को बदलने के लिए, सीक करें.
• रिपीट मोड और शफ़ल मोड सेट करें.
• ट्रैक चुनने की सेटिंग अपडेट करें.
• वीडियो चलाने की स्पीड सेट करें.

ध्यान दें: Player के इंस्टेंस के लिए, इंटरफ़ेस की सभी सुविधाओं के साथ काम करना ज़रूरी नहीं है. उपलब्ध कमांड को देखकर यह पता लगाया जा सकता है कि कौनसी सुविधा काम करती है और किस तरीके को कॉल करने की अनुमति है.

कस्टम Player लागू करना

कस्टम प्लेयर बनाने के लिए, Media3 में शामिल SimpleBasePlayer को एक्सटेंड किया जा सकता है. यह क्लास, Player इंटरफ़ेस को लागू करने का बुनियादी तरीका उपलब्ध कराती है. इससे, आपको लागू करने के लिए ज़रूरी तरीकों की संख्या कम से कम करने में मदद मिलती है.

सबसे पहले, getState() तरीके को बदलें. इस तरीके को कॉल करने पर, प्लेयर की मौजूदा स्थिति की जानकारी अपने-आप भर जानी चाहिए. इसमें यह जानकारी शामिल है:

• उपलब्ध निर्देशों का सेट
• प्लेबैक की प्रॉपर्टी, जैसे कि वीडियो चलाने की स्थिति STATE_READY होने पर प्लेयर को वीडियो चलाना शुरू करना चाहिए या नहीं, फ़िलहाल चल रहे मीडिया आइटम का इंडेक्स, और मौजूदा आइटम में वीडियो चलाने की पोज़िशन

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 यह पक्का करेगा कि State को स्टेट वैल्यू के मान्य कॉम्बिनेशन के साथ बनाया गया हो. यह लिसनर को भी मैनेज करेगा और उन्हें स्थिति में होने वाले बदलावों की जानकारी देगा. अगर आपको स्थिति को मैन्युअल तरीके से अपडेट करना है, तो invalidateState() को कॉल करें.

getState() तरीके के अलावा, आपको सिर्फ़ उन तरीकों को लागू करना होगा जिनका इस्तेमाल उन निर्देशों के लिए किया जाता है जिनके बारे में आपका प्लेयर बताता है कि वे उपलब्ध हैं. ओवरराइड किए जा सकने वाले हैंडलर का वह तरीका ढूंढें जो आपको लागू करना है. उदाहरण के लिए, COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM और COMMAND_SEEK_TO_NEXT_MEDIA_ITEM जैसे ऑपरेशन के लिए, handleSeek() तरीके को बदलें.

Player को लागू करने के तरीके में बदलाव करना

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

अहम जानकारी: Player को स्वीकार करने वाले कॉम्पोनेंट के लिए, Robolectric या यूज़र इंटरफ़ेस (यूआई) टेस्ट लिखते समय, कस्टम टेस्ट स्टब लागू करने या Player का मॉक बनाने के बजाय, media3-test-utils में FakePlayer का इस्तेमाल करें. ज़्यादा जानकारी के लिए, FakePlayer की मदद से यूज़र इंटरफ़ेस (यूआई) और ऐप्लिकेशन के कॉम्पोनेंट की जांच करना लेख पढ़ें.