API - Intent definition

Intent definition to launch playback activity of MX Player. Also check sample codes attached below.


Unlike its page name, this is not actually an API definition but just an Intent definition for playing back videos through MX Player.

Using this Intent definition,

You CAN;
  1. Play single or multiple videos.
  2. Provide subtitles to be drawn together.
  3. Select decoder and simple options such as video zoom, etc.
  4. Receive playback result including whether it is completed or not, last playback position, etc.
You CANNOT;
  1. Play or pause playback.
  2. Touch user interface.
  3. Change playback options except provided ones.
  4. Change settings.
  5. Access native features of MX Player such as extracting thumbnails, search videos, etc.



[Supported Version]
Since 1.6

[Package]
com.mxtech.videoplayer.pro - Pro Edition
com.mxtech.videoplayer.ad - Free Edition.

[Action: android.intent.action.VIEW]
Data: 
Uri pointing to a media source.
Extras: 
(All extras are optional)
decode_mode
Type: byte
Values: 1 - HW decoder 2 - SW decoder

fast_mode
Type: boolean
Values: true to use SW fast mode when SW decoder is selected.

Fast mode is deprecated. Even though this can improve decoding speed in some cases, there are also chances degrade video output quality. It is not recommended at all.

video  Added in 1.8.7
Type: boolean

Set video visibility. This extra will be ignored if user make their own choice on Playback screen > Menu > Display > Video.

video_list_is_explicit  Added in 1.8.9
Type: boolean

If set true, entire video list will be played regardless 'Back to list' option on Settings > Player.

video_list
Type: parcelable array (android.net.Uri[])
Values: video play list including uri provided on Data.

To prevent loading next file automatically, provide single sized array having only "Data".

The uri used as the Intent data should be included in the video_list either.
For example, to play 1.mp4, 2.mp4, 3.mp4 in sequence, set data to 1.mp4 and put { 1.mp4, 2.mp4, 3.mp4 } to video_list.

If URI points to a file, it should be canonicalized and prefixed with 'file://'. 
video_list.name  Added in 1.7.31
Type: String[]
Values: Custom video titles of each videos in video_list to be displayed to users.

Array size should should exactly match with the size of video_list. Array elements can be null. In that case, default name will be used.

If video_list.name and title is provided together, video_list.name will be used and title will be ignored.

video_list.size Added in 1.8.4
Type: long[]
Values: Sizes of each videos in video_list.

Array size should exactly match with the size of video_list. Array elements can be 0 for local media.

Providing size may improve accuracy of subtitle finding for remote/streaming media. Not required for local files.

video_list.filename  Added in 1.8.4
Type: String[]
Values: File names of each videos in video_list.

Array size should exactly match with the size of video_listArray elements can be null for local media.

Providing file name may improve accuracy of subtitle finding for remote/streaming media. Not required for local files or file name can be retrieved from video URI
.

video_list.
hash.opensubtitles Added in 1.8.4
Type: String[]
Values: MovieHashes of each media in video_list.

Array size should exactly match with the size of video_listArray elements can be null for local media.

Used for better subtitle searching from OpenSubtitles.org. Not required for local files.

This extra should come with `video_list.size` and `video_list.filename` extra.


subs
Type: parcelable array (android.net.Uri[])
Values: subtitle list used for given video uri (in data field)

subs.name  Added in 1.7.31
Type: String[]
Values: Custom subtitle names to be displayed to users.

Array should have same size as `subs`. Array elements can point to null instead of valid string. In this case, default name will be used.

Even if this extra is provided, custom name will not be used for subtitles defining name inside script or containing multiple tracks in a script file such as SAMI subtitles.

subs.filename Added in 1.8.4
Type: String[]
Values: File names of each subtitles in `subs`.

Array size should exactly match with the size of `subs`. Array elements can be null for local media or file name can be retrieved from subtitle URI.

Providing file name may improve accuracy of subtitle finding for remote/streaming media.

subs.enable  Added in 1.6e
Type: parcelable array (android.net.Uri[])
Values: Initially visible subtitles.

In the following cases, subtitle URI is different from file URI since single file can contain multiple subtitle tracks.

If URI is pointing a file, URI should have 'file' scheme, such as file:///sdcard/sub.srt
  • SAMI Subtitles: {file-uri}#{track-name} ex) file:///sdcard/movie1.smi#encc
title
Type: String
Values: Title text.

size Added in 1.8.4
Type: long

Values: Size of media file in bytes.

Providing size may improve accuracy of subtitle finding for remote/streaming media. Not required for local files.

filename Added in 1.8.4
Type: String
value: File name of the media.

Providing file name may improve accuracy of subtitle finding for remote/streaming media. Not required for local files or file name can be retrieved from video URI.

hash.opensubtitles Added in 1.8.4
Type: String
Values: OpenSubtitles.org MovieHash of given media.

Used for better subtitle searching from OpenSubtitles.org. Not required for local files. 

This extra should come with `size` and `filename` extra.

Visit following link for making hash string;
https://trac.opensubtitles.org/projects/opensubtitles/wiki/HashSourceCodes
position
Type: int
Values: resume position in milliseconds. presence of this extra forces to resume given position not giving user a chance to play from the beginning.
return_result
Type: boolean
Values: set true to receive resulting intent through Activity.onActivityResult() call.

headers  Added in 1.7.11
Type: String[]
Values: Headers to be sent along with the server request for videos and subtitles.
           (Before 1.8.4, this extra will not be used for downloading subtitles.)

Key and value should appear in turn. 

e.g) String[] headers = { 
          "User-Agent", "Mozilla compatible/1.0", 
          "Authorization", "(Access Token)",
          "Extra Key", "(Extra Value)" };

This feature has limitation if used for HW decoder; 1) It only works with Android 2.2 and above. 2) Before Android 4.0, default header cannot be overriden. For example, if you pass "User-Agent", it will not replace default User-Agent to given value but default and given header will be passed altogether.

suppress_error_message  Added in 1.7.14
Type: boolean
Value: If set to true and error occurs, activity will play next video or close itself not showing error message.

secure_uri   Added in 1.7.14
Type: boolean
Value: If set to true, video uri will not be displayed in the property dialog box.

video_zoom   Added in 1.7.23
Type: int
Value: Override video zoom setting. Available values are: Fit to screen=1, Stretch=0, Crop=3, 100%=2

DAR_horz, DAR_vert  Added in 1.7.23
Type: float
Value: Override default DAR(display aspect ratio). Both extras should be provided together.

sticky  Added in 1.7.23
Type: boolean
Value: Override background play setting.

orientation  Added in 1.8.9
Type: int
Values: One of following values;

0 - Landscape
8 - Reverse Landscape
6 - Auto rotation (Landscape)
1 - Portrait
9 - Reverse Portrait
7 - Auto rotation (Portrait)
10 - Auto rotation
-1 - System default
99999 - Match video orientation

Override screen orientation setting.

keys.dpad_up_down  Added in 1.8.9
Type: int
Values: 0 - Volume up/down (default), 1 - Load next/previous video.

Override DPAD up/down key action.

[Result:  com.mxtech.intent.result.VIEW]
Code:
Activity.RESULT_OK : Playback was completed or stopped by user request.
Activity.RESULT_CANCELED: User canceled before starting any playback. Added in 1.8.4
RESULT_ERROR (=Activity.RESULT_FIRST_USER): Last playback was ended with an error. 
Added in 1.8.4
Data:
Last played media URI. 
Extras:
decode_mode
Type: byte
Value: Used decoding mode

position
Type: int
Value: Last playback position in milliseconds. This extra will not exist if playback is completed.

duration  Added in 1.7.23
Type: int
Value: Duration of last played video in milliseconds. This extra will not exist if playback is completed.

end_by  Added in 1.7.19
Type: String
Value: Indicates reason of activity closure. Can be one of following values:
  • "user": User requested to leave activity.
  • "playback_completion": All playback completed.
Note that if activity is finished after switching to background play, RESULT_OK will be returned at the time of activity finished.

[MIME Type]
By setting proper MIME type, you can avoid ActivityNotFoundException exception regardless of passing URI.

Even if MIME type is not provided, Intent can be delivered to MX Player depending on the file extension of Intent uri(data). Most popular extensions are supported including avi, mkv, mp4, 3gp, asf, divx, flv, ts, wmv and so forth.

*CAVEAT: For http/https URIs, result will not be returned unless directly specifying activity class name by calling Intent.setClassName(). Class name for free edition is com.mxtech.videoplayer.ad.ActivityScreen and pro edition is com.mxtech.videoplayer.ActivityScreen.     

For example,

Intent intent = new Intent(Intent.ACTION_VIEW);
Uri videoUri = Uri.parse("http://host:port/playlist.m3u8");
intent.setDataAndType( videoUri, "application/x-mpegURL" );
intent.setPackage( "com.mxtech.videoplayer.pro" );
startActivity( intent );


FAQ

How can I launch MX Player from a web page?

  • You can use a URL with "intent" scheme.

    Example

    <a href="intent:http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8 #Intent;package=com.mxtech.videoplayer.ad;S.title=New%20title;end">Launch through Intent scheme.</a>
  • Check following links for more information; link #1, link #2

Can I have sample codes?

  • Fully featured sample codes are available bottom of this page.
ċ
sample_code.zip
(19k)
J.H. Kim,
Sep 24, 2016, 5:41 AM