ExoPlayer demo uygulaması

ExoPlayer'ın ana demo uygulaması iki temel amaca hizmet eder:

  1. ExoPlayer kullanımına dair nispeten basit ancak tam özellikli bir örnek sunmak. Demo uygulaması, 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 örneklerin yanı sıra kendi içeriğinizin oynatılmasını test etmek için kullanılabilir.

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

Kodu alma

Ana demo uygulamasının kaynak kodunu demos/main klasöründe bulabilirsiniz. GitHub projemiz Henüz yapmadıysanız projeyi yerel bir 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

Derleme ve çalıştırma

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 uygulaması, bağlı bir Android cihaza yüklenir ve cihazda çalışır. Mümkünse fiziksel bir cihaz kullanmanızı öneririz. Bunun yerine bir emülatör kullanmak istiyorsanız lütfen Desteklenen cihazlar bölümündeki emülatörler kısmını okuyun ve sanal cihazınızın en az 23 API düzeyine sahip bir sistem görüntüsü kullandığından emin olun.

SampleChooserActivity ve PlayerActivity

Demo uygulamasında bir örnek listesi (SampleChooserActivity) gösterilir. Bir örnek seçildiğinde oynatma için ikinci bir etkinlik (PlayerActivity) açılır. Demoda oynatma kontrolleri ve parça seçimi işlevi yer alır. Ayrıca, sistem günlüğüne yararlı hata ayıklama bilgileri vermek için ExoPlayer'ın EventLogger yardımcı sınıfını kullanır. Bu günlük kaydı (diğer etiketlerle ilgili hata düzeyi günlük kaydıyla birlikte) şu komutla görüntülenebilir:

adb logcat EventLogger:V *:E

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

ExoPlayer'da AV1, VP9, Opus, FLAC ve FFmpeg (yalnızca ses) dahil olmak üzere paketlenmiş yazılım kod çözücülerin kullanılmasına olanak tanıyan çeşitli uzantılar bulunur. Demo uygulaması, bu uzantıları aşağıdaki şekilde içerecek ve kullanacak şekilde oluşturulabilir:

  1. Dahil etmek istediğiniz her uzantıyı oluşturun. Bu işlemin manuel olarak yapıldığını unutmayın. Talimatlar için her uzantıdaki README.md dosyasına bakın.

  2. Android Studio'nun Build Variants (Derleme Değişkenleri) görünümünde, aşağıdaki resimde gösterildiği gibi demo modülünün derleme değişkenini withDecoderExtensionsDebug veya withDecoderExtensionsRelease olarak ayarlayın.

    `withDecoderExtensionsDebug` derleme değişkeni demosunu 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ü yoksa kullanılır. Aşağıdaki bölümlerde açıklandığı gibi, uzantı kod çözücülerinin tercih edilmesi gerektiğini belirtebilirsiniz.

Kendi içeriğinizi oynatma

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

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

Demo uygulamasında listelenen örnekler assets/media.exolist.json adresinden yüklenir. Bu JSON dosyası düzenlenerek demo uygulamasından örnekler eklenebilir ve kaldırılabilir. Şema aşağıdaki gibidir. [O], isteğe bağlı bir özelliği gösterir.

[
  {
    "name": "Name of heading",
    "samples": [
      {
        "name": "Name of sample",
        "uri": "The URI of the sample",
        "extension": "[O] Sample type hint. Cannot be combined with mime_type. 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",
        "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
        "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, aşağıdaki ş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. Cannot be combined with mime_type. 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",
            "mime_type": "[O] The MIME type of the sample. Cannot be combined with extension.",
            "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 bir 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ünde uzantı kod çözücülerinin tercih edilip edilmeyeceğini belirtme seçenekleri bulunur.

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

Yerel dosya URI'leri belirtilirken demo uygulama, bu dosyaları okumak için gerekli depolama alanı erişim izinlerini ister. Ancak Android 13'ten itibaren, tipik bir medya dosyası uzantısıyla (ör. .mp4) bitmeyen rastgele dosyaları yüklemek mümkün değildir. Bu tür bir dosyayı yüklemeniz gerekiyorsa erişim kısıtlaması olmayan demo uygulamasının belirli depolama dizinine yerleştirebilirsiniz. Bu genellikle /sdcard/Android/data/androidx.media3.demo.main/files konumunda bulunur.

2. Harici bir exolist.json dosyasını 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, böyle bir dosyayı https://yourdomain.com/samples.exolist.json adresinde barındırıyorsanız şu kodu kullanarak demo uygulamasında 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ı (ör. tarayıcıda veya e-posta istemcisinde) tıkladığınızda bu bağlantı demo uygulamasında da açılır. Bu nedenle, *.exolist.json JSON dosyası barındırmak, içerikleri diğer kullanıcıların demo uygulamasında denemesi için dağıtmanın basit bir yoludur.

3. Amaç tetikleme

Niyetler, örnek listesini atlamak ve doğrudan oynatmaya başlamak için kullanılabilir. Tek bir örnek oynatmak için amacın işlemini androidx.media3.demo.main.action.VIEW, veri URI'sini ise oynatılacak örneğin URI'si olarak ayarlayın. Bu tür bir amaç, terminalden aşağıdaki yöntemlerle tetiklenebilir:

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

Tek bir örnek amaç 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 [Uzun] Örneklerin kırpılması gereken başlangıç noktası (milisaniye cinsinden).
    • clip_end_position_ms [Uzun] Örneğin kırpılması gereken uç nokta (milisaniye cinsinden).
    • drm_scheme [Dize] Korumalıysa DRM şeması. Geçerli değerler widevine, playready ve clearkey şeklindedir. DRM şeması UUID'leri de kabul edilir.
    • drm_license_uri [Dize] Korunuyorsa lisans sunucusunun URI'si.
    • drm_force_default_license_uri [Boolean] Kendi lisans URI'lerini içeren anahtar isteklerinde drm_license_uri kullanımının zorunlu kılınıp kılınmayacağı.
    • drm_key_request_properties [Dize dizisi] Korunuyorsa name1, value1, name2, value2 vb. olarak paketlenmiş anahtar isteği üstbilgileri.
    • drm_session_for_clear_content [Boolean] Net video ve ses parçalarına DRM oturumu eklenip eklenmeyeceği.
    • drm_multi_session [Boolean] Korunuyorsa 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 zorunludur).
    • 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 bir reklam etiketinin URI'si.
    • prefer_extension_decoders [Boolean] Uzantı kod çözücülerin platform kod çözücülere tercih edilip edilmeyeceği.

Bir amaç tetiklemek için adb shell am start kullanılırken --es ile isteğe bağlı bir dize ekstrası ayarlanabilir (ör. --es extension mpd). --ez ile isteğe bağlı bir boolean ekstrası ayarlanabilir (ör. --ez prefer_extension_decoders TRUE). --el ile isteğe bağlı bir uzun ekstrası ayarlanabilir (ör. --el clip_start_position_ms 5000). --esa ile isteğe bağlı bir dize dizisi ekstrası ayarlanabilir (ör. --esa drm_key_request_properties name1,value1).

Ö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 fark dışında androidx.media3.demo.main.action.VIEW ile aynıdır:

  • Ekstraların anahtarlarında alt çizgi olmalı ve örneklerin 0 tabanlı dizini sonek olarak eklenmelidir. Örneğin, extension_0, ilk örnek için örnek türünü belirtir. drm_scheme_1, ikinci örnek için DRM şemasını ayarlayacaktır.
  • Örneğin URI'si, uri_<sample-index> anahtarıyla ek olarak iletilir.

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

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