ExoPlayer demo uygulaması

ExoPlayer'ın ana demo uygulamasının iki temel amacı vardır:

  1. ExoPlayer kullanımına ilişkin nispeten basit ancak tüm özellikleri içeren bir örnek sunmak. Demo uygulama, kendi uygulamanızı geliştirmek için uygun bir başlangıç noktası olarak kullanılabilir.
  2. ExoPlayer'ı denemeyi kolaylaştırmak için. Demo uygulaması, dahil edilen örneklere ek olarak kendi içeriğinizin oynatılmasını test etmek için kullanılabilir.

Bu sayfada, demo uygulamasının nasıl edinileceği, derleneceği ve çalıştırılacağı, ayrıca kendi medyanızı oynatmak için nasıl kullanılacağı da açıklanmaktadır.

Kodu alma

Ana demo uygulamasının kaynak kodunu GitHub projemizin demos/main klasöründe bulabilirsiniz. Henüz yapmadıysanız projeyi bir yerel dizine klonlayın:

git clone https://github.com/androidx/media.git

Ardından, projeyi Android Studio'da açın. Android Projesi görünümünde aşağıdakileri görmeniz gerekir (demo uygulamasının ilgili klasörleri genişletilmiştir):

Android Studio'daki proje

Derleniyor ve yayınlanıyor

Demo uygulamasını derlemek ve çalıştırmak için Android Studio'da demo yapılandırmasını seçip çalıştırın. Demo uygulama, bağlı bir Android cihaza yüklenip çalışır. Mümkünse fiziksel bir cihaz kullanmanızı öneririz. Bunun yerine bir emülatör kullanmak isterseniz lütfen Desteklenen cihazlar'ın emülatörler bölümünü okuyun ve Sanal Cihazınızın API düzeyi en az 23 olan bir sistem görüntüsü kullandığından emin olun.

SampleChooserActivity ve PlayerActivity

Demo uygulamada bir örnek listesi (SampleChooserActivity) yer alır. Örnek seçtiğinizde, oynatma için ikinci bir etkinlik (PlayerActivity) açılır. Demoda oynatma kontrolleri ve parça seçimi işlevi bulunur. Ayrıca, faydalı hata ayıklama bilgilerinin sistem günlüğüne çıkarılması için ExoPlayer'ın EventLogger yardımcı program sınıfını da kullanır. Bu günlük kaydı, (diğer etiketler için hata düzeyinde günlük kaydıyla birlikte) şu komutla görüntülenebilir:

adb logcat EventLogger:V *:E

Paketli kod çözücüleri etkinleştirme

ExoPlayer, paket halinde sunulan yazılım kod çözücülerinin kullanılmasına olanak tanıyan AV1, VP9, Opus, FLAC ve FFmpeg (yalnızca ses) gibi çeşitli uzantılara sahiptir. Demo uygulama, bu uzantıları aşağıdaki gibi içerecek ve kullanacak şekilde oluşturulabilir:

  1. Dahil etmek istediğiniz uzantıların her birini oluşturun. Bunun manuel bir işlem olduğunu unutmayın. Talimatlar için her bir uzantıdaki README.md dosyasına bakın.

  2. Android Studio'nun Derleme Varyantları görünümünde demo modülünün derleme varyantını, aşağıdaki resimde gösterildiği gibi withDecoderExtensionsDebug veya withDecoderExtensionsRelease olarak ayarlayın.

    "withDecoderExtensionsDebug" derleme varyantını seçme

  3. demo yapılandırmasını normal şekilde derleyin, yükleyin ve çalıştırın.

Varsayılan olarak uzantı kod çözücü, yalnızca uygun bir platform kod çözücü mevcut olmadığında kullanılır. Aşağıdaki bölümlerde açıklandığı gibi uzantı kod çözücülerinin tercih edilmesi gerektiğini belirtmek mümkündür.

Kendi içeriğinizi oynatma

Demo uygulamasında kendi içeriğinizi oynatmanın birden fazla yolu vardır.

1. asset/media.exolist.json dosyasını düzenleme

Demo uygulamasında listelenen örnekler assets/media.exolist.json üzerinden yüklenmiştir. Bu JSON dosyasını düzenleyerek demo uygulamadan örnek ekleyebilir ve kaldırabilirsiniz. Şema aşağıdaki gibidir; [O], isteğe bağlı bir özelliği belirtir.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Values: mpd, ism, m3u8",
        "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
        "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
        "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
        "drm_license_uri": "[O] URI of the license server if protected",
        "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
        "drm_key_request_properties": "[O] Key request headers if protected",
        "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks"
        "drm_multi_session": "[O] Enables key rotation if protected",
        "subtitle_uri": "[O] The URI of a subtitle sidecar file",
        "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
        "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)",
        "ad_tag_uri": "[O] The URI of an ad tag to load via the IMA extension"
      },
      ...etc
    ]
  },
  ...etc
]

Örnek oynatma listeleri şema kullanılarak belirtilebilir:

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of playlist sample",
        "playlist": [
          {
            "uri": "The URI of the first sample in the playlist",
            "extension": "[O] Sample type hint. Values: mpd, ism, m3u8"
            "clip_start_position_ms": "[O] A start point to which the sample should be clipped, in milliseconds"
            "clip_end_position_ms": "[O] An end point from which the sample should be clipped, in milliseconds"
            "drm_scheme": "[O] Drm scheme if protected. Values: widevine, playready, clearkey",
            "drm_license_uri": "[O] URI of the license server if protected",
            "drm_force_default_license_uri": "[O] Whether to force use of "drm_license_uri" for key requests that include their own license URI",
            "drm_key_request_properties": "[O] Key request headers if protected",
            "drm_session_for_clear_content": "[O] Whether to attach a DRM session to clear video and audio tracks",
            "drm_multi_session": "[O] Enables key rotation if protected",
            "subtitle_uri": "[O] The URI of a subtitle sidecar file",
            "subtitle_mime_type": "[O] The MIME type of subtitle_uri (required if subtitle_uri is set)",
            "subtitle_language": "[O] The BCP47 language code of the subtitle file (ignored if subtitle_uri is not set)"
          },
          {
            "uri": "The URI of the second sample in the playlist",
            ...etc
          },
          ...etc
        ]
      },
      ...etc
    ]
  },
  ...etc
]

Gerekirse anahtar isteği başlıkları, her başlık için dize özelliği içeren bir nesne olarak belirtilir:

"drm_key_request_properties": {
  "name1": "value1",
  "name2": "value2",
  ...etc
}

Örnek seçici etkinliğinde, taşma menüsü uzantı kod çözücülerinin tercih edilip edilmeyeceğini belirtmenize yönelik seçenekler içerir.

Yerel dosya URI'leri ve kapsamlı depolama kısıtlamaları

Demo uygulama, yerel dosya URI'lerini belirtirken bu dosyaları okumak için gerekli depolama erişimi izinlerini ister. Ancak, Android 13'te tipik bir medya dosyası uzantısıyla (.mp4 gibi) bitmeyen rastgele dosyaları yüklemek mümkün değildir. Bu tür bir dosyayı yüklemeniz gerekirse bunu demo uygulamasında erişim kısıtlaması olmayan özel depolama dizinine ekleyebilirsiniz. Bu genellikle /sdcard/Android/data/androidx.media3.demo.main/files adresinde bulunur.

2. Harici bir exolist.json dosyası yükleme

Demo uygulaması, yukarıdaki şemayı kullanarak ve *.exolist.json kuralına göre adlandırılmış harici JSON dosyalarını yükleyebilir. Örneğin, https://yourdomain.com/samples.exolist.json adresinde böyle bir dosyayı barındırıyorsanız demo uygulamasında şunu kullanarak açabilirsiniz:

adb shell am start -a android.intent.action.VIEW \
    -d https://yourdomain.com/samples.exolist.json

Demo uygulamasının yüklü olduğu bir cihazda *.exolist.json bağlantısını (örneğin, tarayıcıda veya bir e-posta istemcisinde) tıkladığınızda, uygulama demo uygulamada da açılır. Dolayısıyla *.exolist.json JSON dosyasının barındırılması, içeriği diğer kullanıcıların demo uygulamada denemesi için basit bir şekilde dağıtmanın bir yolunu sağlar.

3. Bir intent'i tetikleme

Intent'ler, örnek listesini atlamak ve doğrudan oynatmada başlatmak için kullanılabilir. Tek bir örneği oynatmak için niyetin eylemini androidx.media3.demo.main.action.VIEW, veri URI'sini ise oynatılacak örneğin eylemine ayarlayın. Bu tür bir niyet, aşağıdakiler kullanılarak terminalden tetiklenebilir:

adb shell am start -a androidx.media3.demo.main.action.VIEW \
    -d https://yourdomain.com/sample.mp4

Tek bir örnek intent için desteklenen isteğe bağlı ekstralar şunlardır:

  • Örnek yapılandırma ekstraları:
    • mime_type [Dize] Örnek MIME türü ipucu. Örneğin, DASH içeriği için application/dash+xml.
    • clip_start_position_ms [Long] Örneğin milisaniye cinsinden kırpılacağı başlangıç noktası.
    • clip_end_position_ms [Uzun] Milisaniye cinsinden, örneğin kırpılacağı bitiş noktası.
    • drm_scheme [String] Korumalıysa DRM şeması. Geçerli değerler widevine, playready ve clearkey şeklindedir. DRM şeması UUID'leri de kabul edilir.
    • drm_license_uri [Dize] Korunan lisans sunucusunun URI'si.
    • drm_force_default_license_uri [Boole] Kendi lisans URI'sını içeren anahtar istekler için drm_license_uri kullanımının zorunlu olup olmayacağı.
    • drm_key_request_properties [Dize dizisi] Korunursa ad1, değer1, ad2, değer2 vb. olarak paketlenen anahtar isteği başlıkları.
    • drm_session_for_clear_content [Boole] Video ve ses parçalarını temizlemek için DRM oturumu eklenip eklenmeyeceğini belirtir.
    • drm_multi_session [Boole] Korunursa anahtar rotasyonunu etkinleştirir.
    • subtitle_uri [Dize] Altyazı yardımcı dosyasının URI'si.
    • subtitle_mime_type [Dize] subtitle_uri'nin MIME türü (subtitle_uri ayarlanmışsa gereklidir).
    • subtitle_language [Dize] Altyazı dosyasının BCP47 dil kodu (subtitle_uri ayarlanmamışsa yoksayılır).
    • ad_tag_uri [Dize] [IMA uzantısı][] kullanılarak yüklenecek reklam etiketinin URI'si.
    • prefer_extension_decoders [Boole] Uzantı kod çözücülerinin, platform kod çözücülere tercih edilip edilmediğidir.

Bir amacı tetiklemek için adb shell am start kullanılırken --es ile isteğe bağlı ekstra bir dize ayarlanabilir (ör. --es extension mpd). İsteğe bağlı bir ekstra boole değeri --ez ile ayarlanabilir (ör. --ez prefer_extension_decoders TRUE). İsteğe bağlı olarak uzun ekstra, --el ile ayarlanabilir (ör. --el clip_start_position_ms 5000). İsteğe bağlı ekstra bir dize dizisi --esa ile ayarlanabilir (ör. --esa drm_key_request_properties name1,value1) bilgileri gösterilir.

Örneklerden oluşan bir oynatma listesini oynatmak için niyetin işlemini androidx.media3.demo.main.action.VIEW_LIST olarak ayarlayın. Örnek yapılandırma ekstraları, iki farklılık dışında androidx.media3.demo.main.action.VIEW ile aynı kalır:

  • Ekstraların anahtarlarında alt çizgi bulunmalıdır ve son ek olarak örneğin 0 tabanlı dizini bulunmalıdır. Örneğin, extension_0 ilk örnek için örnek türüne ipucu verir. drm_scheme_1, ikinci örnek için DRM şemasını ayarlar.
  • Örneğin URI'si, uri_<sample-index> anahtarıyla ekstra olarak iletilir.

Örnekleme bağımlı olmayan diğer ekstralar değişmez. Örneğin, iki öğeli bir oynatma listesini oynatmak ve ikinci öğenin uzantısını geçersiz kılarak terminalde aşağıdaki komutu çalıştırabilirsiniz:

adb shell am start -a androidx.media3.demo.main.action.VIEW_LIST \
    --es uri_0 https://a.com/sample1.mp4 \
    --es uri_1 https://b.com/sample2.fake_mpd \
    --es extension_1 mpd