תחילת העבודה

כדי להתחיל להשתמש ב-ExoPlayer בתרחישי שימוש פשוטים, צריך לבצע את השלבים הבאים:

  1. מוסיפים את ExoPlayer כתלות לפרויקט.
  2. יוצרים מכונת ExoPlayer.
  3. מצרפים את הנגן לתצוגה (לפלט וידאו ולקלט משתמש).
  4. מכינים את הנגן להפעלה באמצעות MediaItem.
  5. כשמסיימים, משחררים את הנגן.

השלבים האלה מפורטים בהמשך. דוגמה מלאה זמינה PlayerActivity באפליקציית ההדגמה הראשית.

הוספת ExoPlayer כתלות

הוספת מודולים של ExoPlayer

הדרך הכי קלה להתחיל להשתמש ב-AndroidX Media3 היא להוסיף תלות ב-gradle בספריות שאתם צריכים בקובץ build.gradle של מודול האפליקציה.

לדוגמה, כדי להסתמך על ExoPlayer עם תמיכה בהפעלה של DASH ורכיבי ממשק משתמש, אפשר להוסיף תלות במודולים באופן הבא:

Kotlin

implementation("androidx.media3:media3-exoplayer:1.7.1")
implementation("androidx.media3:media3-exoplayer-dash:1.7.1")
implementation("androidx.media3:media3-ui:1.7.1")
implementation("androidx.media3:media3-ui-compose:1.7.1")

מגניב

implementation "androidx.media3:media3-exoplayer:1.7.1"
implementation "androidx.media3:media3-exoplayer-dash:1.7.1"
implementation "androidx.media3:media3-ui:1.7.1"
implementation("androidx.media3:media3-ui-compose:1.7.1")

כאשר 1.7.1 היא הגרסה המועדפת (אפשר למצוא את הגרסה האחרונה בהערות לגבי הגרסה). כל המודולים צריכים להיות באותה גרסה.

ל-AndroidX Media3 יש מודולים של ספריות שתלויים בספריות חיצוניות כדי לספק פונקציונליות נוספת. חלק מהספריות זמינות ממאגר Maven, ואחרות צריך ליצור באופן ידני. אפשר לעיין בספריית הספריות ולראות קובצי README נפרדים עם פרטים.

מידע נוסף על מודולי הספריות שזמינים מופיע בדף Google Maven AndroidX Media.

הפעלת התמיכה ב-Java 8

אם התמיכה ב-Java 8 לא מופעלת, צריך להפעיל אותה לפחות בכל הקבצים build.gradle שתלויים ב-ExoPlayer, על ידי הוספת הקוד הבא לקטע android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

יצירת הנגן

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

Kotlin

val player = ExoPlayer.Builder(context).build()

Java

ExoPlayer player = new ExoPlayer.Builder(context).build();

הערה לגבי שרשור

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

אפשר לציין באופן מפורש את ה-thread שבו צריך לגשת למופע של ExoPlayer על ידי העברת Looper כשיוצרים את הנגן. אם לא מציינים Looper, המערכת משתמשת ב-Looper של השרשור שבו נוצר נגן, או אם לשרשור הזה אין Looper, המערכת משתמשת ב-Looper של השרשור הראשי של האפליקציה. בכל המקרים, אפשר לשלוח שאילתה לגבי Looper של השרשור שממנו צריך לגשת לנגן באמצעות Player.getApplicationLooper.

מידע נוסף על מודל ה-threading של ExoPlayer זמין בקטע Threading model (מודל ה-threading) ב-Javadoc של ExoPlayer.

צירוף הנגן לתצוגה

ספריית ExoPlayer מספקת מגוון רחב של רכיבי ממשק משתמש מוכנים מראש להפעלת מדיה. הם כוללים את PlayerView, שמכיל PlayerControlView,‏ SubtitleView ו-Surface שבהם הסרטון מוצג. אפשר לכלול PlayerView ב-XML של פריסת האפליקציה. לדוגמה, כדי לקשר את נגן המדיה לתצוגה:

Kotlin

// Bind the player to the view.
playerView.player = player

Java

// Bind the player to the view.
playerView.setPlayer(player);

השימוש ברכיבי ממשק משתמש מוכנים מראש של ExoPlayer הוא אופציונלי. באפליקציות וידאו שמטמיעות ממשק משתמש משלהן, אפשר להגדיר את היעד SurfaceView, TextureView, SurfaceHolder או Surface באמצעות השיטות setVideoSurfaceView,‏ setVideoTextureView, ‏ setVideoSurfaceHolder ו-setVideoSurface של ExoPlayer, בהתאמה. אפשר להשתמש בקריאה החוזרת (callback) של Listener.onCues כדי לקבל כתוביות שצריך להציג במהלך ההפעלה, ובקריאה החוזרת של setImageOutput כדי לקבל תמונות מפוענחות.

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

android:keepScreenOn="true"

מידע נוסף על שימוש ברכיבי ממשק המשתמש של Media3 ועל התאמה אישית שלהם זמין בדף בנושא ממשק המשתמש.

מילוי הפלייליסט והכנת הנגן

ב-ExoPlayer, כל פריט מדיה מיוצג על ידי MediaItem. כדי להפעיל קטע מדיה, צריך ליצור MediaItem מתאים, להוסיף אותו לנגן, להכין את הנגן ולקרוא ל-play כדי להתחיל את ההפעלה:

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

‫ExoPlayer תומך בפלייליסטים באופן ישיר, כך שאפשר להכין את הנגן עם כמה פריטי מדיה להפעלה אחד אחרי השני:

Kotlin

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

שליטה בנגן

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

  • ‫play ו-pause מתחילים את ההפעלה ומשהים אותה.
  • ‫seekTo מאפשרת חיפוש בתוך המדיה.
  • ‫hasPrevious, hasNext, previous ו-next מאפשרים לנווט בפלייליסט.
  • setRepeatMode קובע אם המדיה תופעל בלופ ואיך.
  • setShuffleModeEnabled שולט בהפעלת הפלייליסט בסדר אקראי.
  • setPlaybackParameters משנה את מהירות ההפעלה ואת גובה הצליל של האודיו.

אם נגן המדיה משויך ל-PlayerView או ל-PlayerControlView, אינטראקציה של המשתמש עם הרכיבים האלה תגרום להפעלת שיטות תואמות בנגן המדיה.

הפעלת הנגן

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