این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

کنترل پخش را فعال کنید

برای فعال کردن پخش رسانه در 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 برای برنامه خود، این شئ callback را ایجاد می‌کنید. بخش بعدی نحوه پیاده سازی این شی را مورد بحث قرار می دهد.

اجرای دستورات بازی

هنگامی که کاربری از برنامه شما درخواست پخش برای یک مورد رسانه ای می کند، سیستم عامل Android Automotive و Android Auto از کلاس MediaSessionCompat.Callback از شی MediaSessionCompat برنامه شما که از سرویس مرورگر رسانه برنامه شما دریافت کرده اند استفاده می کنند. وقتی کاربر می‌خواهد بازپخش محتوا را کنترل کند، مانند توقف پخش یا پرش به آهنگ بعدی، Android Auto و Android Automotive OS یکی از روش‌های شی پاسخ تماس را فراخوانی می‌کنند.

برای مدیریت بازپخش محتوا، برنامه شما باید کلاس MediaSessionCompat.Callback انتزاعی را گسترش دهد و روش هایی را که برنامه شما پشتیبانی می کند پیاده سازی کند.

هر یک از این روش های پاسخ به تماس را که برای نوع محتوای ارائه شده توسط برنامه شما منطقی است، پیاده سازی کنید:

onPrepare: هنگامی که منبع رسانه تغییر می کند AAOS این روش را فراخوانی می کند.
onPlay: زمانی که کاربر بازی را بدون انتخاب یک آیتم خاص انتخاب می کند، فراخوانی می شود. برنامه شما باید محتوای پیش‌فرض خود را پخش کند یا اگر پخش با onPause متوقف شد، برنامه شما پخش را از سر می‌گیرد.
توجه: وقتی سیستم عامل Android Automotive یا Android Auto به سرویس مرورگر رسانه متصل می شود، برنامه شما نباید به طور خودکار شروع به پخش موسیقی کند. برای کسب اطلاعات بیشتر، به تنظیم اولیه PlaybackState مراجعه کنید.
onPlayFromMediaId: هنگامی که کاربر انتخاب می کند یک آیتم خاص را پخش کند فراخوانی می شود. این روش شناسه ای را دریافت می کند که سرویس مرورگر رسانه شما به آیتم رسانه در سلسله مراتب محتوا اختصاص داده است.
onPlayFromSearch: هنگامی که کاربر بازی را از یک عبارت جستجو انتخاب می کند، فراخوانی می شود. برنامه باید بر اساس رشته جستجوی ارسال شده انتخاب مناسبی داشته باشد.
onPause: زمانی که کاربر توقف پخش را انتخاب می کند، فراخوانی می شود.
onSkipToNext: هنگامی که کاربر انتخاب می کند به مورد بعدی پرش کند، فراخوانی می شود.
onSkipToPrevious: هنگامی که کاربر انتخاب می کند به مورد قبلی پرش کند، فراخوانی می شود.
onStop: زمانی فراخوانی می شود که کاربر تصمیم می گیرد بازی را متوقف کند. برای ارائه نتیجه انتخابی، این روش ها را در برنامه خود نادیده بگیرید. اگر روشی توسط برنامه شما پشتیبانی نمی شود، نیازی به پیاده سازی آن ندارید. به عنوان مثال، اگر برنامه شما یک پخش زنده مانند پخش ورزشی پخش می کند، نیازی به پیاده سازی onSkipToNext ندارید. در عوض، از پیاده سازی پیش فرض onSkipToNext استفاده کنید.

برنامه شما برای پخش محتوا از طریق بلندگوهای خودرو نیازی به منطق خاصی ندارد. هنگامی که برنامه شما درخواستی برای پخش محتوا دریافت می کند، صدا را به همان روشی پخش می کند که محتوا از طریق بلندگوها یا هدفون های تلفن کاربر پخش می شود. Android Auto و AAOS به طور خودکار محتوای صوتی را به سیستم خودرو ارسال می کنند تا از طریق بلندگوهای خودرو پخش شود.

برای کسب اطلاعات بیشتر در مورد پخش محتوای صوتی، به نمای کلی Media Player ، نمای کلی برنامه صوتی و نمای کلی ExoPlayer مراجعه کنید.

عملکردهای پخش استاندارد را تنظیم کنید

Android Auto و AAOS کنترل‌های پخش را بر اساس اقداماتی که در شی PlaybackStateCompat فعال می‌شوند، نمایش می‌دهند. به طور پیش فرض، برنامه شما باید از اقدامات زیر پشتیبانی کند:

اگر برنامه شما با محتوای برنامه مرتبط باشد، می‌تواند از اقدامات زیر نیز پشتیبانی کند:

علاوه بر این، می توانید به صورت اختیاری یک صف پخش برای نمایش برای کاربر ایجاد کنید. برای انجام این کار، متدهای setQueue و setQueueTitle را فراخوانی کنید، عمل ACTION_SKIP_TO_QUEUE_ITEM فعال کنید و بازگشت به تماس را onSkipToQueueItem تعریف کنید.

همچنین، پشتیبانی از نماد Now playing را اضافه کنید، که نشانگر چیزی است که در حال پخش است. برای این کار متد setActiveQueueItemId را فراخوانی کنید و شناسه آیتم در حال پخش را در صف ارسال کنید. هر زمان که صف تغییر کرد، باید setActiveQueueItemId به روز کنید.

دکمه های نمایش Android Auto و AAOS برای هر عملکرد فعال و همچنین صف پخش. هنگامی که کاربران روی این دکمه ها کلیک می کنند، سیستم پاسخ تماس مربوطه را از MediaSessionCompat.Callback فراخوانی می کند.

فضای بلا استفاده را رزرو کنید

Android Auto و AAOS برای کنش‌های ACTION_SKIP_TO_PREVIOUS و ACTION_SKIP_TO_NEXT فضایی در UI رزرو می‌کنند. اگر برنامه شما یکی از این عملکردها را پشتیبانی نمی‌کند، 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 اقدامات سفارشی را به کنترل های حمل و نقل اضافه می کند. در غیر این صورت، اقدامات سفارشی در منوی Overflow ظاهر می شوند. Android اقدامات سفارشی را به ترتیبی که آنها را به PlaybackStateCompat اضافه می‌کنید نمایش می‌دهد.

از اقدامات سفارشی برای ارائه رفتار متمایز از اقدامات استاندارد استفاده کنید. از آنها برای جایگزینی یا تکرار اقدامات استاندارد استفاده نکنید.

برای افزودن اقدامات سفارشی، از متد addCustomAction در کلاس PlaybackStateCompat.Builder استفاده کنید. این قطعه کد نحوه افزودن یک اقدام سفارشی را به "شروع یک کانال رادیویی" نشان می دهد:

کاتلین

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());

برای مثال دقیق تر از این روش، روش setCustomAction را در برنامه نمونه برنامه پخش موسیقی جهانی اندروید در GitHub ببینید. پس از ایجاد کنش سفارشی خود، جلسه رسانه شما می تواند با نادیده گرفتن روش 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)) {
        ...
    }
}

برای کسب اطلاعات بیشتر، به روش onCustomAction در برنامه نمونه برنامه پخش موسیقی جهانی اندروید در GitHub مراجعه کنید.

آیکون هایی برای اقدامات سفارشی ایجاد کنید

هر اقدام سفارشی که ایجاد می کنید به یک نماد نیاز دارد.

اگر توضیحات آن نماد با یکی از ثابت‌های CommandButton.ICON_ مطابقت دارد، مقدار صحیح را برای کلید EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT از موارد اضافی اقدام سفارشی تنظیم کنید. در سیستم‌های پشتیبانی‌شده، انجام این کار منبع نماد ارسال شده به CustomAction.Builder را لغو می‌کند و به اجزای سیستم اجازه می‌دهد تا کنش شما و سایر اقدامات بازپخش را به‌طور مداوم ارائه کنند.

همچنین باید یک منبع آیکون را مشخص کنید. برنامه‌های موجود در خودروها می‌توانند در اندازه‌ها و تراکم‌های مختلف صفحه نمایش اجرا شوند، بنابراین نمادهایی که ارائه می‌دهید باید بصورت برداری قابل ترسیم باشند. از یک بردار قابل ترسیم برای مقیاس‌بندی دارایی‌ها بدون از دست دادن جزئیات استفاده کنید. یک وکتور قابل ترسیم می‌تواند لبه‌ها و گوشه‌ها را با مرزهای پیکسل در وضوح‌های کوچک‌تر تراز کند.

اگر یک کنش سفارشی حالت دار است (اگر تنظیم پخش را روشن یا خاموش می کند)، نمادهای مختلفی را برای حالت های مختلف ارائه دهید تا به کاربران کمک کند هنگام انتخاب کنش، تغییری را مشاهده کنند.

سبک‌های نماد جایگزین را برای اقدامات غیرفعال ارائه کنید

هنگامی که یک اقدام سفارشی برای زمینه فعلی در دسترس نیست، نماد اقدام سفارشی را با نماد جایگزینی که عملکرد را غیرفعال نشان می‌دهد تعویض کنید.

فرمت صوتی را مشخص کنید

برای نشان دادن اینکه رسانه پخش از فرمت صوتی خاصی استفاده می کند، می توانید نمادهایی را مشخص کنید که در خودروهایی که از این ویژگی پشتیبانی می کنند ارائه می شوند. می‌توانید KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI و KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI را در بسته‌های اضافی آیتم رسانه در حال پخش تنظیم کنید (به MediaSession.setMetadata منتقل شده است). هر دو مورد اضافی را برای قرار دادن طرح‌بندی‌های مختلف تنظیم کنید.

علاوه بر این، می‌توانید KEY_IMMERSIVE_AUDIO اضافی را تنظیم کنید تا به OEM‌های خودرو بگوید که این صدای همهجانبه است، و آنها باید هنگام تصمیم‌گیری در مورد اعمال جلوه‌های صوتی که ممکن است با محتوای فراگیر تداخل ایجاد کنند، بسیار مراقب باشند.

پیوندهایی را از مورد در حال پخش اضافه کنید

می توانید آیتم رسانه در حال پخش را طوری پیکربندی کنید که زیرنویس، توضیحات یا هر دو پیوندی به سایر موارد رسانه باشد. که به کاربر اجازه می دهد سریع به موارد مرتبط بپرد. برای مثال، آنها ممکن است به آهنگ های دیگری از همان هنرمند یا قسمت های دیگر یک پادکست بپرند. اگر خودرو از این ویژگی پشتیبانی می‌کند، کاربران می‌توانند برای مرور آن محتوا روی پیوند ضربه بزنند.

برای افزودن پیوندها، فراداده KEY_SUBTITLE_LINK_MEDIA_ID (برای پیوند از زیرنویس) یا KEY_DESCRIPTION_LINK_MEDIA_ID (برای پیوند از توضیحات) پیکربندی کنید. برای جزئیات، به مستندات مرجع برای آن فیلدهای فراداده مراجعه کنید.

کنترل پخش را فعال کنید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

ثبت یک جلسه رسانه ای

کاتلین

جاوا

اجرای دستورات بازی

عملکردهای پخش استاندارد را تنظیم کنید

فضای بلا استفاده را رزرو کنید

PlaybackState اولیه را تنظیم کنید

اقدامات پخش سفارشی را اضافه کنید

کاتلین

جاوا

کاتلین

جاوا

آیکون هایی برای اقدامات سفارشی ایجاد کنید

سبک‌های نماد جایگزین را برای اقدامات غیرفعال ارائه کنید

فرمت صوتی را مشخص کنید

پیوندهایی را از مورد در حال پخش اضافه کنید

کنترل پخش را فعال کنید