Video externals: XMediaPlayer API

Wed Oct 24 09:57:12 EDT 2012

Hi friends,

here the complete API for the XMediaPlayer external, it is the same for the 
WMP and VLC version of the external.

I added analogies to the QuickTime player object of Livecode where possible.

I will post the API for the "XVideoJoiner" external tomorrow, there have been some
changes recently that I need to write down first.

Best

Klaus

--
Klaus Major
http://www.major-k.de
klaus at major.on-rev.com

------------------------------------------------------------------------------------------------------------------
XMediaPlayer API (WMP and VLC!)

1. Commands

XMediaPlayer_Open PlayerName,WindowId
Open a new instance of mediaplayer
PlayerName = any name (one word!) you want, use it to address the mediaplayer later
WindowId = window id of stack you want to display the video in

Example:
...
put the windowID of this stack into tWID
XMediaPlayer_Open "Your_Player",tWID
...
If a mediaplayer with that name already exists, then the command will be ignored!
---------------------------------------------------------------------
XMediaPlayer_Close PlayerName
Close instance of mediaplayer with name: PlayerName

Example:
...
XMediaPlayer_Close "Your_Player"
...
If a mediaplayer with that name does not exist, then the command will be ignored!
---------------------------------------------------------------------
XMediaPlayer_Pause PlayerName
Pause playback of mediaplayer

Example:
...
XMediaPlayer_Pause "Your_Player"
...
If a mediaplayer with that name does not exist, then the command will be ignored!
---------------------------------------------------------------------
XMediaPlayer_Play PlayerName
Start mediaplayer

Example:
...
XMediaPlayer_Start "Your_Player"
...
If a mediaplayer with that name does not exist, then the command will be ignored!
---------------------------------------------------------------------
XMediaPlayer_Stop PlayerName
Stop mediaplayer

Example:
...
XMediaPlayer_Stop "Your_Player"
...
If a mediaplayer with that name does not exist, then the command will be ignored!
---------------------------------------------------------------------
---------------------------------------------------------------------
2. Mediaplayer Properties

General syntax for setting a property:
XMediaPlayer_Set PlayerName, Name_of_Property, Value_of_Property

If a mediaplayer with that name does not exist, then the commands will be ignored!

URL = filename of video to display
Example:
...
XMediaPlayer_Set "Your_Player","url","/Users/klaus/Movies/MP4/ToTheOne1.mp4" ## Mac
XMediaPlayer_Set "Your_Player","url","C:/Movies/MP4/ToTheOne1.mp4" ## Windows
...
----------------------------------------------------------------------
RECT = position on screen for mediaplayer, rect like in Livecode: left,top,right,bottom

Example:
...
put the rect of grc "video placeholder" into tRect
XMediaPlayer_Set "Your_Player","rect",tRect
...
put 0,0,640,360 into tRect
XMediaPlayer_Set "Your_Player","rect",tRect
...
----------------------------------------------------------------------
VISIBLE - TRUE or FALSE, Hide or show mediaplayer. 

Example:
...
XMediaPlayer_Set "Your_Player","visible",false 
## hide mediaplayer
...
XMediaPlayer_Set "Your_Player","visible",true 
## show mediaplayer
...
----------------------------------------------------------------------
POSITION - Set a position in video, in seconds, integer/floating point values allowed
Analog to "currenttime" for a Livecode QuickTime player object

Example:
...
XMediaPlayer_Set "Your_Player","position",10
## Set the TIME in movie to 10 seconds
...
----------------------------------------------------------------------
STOPPOSITION - Set a time in movie where playback should stop in seconds, integer/floating point values allowed
Analog to "endtime" for a Livecode QuickTime player object

Example:
...
XMediaPlayer_Set "Your_Player","stopPosition",15
## Set the ENDTIME in movie to 15 seconds
...
When playback reaches the set "stopposition" the message "XMediaPlayer_Complete" (see below) will be sent!
----------------------------------------------------------------------
VOLUME - Volume of video, 0 to 100
Analog to "playloudness" for a Livecode QuickTime player object

Example:
...
XMediaPlayer_Set "Your_Player","volume",100
## Full volume
...
----------------------------------------------------------------------
----------------------------------------------------------------------
3. Functions

General syntax for getting a property:
function XMediaPlayer_Get(PlayerName, Name_of_Property) into tMediaPlayerProperty

If a mediaplayer with that name does not exist, then the commands will be ignored!

DURATION - Duration of mediaplayer in seconds (floating point)

Example:
...
put XMediaPlayer_Get("Your_Player","duration") into tMovieLength
set the endvalue of sb "my video progressbar" to tMovieLength
...
----------------------------------------------------------------------
RECT - Current position of mediaplayer overlay

Example:
...
put XMediaPlayer_Get("Your_Player","rect") into the_rect_I_have_set_but_forgotten
...
----------------------------------------------------------------------
VISIBLE - TRUE or FALSE = visibility of mediaplayer overlay

Example:
...
put XMediaPlayer_Get("Your_Player","visible") into tVideoVisibility
...
----------------------------------------------------------------------
POSITION - Current position in mediaplayer, in seconds (floating point)

Example:
...
put XMediaPlayer_Get("Your_Player","postion") into tCurrentTime
set the thumbpos of sb "my video progressbar" to tCurrentTime
...
----------------------------------------------------------------------
PAUSED - TRUE or FALSE, if playback is currently paused or not

Example:
...
put XMediaPlayer_Get("Your_Player","paused") into tCurrentPlayingState
...
----------------------------------------------------------------------
FORMATTEDSIZE - Dimensions of video in format: width in pixels COMMA height in pixels => 640,480

Example:
...
put XMediaPlayer_Get("Your_Player","formattedsize") into tDimensions
put item 1 of tDimensions into tVideoWidth
put item 2 of tDimensions into tVideoHeight
...
----------------------------------------------------------------------
VOLUME - Currently set volume 0 - 100

Example:
...
put XMediaPlayer_Get("Your_Player","volume") into tCurretnMoviePlayLoudness
...
----------------------------------------------------------------------
STOPPOSITION - Time in video where playback should stop. 
HINT: Some demuxers always return length of video, therefore you may want to track this internally,
but I never experienced this so far.

Example:
...
put XMediaPlayer_Get("Your_Player","stopposition") into the_time_in_movie_i_have_set_but_forgotten
...
----------------------------------------------------------------------
----------------------------------------------------------------------
4. These are two very special functions we needed for our first project.
They will return TRUE of FALSE if the queried codec collection (LAVFILTERS rsp. FFDShow) is installed or not.

Hint: In case you didn't know there are some free codec collections for Windows which will let you play 
more videoformats like MP4, FLV, XVID etc. with WMP and thus with the WMP version of the external: 
<http://1f0.de/downloads/>
<http://ffdshow-tryout.sourceforge.net>

Example:
...
XMediaPlayer_IsFilterInstalled("ffdshow") into tFFDSHOWinstalled
...
XMediaPlayer_IsFilterInstalled("lav") into tLAVFiltersInstalled
...
----------------------------------------------------------------------
----------------------------------------------------------------------
5. MediaPlayer messages:

XMediaPlayer_Complete PlayerName - Message is sent when the video reaches its end or the STOPTIME you have set before.
There is only ONE parameter: the name of the player that has stopped

Put this somewhere in message hierarchy.

Example:
on XMediaPlayer_Complete tPlayerName
   if tPlayerName = "Your_Player" then
       answer "End of transmission!"
  end if
end XMediaPlayer_Complete
----------------------------------------------------------------------
XMediaPlayer_LMouseUp
XMediaPlayer_RMouseUp
XMediaPlayer_MouseMove 

Messages are sent when the LEFT or RIGHT mousebutton has been clicked or the mouse is being moved inside of the mediaplayers rect .
NO parameter is being sent, so you need to check "the mouseloc" in that case!

Example:
on XMediaPlayer_LMouseUp
   put the mouseloc into tML
   if tML is within the rect of grc "video_placeholder" then
      ## mouse has been clicked in a mediaplayer
      ## do whatever you want to do in this case
   end if
end XMediaPlayer_LMouseUp