تطبيق ExoPlayer التجريبي

يخدم تطبيق ExoPlayer التجريبي الرئيسي غرضين أساسيين:

  1. تقديم مثال بسيط نسبيًا ولكنه مكتمل الميزات لاستخدام ExoPlayer. يمكن استخدام التطبيق التجريبي كنقطة بداية ملائمة يمكن من خلالها تطوير تطبيقك الخاص.
  2. لتسهيل تجربة ExoPlayer. يمكن استخدام التطبيق التجريبي لاختبار التشغيل للمحتوى الخاص بك بالإضافة إلى العينات المضمنة.

تصف هذه الصفحة كيفية الحصول على التطبيق التجريبي وتجميعه وتشغيله. كما يصف كيفية استخدامها لتشغيل الوسائط الخاصة بك

الحصول على الرمز

يمكن العثور على رمز المصدر للتطبيق التجريبي الرئيسي في مجلد demos/main من مشروع GitHub. إذا لم تكن قد قمت بذلك بالفعل، فانسخ المشروع إلى الدليل المحلي:

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

بعد ذلك، افتح المشروع في "استوديو Android". من المفترض أن يظهر لك ما يلي في عرض مشروع Android (تم توسيع المجلدات ذات الصلة بالتطبيق التجريبي):

المشروع في "استوديو Android"

التجميع والتشغيل

لتجميع التطبيق التجريبي وتشغيله، اختَر إعدادات demo وشغِّلها في "استوديو Android". سيتم تثبيت التطبيق التجريبي وتشغيله على جهاز Android متصل. ننصح باستخدام جهاز مادي إن أمكن. وإذا أردت استخدام محاكي بدلاً من ذلك، يُرجى قراءة قسم أدوات المحاكاة في الأجهزة المتوافقة والتأكد من ذلك أنّ جهازك الافتراضي يستخدم صورة نظام بمستوى واجهة برمجة تطبيقات لا يقل عن 23

SampleChooserActivity وPlayerActivity

يعرض التطبيق التجريبي قائمة بالنماذج (SampleChooserActivity). التحديد سيؤدي النموذج إلى فتح نشاط ثانٍ (PlayerActivity) لتشغيله. العرض التوضيحي ميزات عناصر التحكم في التشغيل وتتبع وظيفة تحديد. كما يستخدم فئة الأداة EventLogger في ExoPlayer لاستخراج معلومات تصحيح أخطاء مفيدة سجل النظام. يمكن مشاهدة هذا التسجيل (إلى جانب تسجيل مستوى الخطأ علامات أخرى) باستخدام الأمر:

adb logcat EventLogger:V *:E

تفعيل برامج فك الترميز المجمّعة

يحتوي ExoPlayer على عدد من الإضافات التي تسمح باستخدام البرامج المجمّعة. برامج فك الترميز، بما في ذلك AV1 وVP9 وOpus وFLAC وFFmpeg (الصوت فقط). التطبيق التجريبي لتضمين هذه الإضافات واستخدامها على النحو التالي:

  1. أنشئ كل إضافة من الإضافات التي تريد تضمينها. لاحظ أن هذه عملية يدوية. الرجوع إلى الملف README.md في كل امتداد على التعليمات

  2. في عرض "صيغ الإصدارات" في "استوديو Android"، حدِّد صيغة الإصدار للعرض التوضيحي. وحدة إلى withDecoderExtensionsDebug أو withDecoderExtensionsRelease باسم كما هو موضح في الصورة التالية.

    تحديد صيغة الإصدار التجريبي "withDecoderExtensionsDebug"

  3. عليك تجميع إعدادات "demo" وتثبيتها وتشغيلها كالمعتاد.

ولن يتم استخدام برنامج فك ترميز الإضافات بشكل تلقائي إلا إذا كان هناك برنامج فك ترميز مناسب للنظام الأساسي غير موجود. من الممكن تحديد أن برامج فك ترميز الإضافات كما هو موضح في الأقسام التالية.

تشغيل المحتوى الخاص بك

تتوفّر عدة طرق لتشغيل المحتوى الخاص بك في التطبيق التجريبي.

1. تعديل مواد العرض/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- رمي الكرة

يمكن استخدام Intents لتجاوز قائمة العينات وإطلاقها مباشرةً في التشغيل. لتشغيل عيّنة واحدة، اضبط إجراء الغرض على ومعرّف الموارد المنتظم (URI) الخاص بالبيانات لـ androidx.media3.demo.main.action.VIEW عينة لتشغيلها. يمكن تنشيط هذا الغرض من الوحدة الطرفية باستخدام:

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

في ما يلي المزايا الإضافية الاختيارية المتوافقة مع عيّنة من المحتوى:

  • أمثلة على الميزات الإضافية الخاصة بالإعداد:
    • mime_type [سلسلة] تعديل نموذج MIME على سبيل المثال: application/dash+xml لمحتوى DASH
    • clip_start_position_ms [طويلة] نقطة البداية التي يجب تحويل العيّنة إليها مقطوعًا، بالمللي ثانية.
    • clip_end_position_ms [طويلة] نقطة نهاية يجب بدء العيّنة منها مقطوعًا، بالمللي ثانية.
    • drm_scheme [سلسلة] مخطط إدارة الحقوق الرقمية (DRM) إذا كان محميًا القيم الصالحة هي widevine، playready وclearkey يتم أيضًا قبول المعرّفات الفريدة العالمية لنظام إدارة الحقوق الرقمية.
    • معرّف الموارد المنتظم (URI) لـ drm_license_uri [السلسلة] لخادم التراخيص إذا كان محميًا.
    • drm_force_default_license_uri [منطقي] ما إذا كان سيتم فرض استخدام drm_license_uri للطلبات الرئيسية التي تتضمن معرّف الموارد المنتظم (URI) للترخيص الخاص بها.
    • drm_key_request_properties [مصفوفة سلسلة] تتم تعبئة عناوين طلبات المفاتيح بتنسيق name1 وvalue1 وname2 وvalue2 وما إلى ذلك إذا كان محميًا.
    • drm_session_for_clear_content [منطقي] ما إذا كان سيتم إرفاق جلسة إدارة الحقوق الرقمية لمحو مقاطع الفيديو والصوت.
    • drm_multi_session [منطقي] تفعيل تدوير المفاتيح في حال حمايته.
    • subtitle_uri [سلسلة] معرّف الموارد المنتظم (URI) الخاص بملف ترجمة جانبية
    • subtitle_mime_type [سلسلة] نوع MIME لـ subtitle_uri (مطلوب إذا subtitle_uri).
    • subtitle_language [سلسلة] رمز اللغة BCP47 لملف الترجمة والشرح (يتم تجاهله في حال عدم ضبط سمة subtitle_uri).
    • ad_tag_uri [سلسلة] معرّف الموارد المنتظم (URI) لعلامة الإعلان المطلوب تحميلها باستخدام [إضافة إعلانات الوسائط التفاعلية][].
    • prefer_extension_decoders [منطقي] ما إذا كانت برامج فك ترميز الإضافات هي أفضل من المنصات.

عند استخدام adb shell am start لتنشيط هدف، يمكن إدخال سلسلة اختيارية إضافية. يتم ضبطها على --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