אפליקציית הדגמה של ExoPlayer

אפליקציית ההדגמה הראשית של ExoPlayer מיועדת לשתי מטרות עיקריות:

  1. כדי לספק דוגמה מלאה לשימוש ב-ExoPlayer. אפשר להשתמש באפליקציית ההדגמה כנקודת התחלה נוחה לפיתוח אפליקציה משלכם.
  2. כדי לאפשר לכם לנסות את ExoPlayer. אפשר להשתמש באפליקציית ההדגמה כדי לבדוק את ההפעלה של התוכן שלכם, בנוסף לדוגמאות שכלולות בה.

בדף הזה מוסבר איך להשיג את אפליקציית ההדגמה, לקמפל אותה ולהריץ אותה. מוסבר גם איך להשתמש בה כדי להפעיל מדיה משלכם.

קבלת הקוד

קוד המקור של אפליקציית ההדגמה הראשית נמצא בתיקייה demos/main של פרויקט GitHub שלנו. אם עדיין לא עשיתם זאת, משכפלים את הפרויקט לספרייה מקומית:

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

לאחר מכן, פותחים את הפרויקט ב-Android Studio. אתם אמורים לראות את הדברים הבאים בתצוגת הפרויקט ב-Android (התיקיות הרלוונטיות של אפליקציית ההדגמה מורחבות):

הפרויקט ב-Android Studio
איור 1. הפרויקט ב-Android Studio.

הידור והרצה

כדי לקמפל ולהריץ את אפליקציית ההדגמה, בוחרים את ההגדרה demo ומריצים אותה ב-Android Studio. אפליקציית ההדגמה תותקן ותפעל במכשיר מחובר עם Android. מומלץ להשתמש במכשיר פיזי אם אפשר. אם רוצים להשתמש במקום זאת באמולטור, צריך לקרוא את הקטע בנושא אמולטורים במאמר מכשירים נתמכים ולוודא שהמכשיר הווירטואלי משתמש בקובץ אימג' של המערכת עם רמת API של 23 לפחות.

‫SampleChooserActivity ו-PlayerActivity באפליקציית ההדגמה של ExoPlayer
איור 2. SampleChooserActivity ו-PlayerActivity.

באפליקציית ההדגמה מוצגת רשימה של דוגמאות (SampleChooserActivity). כשבוחרים דוגמה, נפתח מסך פעילות שני (PlayerActivity) להפעלה. הדמו כולל אמצעי בקרה להפעלה ופונקציונליות לבחירת רצועות. הוא גם משתמש במחלקה EventLogger של כלי השירות של ExoPlayer כדי להפיק מידע שימושי לניפוי באגים ביומן המערכת. אפשר לראות את הרישום ביומן (יחד עם רישום ביומן של רמת השגיאה עבור תגים אחרים) באמצעות הפקודה:

adb logcat EventLogger:V *:E

הפעלת חבילות של מפענחים

ל-ExoPlayer יש מספר תוספים שמאפשרים שימוש במפענחי תוכנה בחבילה, כולל AV1,‏ VP9,‏ Opus,‏ FLAC ו-FFmpeg (אודיו בלבד). אפשר ליצור את אפליקציית ההדגמה כך שתכלול את התוספים האלה ותשתמש בהם באופן הבא:

  1. יוצרים כל אחת מהתוספים שרוצים לכלול. חשוב לזכור שמדובר בתהליך ידני. הוראות מפורטות אפשר למצוא בקובץ README.md בכל תוסף.

  2. בתצוגה Build Variants (וריאנט build) ב-Android Studio, מגדירים את וריאנט build של מודול ההדגמה ל-withDecoderExtensionsDebug או ל-withDecoderExtensionsRelease, כמו שמוצג בתמונה הבאה.

    בחירת וריאציית ה-build של ההדגמה `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. 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
]

אפשר לציין פלייליסטים של דוגמאות באמצעות הסכימה:

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

אם צריך, מציינים את כותרות הבקשה העיקריות כאובייקט שמכיל מאפיין מחרוזת לכל כותרת:

"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 של הנתונים ל-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 [ארוך] נקודת התחלה שאליה צריך לחתוך את הדגימה, במילישניות.
    • ‫clip_end_position_ms [Long] נקודת קצה שממנה צריך לחתוך את הדגימה, באלפיות השנייה.
    • ‫drm_scheme [String] תוכנית DRM אם מוגן. הערכים התקינים הם widevine, playready ו-clearkey. אפשר להשתמש גם ב-UUID של סכימת DRM.
    • ‫drm_license_uri [String] כתובת ה-URI של שרת הרישיונות אם הוא מוגן.
    • ‫drm_force_default_license_uri [Boolean] האם לכפות שימוש ב-drm_license_uri לבקשות מפתח שכוללות URI משלהן לרישיון.
    • drm_key_request_properties [String array] Key request headers packed as name1, value1, name2, value2 etc. if protected.
    • ‫drm_session_for_clear_content [Boolean] האם לצרף סשן DRM לרצועות וידאו ואודיו לא מוצפנות.
    • ‫drm_multi_session [Boolean] הפעלת רוטציית מפתחות אם הם מוגנים.
    • ‫subtitle_uri [String] ה-URI של קובץ כתוביות נלווה.
    • ‫subtitle_mime_type [מחרוזת] סוג ה-MIME של subtitle_uri (נדרש אם מוגדר subtitle_uri).
    • ‫subtitle_language [String] קוד השפה של קובץ הכתוביות בתקן BCP47 (המאפיין הזה מתעלם אם לא מוגדר subtitle_uri).
    • ad_tag_uri [מחרוזת] ה-URI של תג פרסום לטעינה באמצעות התוסף IMA.
    • prefer_extension_decoders [Boolean] האם מפענחי תוספים עדיפים על מפענחי פלטפורמה.

כשמשתמשים ב-adb shell am start כדי להפעיל 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).

כדי להפעיל פלייליסט של קטעים לדוגמה, מגדירים את הפעולה של הכוונה ל-androidx.media3.demo.main.action.VIEW_LIST. הגדרת הדוגמה extras נשארת זהה לזו של 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