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

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

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

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

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

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

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

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

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 का इस्तेमाल करें. लिसनर बनाने और उसका इस्तेमाल करने का तरीका जानने के लिए, Player इवेंट पर ExoPlayer का दस्तावेज़ देखें.

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

Kotlin

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

Java

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

ऑडियो कंट्रोल करने का तरीक़ा

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

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

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

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

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

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

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

Kotlin

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // 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()
  }
}

Java

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

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // 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();
  }
}

SimpleBasePlayer यह पक्का करेगा कि State को राज्य की वैल्यू के मान्य कॉम्बिनेशन के साथ बनाया गया हो. यह दर्शकों को भी मैनेज करेगा और उन्हें स्थिति में हुए बदलावों के बारे में सूचना देगा. अगर आपको स्थिति से जुड़े अपडेट को मैन्युअल तरीके से ट्रिगर करना है, तो invalidateState() पर कॉल करें.

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