ITEC MediaPlayer

The ITEC MediaPlayer library is a video player library for Android supporting exact seeking to frames, playback speed adjustment, shader support, zooming & panning, frame extraction and a lot of media source protocols and formats, including DASH. It strives to be an API-compatible 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

• Direct replacement for Android components
• Frame-exact seeking
• Playback speed adjustment
• GLES shader support
• Picture zooming/panning support
• Frame extraction
• Local files and network sources
• Supports all Android network protocols and media formats
• DASH support
• Lightweight (all components total to ~100kB)

Changelog

• v1.3.2: compile and target SDK updated to 22, added to JCenter repository
• v1.3.1: support for separate audio and video sources added, lint error fix
• v1.3: DASH playback / representation switching greatly improved (no more screen resizing, skipped frames, and video artefacts, better segment caching), external dependencies updated, various other improvements
• v1.2.4: demo app enhanced with option to type/paste url and Crashlytics exception reporting
• v1.2.3: device compatibility improved, contrast/brightness adjustment filter added
• v1.2.2: hotfix for display aspect ratio
• v1.2.1: hotfix for video decoder crash
• v1.2: audio playback support, improved DASH rate based adaption, support for DASH non-square pixel aspect ratios, keep screen on during playback
• v1.0.1: do not catch up lost time after a lag, error handling for invalid URLs improved
• v1.0: initial release

Requirements

• Android API 16+ (Android 4.1 Jelly Bean)
• optional: Adreno GPU
• optional: OpenGL ES 3.0

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 and GLVideoView are equivalents 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, fill free to open an issue on the issue tracker or submit a pull request.

Gradle

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

JCenter repository

The JCenter Maven repository contains release builds of the library, usage is similar to any other Maven dependency:

repositories {
    ...
    jcenter()
}

dependencies {
    ...
    compile 'at.aau.itec.android.mediaplayer:mediaplayer:1.3.2'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-dash:1.3.2'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles:1.3.2'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles-flowabs:1.3.2'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles-qrmarker:1.3.2'
}

Local Maven repository

Run gradlew publishMavenPublicationToMavenLocal to compile and install the modules to your local Maven repository and add one or more of the following dependencies:

repositories {
    ...
    mavenLocal()
}

dependencies {
    ...
    compile 'at.aau.itec.android.mediaplayer:mediaplayer:1.3.2-SNAPSHOT'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-dash:1.3.2-SNAPSHOT'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles:1.3.2-SNAPSHOT'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles-flowabs:1.3.2-SNAPSHOT'
    compile 'at.aau.itec.android.mediaplayer:mediaplayer-gles-qrmarker:1.3.2-SNAPSHOT'
}

Components

The library is split into several logical components, comprising the base MediaPlayer and additional optional components that extend the functionality of the base.

MediaPlayer

The base component 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.

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

MediaPlayer-GLES

Extends the MediaPlayer base with a GLES surface and GLSL shader support. It provides the GLVideoView, a VideoView with a GL surface and a simple interface for custom shader effects. Effects implement the Effect interface and can be dynamically parameterized. It also provides the GLCameraView, which is a camera preview widget with effect support. It comes with a few simple effects, e.g. a sobel edge detector, a simple toon effect and some 9x9 kernel effects. The GLES views can be zoomed and panned with the typical touchscreen gestures.

MediaPlayer-GLES-FlowAbs

This module adds the FlowAbs shader effect to the GLES component and demonstrates the possibility to construct and use very elaborate shaders. It also offers various sub-effects that the flowabs-effect is composed of, including (flow-based) difference of Gaussians, color quantization and a tangent flow map.

MediaPlayer-GLES-QrMarker

This module is another example of an effect composed of multiple shaders. It is taken from QrMarker and provides a rather pointless and extremely slow QR marker identification effect, and a nice Canny edge detection effect.

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 ITEC MediaPlayer Demo on the Google Play Store.

Known Issues

• MediaPlayer: audio can get out of sync on slow devices
• MediaPlayer-DASH: MPD parser is basic and only tested with the test MPDs listed below
• MediaPlayer-DASH: representation switching can result in a short lag (this only happens with mp4/avc videos because reinitializing Android's MediaCodec takes some time; a workaround would be to prepare a second codec with a second surface, and switch them at the right frame; webm works flawlessly)
• MediaPlayer-GLES-FlowAbs: The OrientationAlignedBilateralFilterShaderProgram / FlowAbsBilateralFilterEffect does not work correctly for some unknown reason and is deactivated in the FlowAbs effect, making it slightly less fancy
• Exception handling needs to be improved

Device specific:

• MediaPlayer-GLES: GLCameraView's preview aspect ratio is slightly off on the Nexus 7 2013 back camera (seems to be a system bug)
• MediaPlayer-GLES-FlowAbs: Not working on Tegra devices because shaders contain dynamic loops

Tested and confirmed working on:

• LG Nexus 4 (Android 4.4.4/5.0/5.0.1, Adreno 320)
• LG Nexus 5 (Android 4.4.4/5.0/5.0.1, Adreno 330)
• ASUS Nexus 7 2012 (Android 4.4.4, Tegra 3, no FlowAbs)
• ASUS Nexus 7 2013 (Android 4.4.4/5.0/5.0.2, Adreno 320)
• ASUS Transformer TF701T (Android 4.4.2, Tegra 4, no FlowAbs)
• Samsung Galaxy SII (Android 4.1.2, ARM Mali-400MP4)
• Samsung Galaxy Note 2 (Android 4.4.4 CM, ARM Mali-400MP4)

Online Streaming Test URLs

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

• HTTP streaming:
  • http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4
  • http://www-itec.uni-klu.ac.at/dash/js/content/bunny_4000.webm
• DASH streaming:
  • all DASH MPDs on the ITEC DASH-JS page:
    • MP4 3 rep 50kbps to 150kbps: http://www-itec.uni-klu.ac.at/dash/js/content/bunny_ibmff_240.mpd
    • MP4 7 rep 200kbps to 700kbps: http://www-itec.uni-klu.ac.at/dash/js/content/bunny_ibmff_360.mpd
    • MP4 4 rep 900kbps to 2000kbps: http://www-itec.uni-klu.ac.at/dash/js/content/bunny_ibmff_720.mpd
    • MP4 6 rep 2500kbps to 8000kbps: http://www-itec.uni-klu.ac.at/dash/js/content/bunny_ibmff_1080.mpd
    • WebM 5 rep 200 kbps to 2000 kbps multiplexed audio: http://www-itec.uni-klu.ac.at/dash/js/content/sintel_multi_rep.mpd
    • WebM 7 rep 200 kbps to 4700 kbps multiplexed audio: http://www-itec.uni-klu.ac.at/dash/js/content/bigbuckbunny.mpd
    • WebM 7 rep 1000 kbps to 8000 kbps multiplexed audio: http://www-itec.uni-klu.ac.at/dash/js/content/bigbuckbunny_1080p.mpd
  • MP4 8 rep 250 to 6000 kbps separate audio: http://dj9wk94416cg5.cloudfront.net/sintel2/sintel.mpd

License

Copyright (C) 2014 Mario Guggenberger, Institute of Information Technology, Alpen-Adria-Universität Klagenfurt [email protected]. This project is released under the terms of the GNU General Public License. See LICENSE for details.