תחילת העבודה

בתרחישי שימוש פשוטים, כדי להתחיל להשתמש ב-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.4.1")
implementation("androidx.media3:media3-exoplayer-dash:1.4.1")
implementation("androidx.media3:media3-ui:1.4.1")

Groovy

implementation "androidx.media3:media3-exoplayer:1.4.1"
implementation "androidx.media3:media3-exoplayer-dash:1.4.1"
implementation "androidx.media3:media3-ui:1.4.1"

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

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

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

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

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

הפעלת multidex

אם גרסת Gradle minSdkVersion היא 20 ואילך, צריך להפעיל את multidex כדי למנוע שגיאות build.

יצירת הנגן

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

Kotlin

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

Java

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

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

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

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

מידע נוסף על מודל השרשור של ExoPlayer זמין בקטע Threading model ב-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);

אפשר גם להשתמש ב-PlayerControlView כרכיב עצמאי, וזה שימושי בתרחישים לדוגמה שבהם יש רק אודיו.

השימוש ברכיבי ממשק המשתמש המובנים של ExoPlayer הוא אופציונלי. באפליקציות וידאו שמטמיעות ממשק משתמש משלהם, אפשר להגדיר את היעד SurfaceView, ‏ TextureView,‏ SurfaceHolder או Surface באמצעות השיטות setVideoSurfaceView, ‏ setVideoTextureView, ‏ setVideoSurfaceHolder ו-setVideoSurface של ExoPlayer, בהתאמה. אפשר להשתמש בשיטה addTextOutput של ExoPlayer כדי לקבל כתוביות שצריך להציג במהלך ההפעלה.

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

ב-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.