Codakey
Play
← Back to google/ExoPlayer

How to Deploy & Use google/ExoPlayer

ExoPlayer (Deprecated) Deployment and Usage Guide

Note: This project is deprecated. The latest ExoPlayer code is available in AndroidX Media3. All users are strongly encouraged to migrate to AndroidX Media3. This guide is provided for historical context or for maintaining existing projects still using exoplayer:2.19.1 or earlier versions from this repository.

1. Prerequisites

To work with this deprecated ExoPlayer project, you will need:

  • Java Development Kit (JDK): Version 8 or higher.
  • Android SDK: With appropriate build tools and platform versions (e.g., API 21+ for basic functionality, up to API 33 for features like POST_NOTIFICATIONS for DownloadService).
  • Android Studio: Recommended IDE for Android development.
  • Git: For cloning the repository.

2. Installation

This project is no longer actively developed. The last artifact released was exoplayer:2.19.1. You can either clone this deprecated repository or integrate the last released version via Gradle.

2.1. Cloning the Repository (Deprecated)

If you need to inspect or build from the source of this specific deprecated repository:

git clone https://github.com/google/ExoPlayer.git
cd ExoPlayer

2.2. Integrating via Gradle (Recommended for existing projects)

For existing Android projects that still need to use the last stable version from this repository (2.19.1), add the following to your build.gradle (Module: app) file:

dependencies {
    // Core library
    implementation 'com.google.android.exoplayer:exoplayer-core:2.19.1'
    // UI components
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.19.1'
    // HLS support
    implementation 'com.google.android.exoplayer:exoplayer-hls:2.19.1'
    // DASH support
    implementation 'com.google.android.exoplayer:exoplayer-dash:2.19.1'
    // SmoothStreaming support
    implementation 'com.google.android.exoplayer:exoplayer-smoothstreaming:2.19.1'
    // Advertising support (e.g., IMA)
    implementation 'com.google.android.exoplayer:exoplayer-ima:2.19.1'
    // Optional: for offline downloads
    implementation 'com.google.android.exoplayer:exoplayer-offline:2.19.1'
    // Optional: for analytics
    implementation 'com.google.android.exoplayer:exoplayer-analytics:2.19.1'
}

Ensure your project's build.gradle (Project) file includes Google's Maven repository:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

3. Configuration

ExoPlayer itself does not require external configuration files or environment variables. All configuration is done programmatically within your Android application code.

3.1. Android Manifest Permissions

Depending on your use case, you may need to declare certain permissions in your AndroidManifest.xml:

  • Internet Access: For streaming content. 
    <uses-permission android:name="android.permission.INTERNET" />
  • Wake Lock: To prevent the screen from dimming or the device from sleeping during playback. 
    <uses-permission android:name="android.permission.WAKE_LOCK" />
  • Post Notifications (Android 13+): If using DownloadService and targeting SDK 33 or higher, you need to request this permission at runtime and declare it in the manifest. 
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
  • Network State: To check network connectivity for adaptive streaming or downloads. 
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

3.2. ProGuard/R8 Configuration

If you are using ProGuard or R8 for code shrinking, obfuscation, and optimization, ExoPlayer includes its own rules, so no additional configuration is typically needed.

4. Build & Run

4.1. Building the Project (from source)

If you have cloned the repository, you can open it directly in Android Studio. Android Studio will handle syncing Gradle and building the project.

Alternatively, from the command line:

# Build the entire project
./gradlew build

# Build a specific module, e.g., the demo app
./gradlew :demos:main:assembleDebug

4.2. Running an Example Application (from source)

The demos directory contains example applications. To run the main demo app:

  1. Open the ExoPlayer project in Android Studio.
  2. Select the demos.main run configuration.
  3. Connect an Android device or start an emulator.
  4. Click the "Run" button in Android Studio.

4.3. Basic Usage in Your Application

Here's a minimal example of how to use ExoPlayer to play a video:

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.exoplayer2.ExoPlayer;
import com.google.android.exoplayer2.MediaItem;
import com.google.android.exoplayer2.ui.StyledPlayerView;

public class MainActivity extends AppCompatActivity {

    private StyledPlayerView playerView;
    private ExoPlayer player;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main); // Assuming you have a layout with StyledPlayerView

        playerView = findViewById(R.id.player_view);
    }

    @Override
    protected void onStart() {
        super.onStart();
        if (player == null) {
            player = new ExoPlayer.Builder(this).build();
            playerView.setPlayer(player);

            // Build the media item.
            MediaItem mediaItem = MediaItem.fromUri("https://storage.googleapis.com/exoplayer-test-media-0/BigBuckBunny_320x180.mp4");
            // Set the media item to be played.
            player.setMediaItem(mediaItem);
            // Prepare the player.
            player.prepare();
            // Start playback.
            player.play();
        }
    }

    @Override
    protected void onStop() {
        super.onStop();
        if (player != null) {
            player.release();
            player = null;
        }
    }
}

And in your activity_main.xml:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <com.google.android.exoplayer2.ui.StyledPlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

5. Deployment

ExoPlayer is an Android library, not a standalone application. Deployment involves integrating it into your Android application and then deploying your application to the Google Play Store or other Android app distribution platforms.

Deployment Steps (General Android Application Deployment):

  1. Build Release APK/App Bundle: In Android Studio, navigate to Build > Generate Signed Bundle / APK... and follow the prompts to create a signed release build.
  2. Google Play Console: Upload your signed App Bundle to the Google Play Console.
  3. Testing Tracks: Deploy to internal, alpha, or beta testing tracks to ensure stability.
  4. Production Release: Promote your application to the production track.

6. Troubleshooting

Given this project's deprecated status, troubleshooting should primarily focus on issues related to the 2.19.1 release or earlier versions.

  • "This GitHub project is deprecated" / "New ExoPlayer code is available in AndroidX Media": This is not an error but a strong recommendation. If you encounter issues that seem like bugs or missing features, the first and most important step is to migrate to AndroidX Media3. This deprecated repository will not receive updates.

  • exoplayer:2.19.1 was the last artifact released: If you are using a version older than 2.19.1 and encountering issues, try upgrading to 2.19.1 first. No further releases are planned for this repository.

  • Playback Errors (ExoPlaybackException):

    • Network Issues: Check android.permission.INTERNET and ensure the device has a stable network connection.
    • Media Format Support: Verify that the media format (e.g., HLS, DASH, MP4) and codecs are supported by ExoPlayer and the device.
    • Content URI: Double-check that the media URI is correct and accessible.
    • DRM Issues: If playing protected content, ensure your DRM setup (e.g., DrmSessionManager) is correctly configured.
    • BehindLiveWindowException (HLS): This can occur if the player falls too far behind a live stream. Ensure your HlsChunkSource (e.g., HlsMediaPlaylist) is configured to handle live streams appropriately, or that the network is sufficient.

  • DownloadService Notifications (Android 13+):

    • android.permission.POST_NOTIFICATIONS: If your targetSdkVersion is 33 or higher, you must request this permission at runtime from the user. Without it, notifications from DownloadService will not be shown.
    • Notification Channel: Ensure you've created a notification channel for your DownloadService as required by Android 8.0 (API level 26) and higher.

  • Performance Issues (Stuttering, Buffering):

    • Bandwidth: Check network speed.
    • Device Capabilities: Ensure the device has sufficient processing power and memory for the content being played.
    • TrackSelectionParameters: Review your TrackSelectionParameters to ensure appropriate track selections are made based on device capabilities and network conditions (e.g., maxVideoWidth, maxVideoHeight, maxVideoBitrate).
    • LoadControl: Customizing LoadControl can help adjust buffering behavior.

  • Migration to AndroidX Media3:

    • The official migration guide and script is the definitive resource.
    • Expect package name changes (e.g., com.google.android.exoplayer2 to androidx.media3.exoplayer).
    • Some APIs might have changed or been refactored.
    • Start with the migration script and then manually resolve any remaining compilation errors.
← Project overviewView alternatives to google/ExoPlayer →