Oynatma kontrolünü etkinleştir

Android Auto ve Android Automotive OS'te (AAOS) medya oynatmayı etkinleştirmek için medya oturumu kaydedip geri çağırma yöntemlerini işleyerek oynatma kontrollerini uygulayın. Bu sayfada aşağıdakilerin nasıl yapılacağı açıklanmaktadır:

• Medya tarayıcı hizmetinize bir MediaSessionCompat nesnesi kaydedin.

• Kullanıcıların oynatma isteklerine yanıt vermek için MediaSessionCompat.Callback yöntemlerini uygulayın.

• Standart ve özel oynatma işlemlerini yapılandırın.

• Medya oturumunuz için ilk oynatma durumunu ayarlayın.

• Ses biçimini belirtmek için simgeler ekleyin.

• Etkin olarak oynatılan medya öğelerinden bağlantılar oluşturun.

Android Auto ve AAOS, hizmetiniz için MediaSessionCompat üzerinden oynatma kontrolü komutları gönderir. Bir oturum kaydetmeniz ve ilişkili geri çağırma yöntemlerini uygulamanız gerekir.

Medya oturumu kaydetme

Medya tarayıcı hizmetinizin onCreate yönteminde MediaSessionCompat örneği oluşturun, ardından medya oturumunu kaydetmek için setSessionToken'ı çağırın. Bu kod snippet'i, medya oturumunun nasıl oluşturulacağını ve kaydedileceğini gösterir:

Kotlin

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
    ...
}

Java

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

Medya oturumu nesnesini oluşturduğunuzda, oynatma kontrolü isteklerini işlemek için kullanılan bir geri çağırma nesnesi ayarlarsınız. Bu geri çağırma nesnesini, uygulamanız için MediaSessionCompat.Callback sınıfının bir uygulamasını sağlayarak oluşturursunuz. Sonraki bölümde, bu nesnenin nasıl uygulanacağı açıklanmaktadır.

Not: Medya oturumu çalıştırmasını incelemek için adb shell dumpsys media_session

Oynatma komutlarını uygulama

Bir kullanıcı uygulamanızdan bir medya öğesinin oynatılmasını istediğinde Android Automotive OS ve Android Auto, uygulamanızın medya tarayıcı hizmetinden elde ettikleri uygulamanızın MediaSessionCompat nesnesindeki MediaSessionCompat.Callback sınıfını kullanır. Kullanıcı, içerik oynatmayı kontrol etmek istediğinde (ör. oynatmayı duraklatma veya sonraki parçaya geçme) Android Auto ve Android Automotive OS, geri çağırma nesnesinin yöntemlerinden birini çağırır.

İçerik oynatmayı işlemek için uygulamanızın soyut MediaSessionCompat.Callback sınıfını genişletmesi ve uygulamanızın desteklediği yöntemleri uygulaması gerekir.

Uygulamanızın sunduğu içerik türü için anlamlı olan geri çağırma yöntemlerinin her birini uygulayın:

onPrepare

AAOS, medya kaynağı değiştiğinde bu yöntemi çağırır.

onPlay

Kullanıcı belirli bir öğe seçmeden oynatmayı seçtiğinde çağrılır. Uygulamanız, varsayılan içeriğini oynatmalı veya oynatma onPause ile duraklatıldıysa oynatmaya devam etmelidir.

Not: Android Automotive OS veya Android Auto, medya tarayıcı hizmetine bağlandığında uygulamanız otomatik olarak müzik çalmaya başlamamalıdır. Daha fazla bilgi için Set initial PlaybackState başlıklı makaleyi inceleyin.

onPlayFromMediaId

Kullanıcı belirli bir öğeyi oynatmayı seçtiğinde çağrılır. Yöntem, medya tarayıcı hizmetinizin içerik hiyerarşisindeki medya öğesine atadığı kimliği alır.

onPlayFromSearch

Kullanıcı, arama sorgusundan oynatmayı seçtiğinde çağrılır. Uygulama, iletilen arama dizesine göre uygun bir seçim yapmalıdır.

onPause

Kullanıcı oynatmayı duraklatmayı seçtiğinde çağrılır.

onSkipToNext

Kullanıcı bir sonraki öğeye geçmeyi seçtiğinde çağrılır.

onSkipToPrevious

Kullanıcı önceki öğeye atlamayı seçtiğinde çağrılır.

onStop

Kullanıcı oynatmayı durdurmayı seçtiğinde çağrılır. Seçilen sonucu sağlamak için bu yöntemleri uygulamanızda geçersiz kılın. Amacı uygulamanız tarafından desteklenmeyen bir yöntemi uygulamanız gerekmez. Örneğin, uygulamanız spor yayını gibi bir canlı yayın oynatıyorsa onSkipToNext yöntemini uygulamanız gerekmez. Bunun yerine, onSkipToNext için varsayılan uygulamayı kullanın.

Uygulamanızın, içeriği arabanın hoparlörlerinden çalmak için özel bir mantığa ihtiyacı yoktur. Uygulamanız içerik oynatma isteği aldığında sesi, içeriğin kullanıcının telefon hoparlörleri veya kulaklıkları aracılığıyla oynatıldığı şekilde oynatır. Android Auto ve AAOS, ses içeriğini arabanın hoparlörlerinden çalınması için otomatik olarak arabanın sistemine gönderir.

Ses içeriği oynatma hakkında daha fazla bilgi edinmek için Medya oynatıcıya genel bakış, Ses uygulamasına genel bakış ve ExoPlayer'a genel bakış başlıklı makaleleri inceleyin.

Standart oynatma işlemlerini ayarlama

Android Auto ve AAOS, oynatma kontrollerini PlaybackStateCompat nesnesinde etkinleştirilen işlemlere göre gösterir. Uygulamanız varsayılan olarak aşağıdaki işlemleri desteklemelidir:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

Uygulamanız, içeriğiyle alakalı olması durumunda aşağıdaki işlemleri de destekleyebilir:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Ayrıca, kullanıcıya gösterilecek bir oynatma sırası da oluşturabilirsiniz. Bunu yapmak için setQueue ve setQueueTitle yöntemlerini çağırın, ACTION_SKIP_TO_QUEUE_ITEM işlemini etkinleştirin ve geri çağırmayı onSkipToQueueItem tanımlayın.

Ayrıca, neyin çaldığını gösteren Ne çalıyor? simgesi için destek ekleyin. Bunu yapmak için setActiveQueueItemId yöntemini çağırın ve kuyrukta oynatılan öğenin kimliğini iletin. Kuyrukta değişiklik olduğunda setActiveQueueItemId güncellemeniz gerekir.

Not: Çalınan şarkılar simgesi için destek eklemek yalnızca oynatma sırası desteklenirken gereklidir.

Android Auto ve AAOS, etkinleştirilen her işlem için düğmelerin yanı sıra oynatma sırasını da gösterir. Kullanıcılar bu düğmeleri tıkladığında sistem, MediaSessionCompat.Callback'daki ilgili geri çağırmayı başlatır.

Kullanılmayan alanı ayırma

Android Auto ve AAOS, kullanıcı arayüzünde ACTION_SKIP_TO_PREVIOUS ve ACTION_SKIP_TO_NEXT işlemleri için yer ayırır. Uygulamanız bu işlevlerden birini desteklemiyorsa Android Auto ve AAOS, oluşturduğunuz özel işlemleri göstermek için bu alanı kullanır.

Bu alanları özel işlemlerle doldurmak istemiyorsanız Android Auto ve AAOS'in, uygulamanız ilgili işlevi desteklemediğinde alanı boş bırakması için bu alanları ayırabilirsiniz.

Bunu yapmak için setExtras yöntemini, ayrılmış işlevlere karşılık gelen sabitleri içeren bir ekstralar paketiyle çağırın. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT, ACTION_SKIP_TO_NEXT'e, SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV ise ACTION_SKIP_TO_PREVIOUS'e karşılık gelir. Bu sabitleri pakette anahtar olarak, boole değerini true değer olarak kullanın.

İlk PlaybackState'i ayarlama

Android Auto ve AAOS, medya tarayıcı hizmetinizle iletişim kurarken medya oturumunuz, PlaybackStateCompat kullanarak içerik oynatma durumunu bildirir.

AAOS veya Android Auto, medya tarayıcı hizmetinize bağlandığında uygulamanız müziği otomatik olarak çalmaya başlamamalıdır. Bunun yerine, arabanın durumuna veya kullanıcı işlemlerine göre oynatmayı devam ettirmek ya da başlatmak için Android Auto ve AAOS'u kullanın.

Bunu yapmak için medya oturumunuzun ilk PlaybackStateCompat değerini STATE_STOPPED, STATE_PAUSED, STATE_NONE veya STATE_ERROR olarak ayarlayın.

Not: PlaybackStateCompat, STATE_NONE olarak ayarlandığında Android Auto ve AAOS, oynatma kullanıcı arayüzüne erişimi engeller. Bu durumu yalnızca uygulamada oynatılacak bir içerik olmadığında ve kullanıcının oynatmayı başlatmak için yeni içerik seçmesi gerektiğinde gönderin.

Android Auto ve AAOS'teki medya oturumları yalnızca sürüş süresi boyunca devam eder. Bu nedenle kullanıcılar bu oturumları sık sık başlatır ve durdurur. Sürücüler arasında sorunsuz bir deneyim sağlamak için kullanıcının önceki oturum durumunu takip edin. Böylece, medya uygulaması devam ettirme isteği aldığında kullanıcı kaldığı yerden otomatik olarak devam edebilir. Örneğin, son çalınan medya öğesi, PlaybackStateCompat ve sıra.

Özel oynatma işlemleri ekleme

Medya uygulamanızın desteklediği ek işlemleri göstermek için özel oynatma işlemleri ekleyebilirsiniz. Alan izin veriyorsa (ve siz de alanı ayırmadıysanız) Android, özel işlemleri aktarım kontrollerine ekler. Aksi takdirde, özel işlemler taşma menüsünde görünür. Android, özel işlemleri PlaybackStateCompat'ya eklediğiniz sırayla gösterir.

Standart işlemlerden farklı davranışlar sağlamak için özel işlemleri kullanın. Bunları standart işlemleri değiştirmek veya kopyalamak için kullanmayın.

Özel işlemler eklemek için PlaybackStateCompat.Builder sınıfında addCustomAction yöntemini kullanın. Bu kod snippet'i, "Radyo kanalı başlat"a nasıl özel işlem ekleneceğini gösterir:

Kotlin

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

Java

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

Bu yöntemin daha ayrıntılı bir örneği için GitHub'daki Universal Android Music Player örnek uygulamasında setCustomAction yöntemine bakın. Özel işleminizi oluşturduktan sonra medya oturumunuz, onCustomAction yöntemini geçersiz kılarak işlemlere yanıt verebilir.

Bu kod snippet'inde, uygulamanızın "Radyo kanalı başlat" işlemine nasıl yanıt verebileceği gösterilmektedir:

Kotlin

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

Java

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

Daha fazla bilgi edinmek için GitHub'daki Universal Android Music Player örnek uygulamasında onCustomAction yöntemine bakın.

Özel işlemler için simgeler oluşturma

Oluşturduğunuz her özel işlem için bir simge gerekir.

Bu simgenin açıklaması CommandButton.ICON_ sabitlerinden biriyle eşleşiyorsa özel işlemin EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT anahtarının tam sayı değerini ayarlayın. Desteklenen sistemlerde bu işlem, CustomAction.Builder'a iletilen simge kaynağını geçersiz kılar. Böylece sistem bileşenleri, işleminizi ve diğer oynatma işlemlerini tutarlı bir şekilde oluşturabilir.

Ayrıca bir simge kaynağı da belirtmeniz gerekir. Arabalardaki uygulamalar birçok farklı ekran boyutunda ve yoğunluğunda çalışabilir. Bu nedenle, sağladığınız simgeler vektörel çizilebilir öğeler olmalıdır. Ayrıntı kaybı olmadan öğeleri ölçeklendirmek için drawable vektör kullanın. Vektör çizilebilir öğeler, daha düşük çözünürlüklerde kenarları ve köşeleri piksel sınırlarıyla hizalayabilir.

Özel bir işlem durumluysa (bir oynatma ayarını açıp kapatıyorsa), kullanıcıların işlemi seçtiklerinde bir değişiklik görmelerine yardımcı olmak için farklı durumlar için farklı simgeler sağlayın.

Devre dışı bırakılan işlemler için alternatif simge stilleri sağlama

Özel işlem geçerli bağlamda kullanılamadığında özel işlem simgesini, işlemi devre dışı olarak gösteren alternatif bir simgeyle değiştirin.

Şekil 1. Stil dışı özel işlem simgeleri örnekleri.

Ses biçimini belirtme

Oynatılan medyada özel bir ses biçimi kullanıldığını belirtmek için, bu özelliği destekleyen arabalarda oluşturulan simgeleri belirtebilirsiniz. Şu anda oynatılan medya öğesinin (MediaSession.setMetadata'a iletilir) ekstralar paketinde KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI ve KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI değerlerini ayarlayabilirsiniz. Farklı düzenlere uyum sağlamak için her iki ekstrayı da ayarlayın.

Ayrıca, KEY_IMMERSIVE_AUDIO ekstrasını ayarlayarak otomobil üreticilerine bunun sarmal ses olduğunu ve sarmal içerikle etkileşime girebilecek ses efektleri uygulayıp uygulamayacaklarına karar verirken çok dikkatli olmaları gerektiğini söyleyebilirsiniz.

Şu anda oynatılan öğeden bağlantı ekleme

Oynatılan medya öğesini, altyazısı, açıklaması veya her ikisi de diğer medya öğelerine bağlantı verecek şekilde yapılandırabilirsiniz. Bu sayede kullanıcı, ilgili öğelere hızlıca geçebilir. Örneğin, aynı sanatçının diğer şarkılarına veya bir podcast'in diğer bölümlerine geçebilir. Araba bu özelliği destekliyorsa kullanıcılar bağlantıya dokunarak ilgili içeriğe gidebilir.

Bağlantı eklemek için KEY_SUBTITLE_LINK_MEDIA_ID meta verilerini (altyazıdan bağlantı oluşturmak için) veya KEY_DESCRIPTION_LINK_MEDIA_ID meta verilerini (açıklamadan bağlantı oluşturmak için) yapılandırın. Ayrıntılar için bu meta veri alanlarının referans belgelerine bakın.