برنامه نمایشی ExoPlayer

برنامه آزمایشی اصلی ExoPlayer دو هدف اصلی را دنبال می کند:

  1. برای ارائه یک مثال نسبتا ساده و در عین حال کاملاً برجسته از استفاده از ExoPlayer. برنامه آزمایشی می تواند به عنوان یک نقطه شروع مناسب برای توسعه برنامه خود استفاده شود.
  2. برای آسان کردن امتحان ExoPlayer. برنامه آزمایشی را می توان برای آزمایش پخش محتوای خود علاوه بر نمونه های موجود استفاده کرد.

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

دریافت کد

کد منبع برنامه اصلی نسخه آزمایشی را می‌توانید در demos/main پروژه GitHub ما پیدا کنید. اگر قبلاً این کار را انجام نداده اید، پروژه را در یک فهرست محلی کلون کنید:

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

سپس پروژه را در اندروید استودیو باز کنید. باید موارد زیر را در نمای پروژه Android مشاهده کنید (پوشه های مربوطه برنامه آزمایشی گسترش یافته است):

پروژه در اندروید استودیو

کامپایل و اجرا

برای کامپایل و اجرای برنامه آزمایشی، پیکربندی demo را در Android Studio انتخاب و اجرا کنید. برنامه آزمایشی بر روی یک دستگاه Android متصل نصب و اجرا می شود. توصیه می کنیم در صورت امکان از یک دستگاه فیزیکی استفاده کنید. اگر می خواهید به جای آن از یک شبیه ساز استفاده کنید، لطفاً بخش شبیه سازهای دستگاه های پشتیبانی شده را بخوانید و مطمئن شوید که دستگاه مجازی شما از تصویر سیستمی با سطح API حداقل 23 استفاده می کند.

SampleChooserActivity و PlayerActivity

برنامه آزمایشی لیستی از نمونه ها را ارائه می دهد ( SampleChooserActivity ). با انتخاب یک نمونه، فعالیت دوم ( PlayerActivity ) برای پخش باز می شود. دمو دارای کنترل های پخش و عملکرد انتخاب آهنگ است. همچنین از کلاس ابزار EventLogger ExoPlayer برای خروجی اطلاعات مفید اشکال زدایی به گزارش سیستم استفاده می کند. این گزارش را می توان (همراه با ثبت سطح خطا برای سایر برچسب ها) با دستور زیر مشاهده کرد: 

adb logcat EventLogger:V *:E

فعال کردن رمزگشاهای همراه

ExoPlayer دارای تعدادی برنامه افزودنی است که امکان استفاده از رمزگشاهای نرم افزار همراه، از جمله AV1، VP9، Opus، FLAC، و FFmpeg (فقط صدا) را فراهم می کند. برنامه آزمایشی را می توان برای گنجاندن و استفاده از این افزونه ها به شرح زیر ساخته شده است:

  1. هر یک از افزونه هایی را که می خواهید اضافه کنید بسازید. توجه داشته باشید که این یک فرآیند دستی است. برای دستورالعمل ها به فایل README.md در هر پسوند مراجعه کنید.

  2. در نمای Build Variants اندروید استودیو، نوع ساخت ماژول دمو را مطابق تصویر زیر روی withDecoderExtensionsDebug یا withDecoderExtensionsRelease تنظیم کنید.

    انتخاب نوع ساخت نسخه ی نمایشی «withDecoderExtensionsDebug».

  3. پیکربندی نسخه ی demo را به طور معمول کامپایل، نصب و اجرا کنید.

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

پخش محتوای خودتان

راه های مختلفی برای پخش محتوای خود در برنامه نمایشی وجود دارد.

1. ویرایش assets/media.exolist.json

نمونه‌های فهرست‌شده در برنامه آزمایشی از assets/media.exolist.json بارگیری می‌شوند. با ویرایش این فایل JSON، امکان افزودن و حذف نمونه ها از برنامه نمایشی وجود دارد. این طرح به شرح زیر است، که در آن [O] یک ویژگی اختیاری را نشان می دهد.

[
  {
    "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
]

لیست پخش نمونه ها را می توان با استفاده از این طرح مشخص کرد:

[
  {
    "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
]

در صورت لزوم، سرصفحه‌های درخواست کلید به عنوان یک شی حاوی یک ویژگی رشته برای هر هدر مشخص می‌شوند:

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

در فعالیت انتخابگر نمونه، منوی سرریز شامل گزینه‌هایی برای تعیین ترجیح رمزگشاهای افزونه است.

URI فایل های محلی و محدودیت های ذخیره سازی محدوده

هنگام تعیین URI فایل های محلی، برنامه آزمایشی مجوزهای لازم برای دسترسی به فضای ذخیره سازی را برای خواندن این فایل ها درخواست می کند. با این حال، از Android 13، امکان بارگیری فایل‌های دلخواه که به پسوند فایل رسانه‌ای معمولی ختم نمی‌شوند (مانند .mp4 ) وجود ندارد. اگر نیاز به بارگیری چنین فایلی دارید، می‌توانید آن را در فهرست ذخیره‌سازی خاص برنامه آزمایشی قرار دهید که محدودیت دسترسی ندارد. این معمولاً در /sdcard/Android/data/androidx.media3.demo.main/files قرار دارد.

2. بارگیری یک فایل exolist.json خارجی

برنامه آزمایشی می‌تواند فایل‌های JSON خارجی را با استفاده از طرحواره بالا و نام‌گذاری شده طبق قرارداد *.exolist.json بارگیری کند. برای مثال، اگر چنین فایلی را در https://yourdomain.com/samples.exolist.json میزبانی می کنید، می توانید آن را در برنامه نمایشی با استفاده از:

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

با کلیک بر روی پیوند *.exolist.json (به عنوان مثال، در مرورگر یا یک سرویس گیرنده ایمیل) در دستگاهی که برنامه آزمایشی نصب شده است، آن را در برنامه نمایشی نیز باز می کند. از این رو میزبانی یک فایل JSON *.exolist.json یک راه ساده برای توزیع محتوا برای دیگران در برنامه آزمایشی ارائه می دهد.

3. شلیک یک قصد

از Intent ها می توان برای دور زدن لیست نمونه ها و راه اندازی مستقیم به پخش استفاده کرد. برای پخش یک نمونه، اکشن intent را روی androidx.media3.demo.main.action.VIEW و URI داده آن را روی نمونه مورد نظر تنظیم کنید. چنین قصدی را می توان از ترمینال با استفاده از موارد زیر شلیک کرد:

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

موارد اضافی اختیاری پشتیبانی شده برای یک هدف نمونه عبارتند از:

  • نمونه تنظیمات اضافی:
    • mime_type [String] نمونه اشاره نوع MIME. به عنوان مثال application/dash+xml برای محتوای DASH.
    • clip_start_position_ms [Long] نقطه شروعی که نمونه باید به آن برش داده شود، در میلی ثانیه.
    • clip_end_position_ms [Long] نقطه پایانی که نمونه باید از آن بریده شود، در میلی ثانیه.
    • drm_scheme [String] طرح DRM در صورت محافظت. مقادیر معتبر عبارتند از widevine , playready و clearkey . UUID های طرح DRM نیز پذیرفته می شوند.
    • drm_license_uri [رشته] URI سرور مجوز اگر محافظت شود.
    • drm_force_default_license_uri [Boolean] آیا استفاده اجباری از drm_license_uri برای درخواست‌های کلیدی که شامل URI مجوز خودشان است یا خیر.
    • drm_key_request_properties [آرایه رشته‌ای] سرصفحه‌های درخواست کلید به صورت name1، value1، name2، value2 و غیره در صورت محافظت بسته‌بندی می‌شوند.
    • drm_session_for_clear_content [Boolean] آیا باید یک جلسه DRM برای پاک کردن آهنگ‌های ویدیویی و صوتی پیوست شود.
    • drm_multi_session [Boolean] چرخش کلید را در صورت محافظت فعال می کند.
    • subtitle_uri [String] URI یک فایل سایدکار زیرنویس.
    • subtitle_mime_type [String] نوع MIME subtitle_uri (در صورت تنظیم subtitle_uri لازم است).
    • subtitle_language [String] کد زبان BCP47 فایل زیرنویس (در صورت تنظیم نشدن subtitle_uri نادیده گرفته می‌شود).
    • ad_tag_uri [String] URI یک برچسب تبلیغاتی که با استفاده از [برنامه افزودنی IMA][] بارگیری می شود.
    • prefer_extension_decoders [Boolean] اینکه آیا رمزگشاهای الحاقی به پلتفرم ها ترجیح داده می شوند.

هنگام استفاده از adb shell am start to fire intent، یک رشته اضافی اختیاری را می توان با --es تنظیم کرد (به عنوان مثال، --es extension mpd ). یک اضافی بولی اختیاری را می توان با --ez تنظیم کرد (به عنوان مثال، --ez prefer_extension_decoders TRUE ). یک اضافی طولانی اختیاری را می توان با --el تنظیم کرد (به عنوان مثال --el clip_start_position_ms 5000 ). یک آرایه رشته اختیاری اضافی را می توان با --esa تنظیم کرد (به عنوان مثال، --esa drm_key_request_properties name1,value1 ).

برای پخش لیست پخش نمونه‌ها، اکشن intent را روی androidx.media3.demo.main.action.VIEW_LIST تنظیم کنید. تنظیمات اضافی نمونه مانند androidx.media3.demo.main.action.VIEW باقی می مانند، به جز دو تفاوت:

  • کلیدهای اضافی باید دارای زیرخط و شاخص مبتنی بر 0 نمونه به عنوان پسوند باشند. به عنوان مثال، extension_0 به نوع نمونه برای نمونه اول اشاره می کند. drm_scheme_1 طرح DRM را برای نمونه دوم تنظیم می کند.
  • uri نمونه به عنوان یک اضافی با کلید uri_<sample-index> ارسال می شود.

سایر موارد اضافی که به نمونه وابسته نیستند، تغییر نمی کنند. برای مثال، می‌توانید برای پخش یک لیست پخش با دو آیتم، دستور زیر را در ترمینال اجرا کنید و پسوند مورد دوم را لغو کنید:

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