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

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

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

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

קבלת הקוד

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

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

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

הפרויקט ב-Android Studio

הידור והרצה

כדי להדר ולהפעיל את אפליקציית ההדגמה, צריך לבחור ולהפעיל את ההגדרה 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' ב-Android Studio, מגדירים את וריאנט ה-build להדגמה למודול withDecoderExtensionsDebug או withDecoderExtensionsRelease בתור שמוצגת בתמונה הבאה.

    בחירת וריאנט ה-build של ההדגמה 'withDecoderExtensionDebug'

  3. הידור, ההתקנה וההפעלה של ההגדרה של demo כרגיל.

כברירת מחדל, ייעשה שימוש במפענח תוספים רק אם מקודד פלטפורמה מתאים. אינו קיים. אפשר לציין שמפענחי תוספים צריכים להיות של Google, כפי שמתואר בקטעים הבאים.

הפעלת התוכן שלך

אתם יכולים להפעיל את התוכן שלכם באפליקציית ההדגמה בכמה דרכים.

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. הפעלת כוונה

אפשר להשתמש באובייקטים מסוג 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

התוספות האופציונליות שנתמכות ב-Intent לדוגמה אחת הן:

  • תוספות להגדרות לדוגמה:
    • mime_type [מחרוזת] רמז לסוג MIME לדוגמה. לדוגמה application/dash+xml לתוכן DASH.
    • clip_start_position_ms [ארוכה] נקודת התחלה שאליה הדגימה צריכה להיות נחתך, באלפיות השנייה.
    • clip_end_position_ms [ארוכה] נקודת סיום שממנה צריכה להיות הדגימה נחתך, באלפיות השנייה.
    • drm_scheme [מחרוזת] סכימת DRM אם היא מוגנת. הערכים החוקיים הם widevine, playready וגם clearkey ניתן גם להשתמש במזהי UUID של סכימת DRM.
    • drm_license_uri [מחרוזת] URI של שרת הרישיונות אם הוא מוגן.
    • drm_force_default_license_uri [בוליאני] האם לאלץ שימוש ב- drm_license_uri לבקשות מפתח שכוללות URI של הרישיון משלהן.
    • drm_key_request_properties [מערך מחרוזות] כותרות של בקשות מפתח ארוזות בתור name1, value1, name2, value2 וכו' אם הם מוגנים.
    • drm_session_for_clear_content [בוליאני] האם לצרף סשן DRM כדי למחוק טראקים של וידאו ואודיו.
    • drm_multi_session [בוליאני] מאפשר רוטציית מפתחות אם היא מוגנת.
    • subtitle_uri [מחרוזת] ה-URI של קובץ כתוביות צדדיות.
    • subtitle_mime_type [מחרוזת] סוג MIME של Caption_uri (חובה אם Caption_uri מוגדרת).
    • subtitle_language [מחרוזת] קוד השפה BCP47 של קובץ הכתוביות (המערכת תתעלם אם לא מוגדר ערך caption_uri).
    • ad_tag_uri [String] ה-URI של תג מודעה שיש לטעון באמצעות [תוסף IMA][].
    • prefer_extension_decoders [בוליאני] האם מפענחי תוספים הם היא מועדפת על הפלטפורמה.

כשמשתמשים בפונקציה 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).

כדי להשמיע פלייליסט של טעימות, צריך להגדיר את פעולת ה-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