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

Android Auto और Android Automotive OS (AAOS) में मीडिया चलाने की सुविधा चालू करने के लिए, मीडिया सेशन रजिस्टर करके और उसके कॉलबैक तरीकों को मैनेज करके, प्लेबैक कंट्रोल लागू करें. इस पेज पर, यह बताया गया है कि कैसे:

• अपनी मीडिया ब्राउज़र सेवा में MediaSessionCompat ऑब्जेक्ट रजिस्टर करें.

• उपयोगकर्ता के वीडियो चलाने के अनुरोधों का जवाब देने के लिए, MediaSessionCompat.Callback तरीके लागू करें.

• वीडियो चलाने के स्टैंडर्ड और कस्टम ऐक्शन कॉन्फ़िगर करें.

• अपने मीडिया सेशन के लिए, मीडिया चलाने की शुरुआती स्थिति सेट करें.

• ऑडियो फ़ॉर्मैट के बारे में बताने के लिए आइकॉन जोड़ें.

• अभी चल रहे मीडिया आइटम से लिंक बनाएं.

Android Auto और AAOS, आपकी सेवा के लिए MediaSessionCompat के ज़रिए, मीडिया चलाने से जुड़े कंट्रोल के निर्देश भेजते हैं. आपको एक सेशन रजिस्टर करना होगा और उससे जुड़े कॉलबैक तरीके लागू करने होंगे.

मीडिया सेशन रजिस्टर करना

मीडिया ब्राउज़र सेवा के onCreate तरीके में, MediaSessionCompat का एक इंस्टेंस बनाएं. इसके बाद, मीडिया सेशन रजिस्टर करने के लिए setSessionToken को कॉल करें. इस कोड स्निपेट में, मीडिया सेशन बनाने और रजिस्टर करने का तरीका बताया गया है:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

मीडिया सेशन ऑब्जेक्ट बनाते समय, आपको एक कॉलबैक ऑब्जेक्ट सेट करना होता है. इसका इस्तेमाल, प्लेबैक कंट्रोल के अनुरोधों को मैनेज करने के लिए किया जाता है. इस कॉलबैक ऑब्जेक्ट को बनाने के लिए, आपको अपने ऐप्लिकेशन के लिए MediaSessionCompat.Callback क्लास का इस्तेमाल करना होगा. अगले सेक्शन में, इस ऑब्जेक्ट को लागू करने का तरीका बताया गया है.

गाने चलाने से जुड़े निर्देश लागू करना

जब कोई उपयोगकर्ता आपके ऐप्लिकेशन से किसी मीडिया आइटम को चलाने का अनुरोध करता है, तो Android Automotive OS और Android Auto, आपके ऐप्लिकेशन के MediaSessionCompat ऑब्जेक्ट से MediaSessionCompat.Callback क्लास का इस्तेमाल करते हैं. यह ऑब्जेक्ट, उन्हें आपके ऐप्लिकेशन की मीडिया ब्राउज़र सेवा से मिलता है. जब कोई उपयोगकर्ता कॉन्टेंट चलाने की सुविधा को कंट्रोल करना चाहता है, जैसे कि कॉन्टेंट को रोकना या अगले ट्रैक पर जाना, तो Android Auto और Android Automotive OS, कॉलबैक ऑब्जेक्ट के किसी एक तरीके को शुरू करते हैं.

कॉन्टेंट चलाने की सुविधा को मैनेज करने के लिए, आपके ऐप्लिकेशन को ऐब्स्ट्रैक्ट MediaSessionCompat.Callback क्लास को एक्सटेंड करना होगा. साथ ही, उन तरीकों को लागू करना होगा जिन्हें आपका ऐप्लिकेशन सपोर्ट करता है.

अपने ऐप्लिकेशन में उपलब्ध कॉन्टेंट के हिसाब से, इनमें से हर कॉलबैक तरीके को लागू करें:

onPrepare

मीडिया सोर्स बदलने पर, AAOS इस तरीके को लागू करता है.

onPlay

जब उपयोगकर्ता किसी आइटम को चुने बिना 'चलाएं' विकल्प चुनता है, तब इस इंटेंट को शुरू किया जाता है. आपके ऐप्लिकेशन को डिफ़ॉल्ट कॉन्टेंट चलाना चाहिए. अगर onPause बटन से प्लेबैक रोका गया था, तो आपके ऐप्लिकेशन को प्लेबैक फिर से शुरू करना चाहिए.

onPlayFromMediaId

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

onPlayFromSearch

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

onPause

इस फ़ंक्शन को तब कॉल किया जाता है, जब उपयोगकर्ता वीडियो चलाने की सुविधा को रोकना चाहता है.

onSkipToNext

जब उपयोगकर्ता अगले आइटम पर जाने का विकल्प चुनता है, तब इस फ़ंक्शन को कॉल किया जाता है.

onSkipToPrevious

जब उपयोगकर्ता पिछले आइटम पर जाने का विकल्प चुनता है, तब इस फ़ंक्शन को कॉल किया जाता है.

onStop

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

कार के स्पीकर से कॉन्टेंट चलाने के लिए, आपके ऐप्लिकेशन को किसी खास लॉजिक की ज़रूरत नहीं होती. जब आपके ऐप्लिकेशन को कॉन्टेंट चलाने का अनुरोध मिलता है, तो वह ऑडियो को उसी तरह से चलाता है जिस तरह से कॉन्टेंट को उपयोगकर्ता के फ़ोन के स्पीकर या हेडफ़ोन से चलाया जाता है. Android Auto और AAOS, ऑडियो कॉन्टेंट को कार के सिस्टम पर अपने-आप भेजते हैं, ताकि उसे कार के स्पीकर पर चलाया जा सके.

ऑडियो कॉन्टेंट चलाने के बारे में ज़्यादा जानने के लिए, मीडिया प्लेयर के बारे में खास जानकारी, ऑडियो ऐप्लिकेशन के बारे में खास जानकारी, और ExoPlayer के बारे में खास जानकारी देखें.

स्टैंडर्ड प्लेबैक ऐक्शन सेट करना

Android Auto और AAOS, PlaybackStateCompat ऑब्जेक्ट में चालू की गई कार्रवाइयों के आधार पर, प्लेबैक कंट्रोल दिखाते हैं. डिफ़ॉल्ट रूप से, आपके ऐप्लिकेशन में ये कार्रवाइयां की जा सकती हों:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

अगर ये कार्रवाइयां ऐप्लिकेशन के कॉन्टेंट से जुड़ी हैं, तो आपका ऐप्लिकेशन इन्हें भी सपोर्ट कर सकता है:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

इसके अलावा, आपके पास उपयोगकर्ता को दिखाने के लिए, एक प्ले क्यू बनाने का विकल्प भी होता है. इसके लिए, setQueue और setQueueTitle तरीकों को कॉल करें. साथ ही, ACTION_SKIP_TO_QUEUE_ITEM कार्रवाई को चालू करें और कॉलबैक onSkipToQueueItem को तय करें.

साथ ही, अभी चल रहा है आइकॉन के लिए भी सहायता जोड़ें. यह आइकॉन, यह दिखाता है कि क्या चल रहा है. ऐसा करने के लिए, setActiveQueueItemId तरीके को कॉल करें और कतार में चल रहे आइटम का आईडी पास करें. जब भी कतार में कोई बदलाव हो, तब आपको setActiveQueueItemId अपडेट करना होगा.

Android Auto और AAOS, चालू की गई हर कार्रवाई के साथ-साथ प्लेबैक क्यू के लिए बटन दिखाते हैं. जब उपयोगकर्ता इन बटन पर क्लिक करते हैं, तो सिस्टम MediaSessionCompat.Callback से जुड़े कॉलबैक को शुरू करता है.

इस्तेमाल नहीं किया गया स्पेस रिज़र्व करना

Android Auto और AAOS, यूज़र इंटरफ़ेस (यूआई) में ACTION_SKIP_TO_PREVIOUS और ACTION_SKIP_TO_NEXT कार्रवाइयों के लिए जगह रिज़र्व करते हैं. अगर आपका ऐप्लिकेशन इनमें से किसी एक फ़ंक्शन के साथ काम नहीं करता है, तो Android Auto और AAOS इस जगह का इस्तेमाल, आपकी बनाई गई कस्टम कार्रवाइयां दिखाने के लिए करते हैं.

अगर आपको उन जगहों पर कस्टम ऐक्शन नहीं दिखाने हैं, तो उन्हें रिज़र्व किया जा सकता है. इससे Android Auto और AAOS, उन जगहों को खाली छोड़ देंगे. ऐसा तब होगा, जब आपका ऐप्लिकेशन उस फ़ंक्शन के साथ काम नहीं करेगा.

इसके लिए, setExtras तरीके को कॉल करें. इसमें एक ऐसा एक्स्ट्रा बंडल शामिल होता है जिसमें रिज़र्व किए गए फ़ंक्शन से जुड़े कॉन्स्टेंट होते हैं. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT, ACTION_SKIP_TO_NEXT के बराबर है. वहीं, SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV, ACTION_SKIP_TO_PREVIOUS के बराबर है. इन कॉन्स्टेंट का इस्तेमाल बंडल में कुंजियों के तौर पर करें. साथ ही, बूलियन true का इस्तेमाल वैल्यू के तौर पर करें.

शुरुआती PlaybackState सेट करना

Android Auto और AAOS, मीडिया ब्राउज़र सेवा से कम्यूनिकेट करते हैं. इसलिए, मीडिया सेशन PlaybackStateCompat का इस्तेमाल करके, कॉन्टेंट चलाने की स्थिति के बारे में बताता है.

AAOS या Android Auto के आपकी मीडिया ब्राउज़र सेवा से कनेक्ट होने पर, आपका ऐप्लिकेशन अपने-आप संगीत चलाना शुरू नहीं करना चाहिए. इसके बजाय, कार की स्थिति या उपयोगकर्ता की कार्रवाइयों के आधार पर, वीडियो को फिर से चलाने या शुरू करने के लिए, Android Auto और AAOS पर भरोसा करें.

इसके लिए, अपने मीडिया सेशन की शुरुआती PlaybackStateCompat को STATE_STOPPED, STATE_PAUSED, STATE_NONE या STATE_ERROR पर सेट करें.

Android Auto और AAOS में मीडिया सेशन सिर्फ़ ड्राइव के दौरान चलते हैं. इसलिए, उपयोगकर्ता इन सेशन को अक्सर शुरू और बंद करते हैं. ड्राइव के बीच बेहतर अनुभव देने के लिए, उपयोगकर्ता के पिछले सेशन की स्थिति को ट्रैक करें. इससे जब मीडिया ऐप्लिकेशन को फिर से शुरू करने का अनुरोध मिलता है, तो उपयोगकर्ता अपने-आप वहीं से शुरू कर सकता है जहां उसने छोड़ा था. उदाहरण के लिए, आखिरी बार चलाया गया मीडिया आइटम, PlaybackStateCompat, और कतार.

कस्टम प्लेबैक ऐक्शन जोड़ना

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

स्टैंडर्ड कार्रवाइयों से अलग व्यवहार दिखाने के लिए, कस्टम कार्रवाइयों का इस्तेमाल करें. इनका इस्तेमाल, स्टैंडर्ड ऐक्शन को बदलने या डुप्लीकेट करने के लिए न करें.

कस्टम ऐक्शन जोड़ने के लिए, PlaybackStateCompat.Builder क्लास में addCustomAction तरीके का इस्तेमाल करें. इस कोड स्निपेट में, "रेडियो चैनल शुरू करें" सुविधा में कस्टम ऐक्शन जोड़ने का तरीका बताया गया है:

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

इस तरीके का ज़्यादा जानकारी वाला उदाहरण देखने के लिए, GitHub पर Universal Android Music Player के सैंपल ऐप्लिकेशन में setCustomAction तरीका देखें. कस्टम ऐक्शन बनाने के बाद, आपका मीडिया सेशन onCustomAction तरीके को बदलकर, कार्रवाइयों का जवाब दे सकता है.

इस कोड स्निपेट में दिखाया गया है कि "रेडियो चैनल शुरू करें" कार्रवाई के लिए, आपका ऐप्लिकेशन कैसे जवाब दे सकता है:

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

ज़्यादा जानने के लिए, GitHub पर Universal Android Music Player के सैंपल ऐप्लिकेशन में onCustomAction तरीका देखें.

कस्टम कार्रवाइयों के लिए आइकॉन बनाना

बनाई गई हर कस्टम कार्रवाई के लिए, एक आइकॉन की ज़रूरत होती है.

अगर उस आइकॉन की जानकारी, CommandButton.ICON_ कॉन्स्टेंट में से किसी एक से मेल खाती है, तो कस्टम ऐक्शन के extras की EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT कुंजी के लिए पूर्णांक वैल्यू सेट करें. जिन सिस्टम पर यह सुविधा काम करती है उन पर ऐसा करने से, CustomAction.Builder को पास की गई आइकॉन रिसॉर्स की जगह यह आइकॉन इस्तेमाल किया जाता है. इससे सिस्टम कॉम्पोनेंट, आपकी कार्रवाई और वीडियो चलाने से जुड़ी अन्य कार्रवाइयों को लगातार रेंडर कर पाते हैं.

आपको एक आइकॉन रिसॉर्स भी तय करना होगा. कार में इस्तेमाल होने वाले ऐप्लिकेशन, अलग-अलग स्क्रीन साइज़ और डेंसिटी पर चल सकते हैं. इसलिए, आपके दिए गए आइकॉन वेक्टर ड्रॉएबल होने चाहिए. ज़्यादा जानकारी को बनाए रखते हुए ऐसेट को स्केल करने के लिए, ड्रॉ करने लायक वेक्टर का इस्तेमाल करें. ड्रॉ करने लायक वेक्टर, छोटे रिज़ॉल्यूशन पर पिक्सल की सीमाओं के हिसाब से किनारों और कोनों को अलाइन कर सकता है.

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

बंद की गई कार्रवाइयों के लिए, आइकॉन की अन्य स्टाइल उपलब्ध कराएं

अगर मौजूदा कॉन्टेक्स्ट के लिए कस्टम ऐक्शन उपलब्ध नहीं है, तो कस्टम ऐक्शन आइकॉन को ऐसे आइकॉन से बदलें जो ऐक्शन को बंद के तौर पर दिखाता हो.

ऑडियो फ़ॉर्मैट के बारे में जानकारी देना

यह बताने के लिए कि मीडिया चलाने के लिए खास ऑडियो फ़ॉर्मैट का इस्तेमाल किया जा रहा है, ऐसे आइकॉन तय किए जा सकते हैं जो इस सुविधा के साथ काम करने वाली कारों में रेंडर किए जाते हैं. मौजूदा समय में चल रहे मीडिया आइटम (MediaSession.setMetadata को पास किया गया) के एक्स्ट्रा बंडल में, KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI और KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI सेट किए जा सकते हैं. अलग-अलग लेआउट के हिसाब से, दोनों एक्स्ट्रा सेट करें.

इसके अलावा, KEY_IMMERSIVE_AUDIO एक्स्ट्रा सेट किया जा सकता है. इससे कार बनाने वाली कंपनियों को यह पता चलेगा कि यह इमर्सिव ऑडियो है. इसलिए, उन्हें ऑडियो इफ़ेक्ट लागू करते समय बहुत सावधानी बरतनी चाहिए, ताकि इमर्सिव कॉन्टेंट में कोई रुकावट न आए.

अभी चल रहे आइटम के लिंक जोड़ें

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

लिंक जोड़ने के लिए, KEY_SUBTITLE_LINK_MEDIA_ID मेटाडेटा (सबटाइटल से लिंक करने के लिए) या KEY_DESCRIPTION_LINK_MEDIA_ID (ब्यौरे से लिंक करने के लिए) कॉन्फ़िगर करें. ज़्यादा जानकारी के लिए, उन मेटाडेटा फ़ील्ड के रेफ़रंस दस्तावेज़ देखें.