Synote Media Fragment Player

Basic Usage

Synote Media Fragment Player is designed for highlighting the media fragments included in the multimedia file URIs. However, if the media fragment syntax is not included in the URI, smfplayer will still be able to play it, but nothing will be highlighted. For example, if you have an mp4 file online:

http://synote.org/resource/yunjiali/bigbuck.mp4

You only need to attach the media fragment string at the back of this URI like:

http://synote.org/resource/yunjiali/bigbuck.mp4#t=10,20&xywh=120,120,120,120

which means you want to replay the 10s to 20s of this video and highlight the spatial areas with left:120, top:120, height:120, width:120. This also works for the files with local files with relative path. For URIs of YouTube and Dailymotion, you can do the same. For example,

http://www.youtube.com/watch?v=KkWI-DHLD_M#t=10,20&t=25,33&xywh=360,120,160,320

Note: Either t or xywh is required for media fragment URI. The xywh will be relative to the actual width and height of the player if they are in pixel. Use percent if you want them to be independent of the player width.

Init and Destroy

Synote Media Fragment Player is a jQuery plugin, so you need to include the js and css files related to smfplayer and medialement.js into the <head>. The jQuery library is also required.

		        			/*-- <head> --*/
		        			<link rel="stylesheet" type="text/css" href="mediaelementplayer.min.css" />
		        			<link rel="stylesheet" type="text/css" href="smfplayer.css" />
		        			<script type="text/javascript" src="path_to_jquery"></script>
		        			<script type="text/javascript" src="mediaelement-and-player.min.js"></script>
		        			<script type="text/javascript" src="smfplayer.min.js"></script>
		        			
		        			/*-- <body> --*/
		        			<div id="player_div"></div>
				      		<script type="text/javascript">
								var uriStr = "http://path/to/file.mp4#t=11,19&xywh=120,120,120,120";
								$(document).ready(function(){ 	 	    		
									var mfuri = uriStr; //Media Fragment URI string
									//initialise smfplayer
									var player = $("#player_div").smfplayer({mfURI:mfuri}/*options*/);
									//destroy smfplayer
									$("#player_div").smfplayer('destroy');
								});
							</script>
		        		

See Player Options for more information about options. You can also define the success and error method in the options. For example, the following code registers a timeupdate listener and updates the text in currenttime_span to the current time.

			        		var player = $("#player_div").smfplayer({
					    		mfURI:mfuri, 
					    		success:function(mediaElement,domObject,p){
						    		mediaElement.addEventListener('timeupdate', function(e){
							    		var ct = mediaElement.currentTime;
							    		$("#currenttime_span").text(ct);
						    		});
					    		}
					    	});
					    
Playback Modes

There are mainly three playback modes for the temporal fragment playback defined in smfplayer, depending on the media fragment URI and the settings of player Options. The "start time" and "end time" are defined in the temporal dimension of the media fragment. If no temporal dimension is defined, they are referred to the whole video/audio.

Mode Description
Only once (default) The temporal dimension of the media fragment will only be replayed once. The video/audio will be played from the start time and paused at the end time, and the spatial dimension will be highlighted during this period of time if the spatialEnabled is true. However, this will happen only once after the start of playing. When the media fragment is playing, you cannot drag the progress bar before the start time of the media fragment, but you can drag it after the end time, indicating the playback of media fragment has completed. After that, the video/audio will be played as normal, i.e. the player won't jump to the start time or paused at the end time.
Always By setting the mfEnabledAlways to true, smfplayer will only replay the part of the video/audio between the start and end time. Any attempt to jump out of this time range will trigger the player to start playing from the start time or paused at the end time.
None If the option mfURI doesn't include any media fragment on temporal dimension, or the syntax of media fragment is not correct, no fragment will be replayed. In this case, smfplayer will act just like the normal <video> or <audio> tags in HTML5.

For the spatial dimension of the media fragment, you can enable or disable the highlighting by setting the spatialEnabled. Once set to true, the spatial fragment will always be highlighted along with the temporal fragment. If no temporal fragment is defined, the spatial fragment will be highlighted all through the video.

Note: The spatial dimension doesn't make sense for audio resources, but if you set width and height in the for audio resources, the spatial highlight will still display.

Player Options

Smfplayer defines its own initialising options, but as a wrapper of mediaelement.js, all the options defined in mediaelement.js are still applicable. However, some of the options are overridden.

Options in smfplayer

Note: '*' indicates required attribute.

Name Default Description
*mfURI N/A The URI of the multimedia resource following the syntax defined in W3C Media Fragment URI 1.0.
width 640 The width in pixel of the video on the webpage, no matter if it's audio or video. This option will override the videoWidth in mediaelement.js.
height 480 The height in pixel of the video on the webpage, no matter if it's audio or video. This option will override the videoHeight in mediaelement.js.
originalWidth 320 the original width of the video in pixel. This is used to display spatial fragment defined in percentage format.
originalHeight 240 the original height of the video in pixel. This is used to display spatial fragment defined in percentage format.
isVideo true A flag indicating whether the mfURI is a video or audio.
mfAlwaysEnabled false A flag indicating whether you want to playback the media fragment ONLY, i.e. no other part of the multimedia resource will be played.
spatialEnabled true A flag indicating whether the spatial dimension of the media fragment is enabled. If it is set to false, the spatial dimension will not be highlighted.
spatialStyle {} A JSON object specifying the style of the spatial highlighting. The default style is defined in smfplayer.css as border:solid 2px yellow. See jQuery.css() for more detail of this usage.
autoStart true A flag indicating whether smfplayer should automatically start playing the media fragment after initialising the player. If it is set to false, user need to click the play button and smfplayer will start playing the media fragment.
tracks
since v1.0
[ ] an array containing JSON object for initialising track element in video/audio. For example: {srclang:"en",kind:"subtitles",type:"text/vtt",src:"a.vtt"}or
{srclang:"zh",kind:"chapter",type:"text/plain",src:"a.srt"}
srclang is the language code of the track. kind is either "subtitle" or "chapter". type is the mime type of the subtitle or chapter. The mime type for srt file is "text/plain" and for webvtt is "text/vtt". src is the relative or url of the subtitle file.
Options in MediaElement.js

Most of the player options defined in MediElement.js are still applicable in smfplayer. The following table shows some exceptions:

Mejs smfplayer Description
defaultVideoWidth
videoWidth
audioWidth
width
isVideo
width in smfplayer overrides defaultVideoWidth and videoWidth. Audio or video will be decided by the isVideo option.
defaultVideoHeight
videoHeight
audioHeight
height
isVideo
height in smfplayer overrides defaultVideoHeight and videoHeight. Audio or video will be decided by the isVideo option.

Player APIs

Smfplayer defines its own APIs for video/audio playback based on MediaElement.js. In addition, we also define the media fragment APIs for the highlighting of media fragments.

Playback APIs
The follow APIs are used to control the smfplayer. You can call the API by smfplayer.func(params).
API Params Description
play() N/A Play video/audio
pause() N/A Pause video/audio
load() N/A Reset the the player and start loading new video/audio from scratch.
getPosition() N/A Get the current position of the video/audio in milliseconds.
setPosition() position Set the current position of the video/audio in milliseconds.
Note: The actual currentTime after calling this method usually is some number around the position parameter depending on different browsers and files.
getDuration() N/A Get the duration of the video/audio in milliseconds.
getMeplayer() N/A Get the MediaElement.js player object, which is wrapped by smfplayer. This object is the same as the one initialised by using new MediaElementPlayer(options).
getOptions()
since v1.0
N/A Get the values of settings for the smfplayer instance.
getDomObject()
since v1.0
N/A Return the audio/video DOM element that the smfplayer create.
stop() N/A DEPRECATED since v1.0
Media Fragment APIs
Based on the playback APIs, smfplayer also defines several APIs to control the media fragment playback. If the media fragment (temporal and spatial fragment) is not defined, these method will do nothing.
API Params Description
playmf() N/A Play the temporal fragment defined in the mfURI option.
showxywh() xywh Show the highlight of the spatial fragment defined in mfURI option. The param xywh is a json object {x: left, y:top, w:width, h:height} indicating the highlighting area in the video.
hidexywh() N/A Show the highlight of the spatial fragment.
getMFJson() N/A Get the json object parsed by the Media fragment parser.