API - Intent definition
Intent definition to launch playback activity of MX Player. Also, check the 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;
Play single or multiple videos.
Provide subtitles to be drawn together.
Select decoder and simple options such as video zoom, etc.
Receive playback results including whether it is completed or not, last playback position, etc.
You CANNOT;
Play or pause playback.
Touch user interface.
Change playback options except provided ones.
Change settings.
Access native features of MX Player such as extracting thumbnails, search videos, etc.
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 (Optional):
decode_mode
Type : byte
Values :
1 - HW decoder
2 - SW decoder
4 - HW+ 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 to degrade video output quality. It is not recommended at all.
video
Type: boolean
Set video visibility. This extra will be ignored if user makes their own choice on Playback screen > Menu > Display > Video.
video_list_is_explicit
Type: boolean
If set true, the entire video list will be played regardless 'Back to list' option on Settings > Player.
video_list
Type : Parcelable array (android.net.Uri[])
Values : Video playlist including URI provided on Data.
To prevent loading the next file automatically, provide a single length 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
Type : String[]
Values : Custom video titles of each video in video_list to be displayed to users.
Array size should exactly match with the size of video_list. Array elements can be null. In that case, the default name will be used.
If video_list.name and title are provided together, video_list.name will be used and title will be ignored.
video_list.size
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
Type : String[]
Values : File names of each videos in video_list.
Array size should exactly match with the size of video_list. Array 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
Type : String[]
Values : MovieHashes of each media in video_list.
Array size should exactly match with the size of video_list. Array 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.
Visit the following link for making hash string https://trac.opensubtitles.org/projects/opensubtitles/wiki/HashSourceCodes
subs
Type: Parcelable array (android.net.Uri[])
Values: subtitle list used for given video Uri (in the data field)
subs.name
Type: String[]
Values: Custom subtitle names to be displayed to users.
The array should have the same size as `subs`. Array elements can point to null instead of a valid string. In this case, the default name will be used. Even if this extra is provided, a custom name will not be used for subtitles defining the name inside the script or containing multiple tracks in a script file such as SAMI subtitles.
subs.filename
Type: String[]
Values: File names of each subtitle in `subs`.
Array size should exactly match with the size of `subs`. Array elements can be null for local media or filename can be retrieved from subtitle URI.
Providing filename may improve the accuracy of subtitle finding for remote/streaming media.
subs.enable
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
Type: long
Values: Size of the media file in bytes.
Providing size may improve the accuracy of subtitle finding for remote/streaming media. Not required for local files.
filename
Type: String
value: Filename of the media.
Providing filename may improve the accuracy of subtitle finding for remote/streaming media. Not required for local files or filename can be retrieved from video URI.
hash.opensubtitles
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 the 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
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
Type: boolean
Value: If set to true and error occurs, activity will play next video or close itself not showing error message.
secure_uri
Type: boolean
Value: If set to true, video uri will not be displayed in the property dialog box.
video_zoom
Type: int
Value: Override video zoom setting. Available values are: Fit to screen=1, Stretch=0, Crop=3, 100%=2
DAR_horz, DAR_vert
Type: float
Value: Override default DAR(display aspect ratio). Both extras should be provided together.
sticky
Type: boolean
Value: Override background play setting.
orientation
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
Type: int
Values:
0 - Volume up/down (default)
1 - Load next/previous video.
Override DPAD up/down key action.
Activity Result:
com.mxtech.intent.result.VIEW
Code:
Activity.RESULT_OK : Playback was completed or stopped by user request.
Activity.RESULT_CANCELED: User cancelled before starting any playback.
RESULT_ERROR (=Activity.RESULT_FIRST_USER): The last playback was ended with an error.
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
Type: int
Value: Duration of last played video in milliseconds. This extra will not exist if playback is completed.
end_by
Type : String
Value: Indicates the reason for activity closure. Can be one of the following values:
"user": User requested to leave activity.
"playback_completion": All playback completed.
Note that if the activity is finished after switching to background play, RESULT_OK will be returned at the time of the 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 the following links for more information; link #1, link #2
Can I have sample codes?
Fully featured sample codes can be downloaded from the following link: Sample Code v6