Skip to content
An extensible media player for Android.
Kotlin Java
Branch: dev
Clone or download
Video Players
Latest commit 6e0322d Aug 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app feat: Reenable http requests Jun 13, 2019
clappr
doc chore(release): bump version Aug 15, 2019
gradle/wrapper chore(gradle): update gradle wrapper to 5.1.1 Jun 10, 2019
.gitignore chore(git): update git ignore to remove iml files Nov 21, 2016
.travis.yml chore(travis): update travis config to sdk 28 Jun 13, 2019
LICENSE chore(release): add license Dec 18, 2016
README.md chore: update kotlin version and gradle plugin version Aug 9, 2019
build.gradle chore: update kotlin version and gradle plugin version Aug 9, 2019
gradle.properties chore(build): increase gradle build heap size Dec 5, 2016
gradlew
gradlew.bat add initial project files Nov 19, 2014
issue_template.md chore/release: bump version Oct 9, 2018
settings.gradle refactor: rename player module to clappr Dec 9, 2016

README.md

Build Status Coverage Status License



Clappr for Android - Beta Version

❗️ Following events were changed to be compatible with clappr for WEB and iOS. ❗️

Name before 0.10.0 version New Name
Event.STALLED Event.STALLING
Event.WILL_CHANGE_SOURCE Event.WILL_LOAD_SOURCE
Event.DID_CHANGE_SOURCE Event.DID_LOAD_SOURCE
Event.BUFFER_UPDATE Event.DID_UPDATE_BUFFER
Event.POSITION_UPDATE Event.DID_UPDATE_POSITION

Using the Player

Dependencies

Clappr is a Kotlin library. If your app is too, be sure Kotlin version is 1.3.41 or bigger, and Android Support version is 28.0.0 or bigger.

The minimal API level supported is 16 (4.1).

It is possible to incorporate clappr into your project in two ways:

Local Reference

After cloning Clappr project, add following lines to dependencies in project/build.gradle:

dependencies {
    ...
    implementation project(':clappr')
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.3.41"
    ...
}

Remote Reference

It is possible to reference any release from Clappr on JCenter. Add following lines to repositories sections in build.gradle:

buildscript {
    repositories {
        jcenter()
        ...
    }
    ...
}

allprojects {
    repositories {
        jcenter()
        ...
    }
}

Following, add following lines to dependencies section in project/build.gradle:

dependencies {
    ...
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.3.41"
    implementation "com.android.support:appcompat-v7:28.0.0"
    implementation "com.android.support:support-v4:28.0.0"
    implementation 'com.google.android.exoplayer:exoplayer:2.9.2'

    implementation "io.clappr.player:clappr:0.12.0"
    ...
}

Clappr supports Java 8 resources, so it is necessary to add Java 8 compatibility in project/build.gradle.

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

For both local and remote reference, you can see how Sample app works.

Initialization

Before instantiating a io.clappr.player.Player, it needs to be initialized with the Application context:

// Add to onCreate of the Application class
Player.initialize(this)

Embed

Player is a Fragment and must be embedded in a container view of the activity in order to start playing.

First define a container frame to player on layout:

    <FrameLayout
        android:id="@+id/player_container"
        android:layout_width="match_parent"
        android:layout_height="@dimen/player_portrait_height" />

Following, instanciate a Player and attach it to container:

val player = Player()

val fragmentTransaction = fragmentManager.beginTransaction()
fragmentTransaction.add(R.id.player_container, player)
fragmentTransaction.commit()

Configuration

After instantiating, Player needs to be configured before it can be used to play any video.

🔴 Attention: Remember to always call the stop() method before calling the load() again

Event binding

Player implements the EventInterface interface for event binding. Client application associate any event to an object following the Callback interface.

The on or once Player methods can be used for binding. The only difference is that once bindings are only called a single time. These methods return a String id that can be used to cancel the binding with the off method.

The Player events are described by Event class and the data returned by EventData class.

For example, to listen the event when the video starts playing, and the event when the video ends successfully:

player.on(Event.PLAYING.value) { Logger.info("App","Playing") }
player.on(Event.DID_COMPLETE.value) { Logger.info("App", "Completed") }

Options

Options class presents the main options (source and mime-type) followed by a hashmap of optional parameters. An Options is the only parameter to Player configure method. Player optional parameters are described by ClapprOption class.

val optionMap = hashMapOf(ClapprOption.START_AT.value to 50)

player.configure(Options(source = "http://clappr.io/highline.mp4", options = optionMap))

Error Handling

All errors are reported through the Event.Error event. This event includes an ErrorInfo in its Bundle.

player.on(Event.ERROR.value) { bundle: Bundle? ->
            bundle?.getParcelable<ErrorInfo>(Event.ERROR.value)?.let {
                Logger.error("App","Error: ${it.code} ${it.message}", (it.extras?.getSerializable(ErrorInfoData.EXCEPTION.value) as? Exception))
            }
        }

Generic error codes (UNKNOWN_ERROR and PLAYBACK_ERROR) are also provided in ErrorCode class:

The data returned by the errors are described on ErrorInfoData.

Recommendations

Fullscreen

Application must handle all fullscreen transitions and behavior.

Player provides two events to indicate that the user has requested fullscreen transition:

player.on(Event.REQUEST_FULLSCREEN.value) { enterFullscreen() }
player.on(Event.EXIT_FULLSCREEN.value) { exitFullscreen() }

API Documentation

FAQ & Troubleshooting

Read this before open an issue

Contributors

Contributing

License

Sponsor

image

You can’t perform that action at this time.