search

protyposis / MediaPlayer-Extended

Android MediaPlayer API-compatible media player library with exact seek and DASH support
Apache License 2.0
440 stars 127 forks source link
android android-api android-component android-mediaplayer dash media-player playback

readme

MediaPlayer-Extended Icon

MediaPlayer-Extended

The MediaPlayer-Extended library is an API-compatible media player library for Android supporting exact seeking to frames, playback speed adjustment, and DASH playback. It strives to be a direct replacement for the Android MediaPlayer and VideoView components and builds upon the Android MediaExtractor and MediaCodec API components. It is very lightweight, easy to use, makes native code / NDK fiddling unnecessary, and works from Android 4.1 up.

A demo is available on the Google Play Store.

Features

For the GLES hardware accelerated view with zooming/panning, shader effects and frame grabbing, that was part of this library until v3.x, please check Spectaculum.

Changelog

Support

For questions and issues, please open an issue on the issue tracker. Commercial support, development and consultation is available through Protyposis Multimedia Solutions.

Requirements

Users

There are many apps and libraries using this project. If you want to have your project listed here, open an issue, submit a pull request, or drop an email.

Usage

Usage is very simple because the library's aim is to be API-compatible with the default Android classes. The MediaPlayer in this library is the equivalent of Android's MediaPlayer, the VideoView is the equivalent of Android's VideoView.

To migrate from the Android default classes to this library, just replace the imports in your Java headers. If there are any methods missing, feel free to open an issue on the issue tracker or submit a pull request.

API

This are the important additions to Android's default components:

Method MediaPlayer VideoView Description
setDataSource(MediaSource) X X (setVideoSource) Sets a MediaSource (e.g. UriSource, FileSource, DashSource), see description below.
setSeekMode(SeekMode) X X Sets the seek mode (e.g. FAST, EXACT, ..., see the SeekMode enum). Default mode is EXACT.
getSeekMode() X X Gets the current seek mode.
setPlaybackSpeed(float) X X Sets the playback speed factor (e.g. 1.0 is normal speed, 0.5 is half speed, 2.0 is double speed). Audio pitch changes with the speed factor.
getPlaybackSpeed() X X Gets the current playback speed factor.
addCue(int, object?) X Adds a cue to the playback timeline. Cues can be used to synchronize events to media playback, e.g. for subtitles, slides, lyrics, or ads.
removeCue(cue) X Removes a cue from the playback timeline.
setOnCueListener(listener) X Listens to cues during playback.

MediaSource

This library adds additional methods to set the playback source, namely mediaPlayer.setDataSource(MediaSource source) and videoView.setVideoSource(MediaSource source). These methods expect an instance of an object implementing the MediaSource interface. A few common implementations are provided:

Additional media sources can be built by implementing the MediaSource interface. The advantage of this interface is that it provides a way to implement data sources above the file level, and that it can provide and sync multiple separate media sources to the same media player.

Gradle

To use this library in your own project, you can either (1) fetch the modules from the Maven Central repository, or checkout the Git repository and (2) install the modules to your local Maven repository or (3) include the required gradle modules directly.

Maven

The Maven Central Maven repository contains release builds of the library since v4.5.0, usage is similar to any other Maven dependency:

repositories {
    ...
    mavenCentral()
}

dependencies {
    ...
    implementation 'net.protyposis.android.mediaplayer:mediaplayer:<version>'
    implementation 'net.protyposis.android.mediaplayer:mediaplayer-dash:<version>'
}

Older version can be found in the legacy jcenter() repository. Run gradlew publishToMavenLocal to compile and install the modules to your local Maven repository.

Modules

MediaPlayer

The base module provides the MediaPlayer, which can be used as a replacement for the Android MediaPlayer, and the VideoView, which can be used as a replacement for the Android VideoView. To load a video, use either the compatibility methods known from the Android API to specify a file or URI, or supply a UriSource.

MediaPlayer-DASH

Extends the MediaPlayer base with DASH support. To play a DASH stream, supply the MediaPlayer or VideoView a DashSource with the URI of the MPD file or an externally parsed/constructed MPD object, and an AdaptationLogic. MPDs can be externally parsed with the DashParser. This component comes with two basic AdaptationLogic implementations, ConstantPropertyBasedLogic which selects a specified constant representation mode, and SimpleRateBasedAdaptationLogic, which monitors the bandwidth and tries to choose the best representation accordingly. It supports MP4, fragmented MP4 and WebM containers, with both file and byte-range requests. The DASH support does not cover the full standard, but many common use cases. DashSource can also be configured with a custom OkHttpClient instance, useful for HTTP request caching, cookie management, authentication, proxy settings, etc.

MediaPlayer-DASH has external dependencies on OkHttp, Okio, and ISO Parser.

Example:

Uri uri = Uri.parse("http://server.com/path/stream.mpd");
MediaSource dashSource = new DashSource(context, uri, new SimpleRateBasedAdaptationLogic());
mediaPlayer.setDataSource(dashSource); // or: videoView.setVideoSource(dashSource);

MediaPlayerDemo

This module is a demo app that incorporates all the main functionality of the MediaPlayer modules and serves as an example on how they can be used and extended. It is available for download as MediaPlayer-Extended Demo on the Google Play Store.

Proguard

-keep class * implements com.coremedia.iso.boxes.Box {* ; }
-keep class * implements com.coremedia.iso.fragment.MovieFragmentBox {* ; }
-dontwarn com.coremedia.iso.boxes.*
-dontwarn com.googlecode.mp4parser.authoring.tracks.mjpeg.**
-dontwarn com.googlecode.mp4parser.authoring.tracks.ttml.**

Issues & Limitations

DASH

The DASH support in this library is currently limited to the most common use cases. It supports video and audio, and switching between multiple representations thereof (bitrates and resolutions). Segments must be divided into separate files or explicit byte ranges and defined in a SegmentTemplate or SegmentList. The player can also display live streams (dynamic mode), but this is just a simple hack to demonstrate the ability. An evaluation of the DASH-IF test vectors is available here.

Currently not supported are single-segment representations, audio-only MPDs, multiple periods (it only plays back the first period), segment index box parsing (sidx), dynamic MPD updates, and encryption. The supported codecs are limited by their support through the Android MediaCodec.

There are two main cases when DASH fails:

Online Streaming Test URLs

These URLs have been tested and definitely work in the demo app:

License

Copyright (C) 2014, 2015, 2016, 2017, 2018, 2020, 2024 Mario Guggenberger mg@protyposis.net. Released under the Apache 2.0 license. See LICENSE for details.