Set up the player

This page introduces the player API and provides information about setting up the player within your development projects. When you create a player instance, you can start to integrate the Wowza Flowplayer into your Android application and take advantage of the player's robust features.

Create a player instance

The Flowplayer interface, together with the FlowplayerSupportFragment and FlowplayerView classes, are central to implementing and interacting with the player while using the Wowza Flowplayer Android SDK.

  • The Flowplayer interface provides the main entry point for interacting with the SDK, giving access to all public functions to manage the player.
  • The FlowplayerView class is an Android-specific view that contains the player, serving as a canvas for the Flowplayer interface and player UI. In the latest version of the Wowza Flowplayer Android SDK, the player is detached from the FlowplayerView class. Therefore, you have to get an instance of the player from the view and invoke commands on it. To learn more about this class, see FlowplayerView .
  • The FlowplayerSupportFragment class serves as a plug-and-play solution to integrate the player, wrapping the FlowplayerView instance and handling its lifecycle automatically. To learn more about this class, see FlowplayerSupportFragment .

Instead of using FlowplayerView.flowplayer each time you work with the player, we recommend creating a reusable player reference to simplify your code. You can assign this top-level variable for your FlowplayerView.flowplayer instance in your activity or fragment, then reuse it throughout the project.

The code examples in the FlowplayerSupportFragment and FlowplayerView sections demonstrate how to declare this reference to your flowplayer instance in your activity or fragment. We suggest you store your flowplayer variable in the highest level component in your code hierarchy, depending on your architecture.

Add a player to an activity

Activities are application components that provide the entry point to your Android application and a screen for user interactions. To get started with the player, you need to add it to an activity. There are two methods to complete this task:

You can refer to the following sections to learn more about each method and how to use it.

FlowplayerSupportFragment (recommended)

When adding the player to an activity, we recommend using the FlowplayerSupportFragment class. This approach serves as a plug-and-play solution, wrapping the FlowplayerView instance and handling its lifecycle automatically. It can also manage orientation and full-screen changes effectively.

However, using this class limits customizations to the player's user interface (UI). If you have specific or advanced needs to customize the UI, the FlowplayerView class may be more appropriate and can provide more granular control.

The FlowplayerSupportFragment class can be added in the same way as any other fragment, either via XML or programmatically using Kotlin.

XMLKotlin
Copy
Copied
<!-- Add to app/res/layout -->
<?xml version="1.0" encoding="utf-8"?>
<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/my_fragment"
    android:name="com.flowplayer.android.player.FlowplayerSupportFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
Copy
Copied
// Declare top-level reference to a flowplayer instance
lateinit var flowplayer: Flowplayer

// Create the fragment within your activity
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val playerFragment = FlowplayerSupportFragment.newInstance()
    supportFragmentManager
        .beginTransaction()
        .replace(R.id.player_holder, playerFragment)
        .commitNow()

    // Then get the instance of the FlowplayerView with
    flowplayer = playerFragment.getPlayer()
}
Info

If you add the fragment programmatically and plan to use the player instance immediately, then you must use commitNow() (recommended) or commit() with fragmentManager.executePendingTransactions(). We suggest the commitNow() approach if you don't need to push the player fragment to the back stack.

FlowplayerView

The FlowplayerView class sits at the core of the Wowza Flowplayer Android SDK. It serves as the actual player view, loading audio and video, controlling playback, and subscribing to player-related callbacks.

When you add FlowplayerView to an activity, you have more control over its lifecycle and UI customizations. If you don't need this level of additional control, we recommend using the FlowplayerSupportFragment method instead.

This class extends the FrameLayout ViewGroup subclass and can be added either via XML or programmatically as in this example:

Copy
Copied
<!-- Add to app/res/layout -->
<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.flowplayer.android.player.FlowplayerView
        android:id="@+id/my_flowplayer"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>

If you decide to use FlowplayerView, you must take extra steps to manage its lifecycle. There are two ways to achieve this:

  • If your activity or fragment inherits (directly or indirectly) from AndroidX's ComponentActivity or Fragment classes, then it also implements LifecycleOwner . In this case, register your activity or fragment lifecycle by adding the lifecycle object in its onCreate() method. For more, see the full FlowplayerLifecycleObserver reference documentation.
    Copy
    Copied
    override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      FlowplayerLifecycleObserver.registerLifecycle(lifecycle)
    }
  • If your activity or fragment does not implement LifecycleOwner , then you must call the FlowplayerView lifecycle methods manually by adding the following code inside the parent activity or fragment:
    Copy
    Copied
    override fun onStart() {
      super.onStart()
      flowplayerView.onStart()
    }
    
    override fun onResume() {
      super.onResume()
      flowplayerView.onResume()
    }
    
    override fun onPause() {
      flowplayerView.onPause()
      super.onPause()
    }
    
    override fun onStop() {
      flowplayerView.onStop()
      super.onStop()
    }
    
    override fun onDestroy() {
      flowplayerView.onDestroy()
      super.onDestroy()
    }

Load your media files

To work with the player in your Android applications, you need to define how the player loads media files.

By leveraging the Flowplayer interface, you can play media directly from a specific media URL. You can configure the player to use a local or remote URL. To load external media, initialize the player with an ExternalMedia instance as shown in the following example.

Copy
Copied
val externalMedia = ExternalMedia("https://link.to.a.media.file")
// Call the prepare() method for your flowplayer instance
flowplayer.prepare(externalMedia, true)

The ExternalMedia class offers the ability to include media with an ad schedule as well. For more information about this class, see the ExternalMedia reference documentation.

Set maximum bitrate (optional)

The Wowza Flowplayer Android SDK supports media formats, such as HLS, that contain video sources encoded at multiple bitrates. Setting a maximum bitrate limit forces the player to load and play only encodings with a bitrate below this limit. Unlike all other mandatory steps to set up the player on this page, this step is optional.

You can use the ExternalMedia class to apply this setting. As demonstrated in the following example, this class accepts a maxVideoBitrate parameter that sets the maximum bitrate for your media.

Copy
Copied
val externalMedia = ExternalMedia("https://link.t.o.a.media.file.m3u8", maxVideoBitrate = 500000)