XVideoJoiner API

Thu Oct 25 12:42:10 EDT 2012

Hi friends,

here the promised API for the XVideoJoiner external.
I have some days off and will be available again on 11/06/2012, If you have questions.

Best

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

General Movie Info

Function: xVideoJoinerGetInfo("path/to/videofile")

Returns the video dimensions and length of a videofile in this format: WidthxHeight in pixels,Length in seconds

Example:
...
try
  put xVideoJoinerGetInfo(“C:/Videos/myvideo.avi") into tVideoInfo
catch errornum
  answer "Not a compatible video file!"
  exit to top
end try
## Success: -> 320x240,55.0
replace "x" with "," in tVideoInfo
put item 1 of tVideoInfo into tVideoWidth
put item 2 of tVideoInfo into tVideoHeight
put item 3 of tVideoInfo into tVideoDuration
...
---------------------------------------------------------------------

Extract frames (snapshots) from a given time in movie to a JPEG file.
Works in "batch mode", means you can extract more than 1 frame with this function.

Function: xVideoJoinerGetSnapShot(tMoviePath,tWidth,tHeight,"tArrayName",Use_KeyFrame)

tMoviePath = absolute path to a valid movie file
tWidth = desired width fo resulting JPEG file
tHeight = desired height of resulting JPEG file

"tArrayName" (QUOTES mandatory!) = a multidimensional array with one or more keys in this format:
tArrayName[1][time in movie in seconds*][outpath to jpeg file 1]
tArrayName[2][time in movie in seconds*][outpath to jpeg file 2]

*Integer or floating allowed.

See example below for exact format.

Use_KeyFrame = TRUE or FALSE

Since I am not a video expert, I will just post the explanation that the programmer gave me.
What I DO know: 
if you pass TRUE then the snapshot will be more accurate in time, but may take longer to process
if FALSE, well, the opposite of the avove :-)

Here is what the programmer told me:
..................................................................................................................
1. You want the frame corresponding to second 25.0 to be decoded
2. When you open the external for snapshot, the decoder needs to parse the
initial header of the file for details and to initialize it
3. Then it has to find the nearest keyframe (I-Frame) behind second 25.0
4. Then it needs to decode all frames from the found keyframe to the time
you've requested (25.0)
5. Now imagine that the nearest keyframe behind second 25.0 is located at
time 10.0 !? You will need to decode everything from second 10.0 to 25.0!!!
15.0 seconds of movie to get 1 frame!
6. The option 2 I was talking about was referring to decoding only the
nearest keyframe behind second 25.0 (in this example, of course). Now
imagine if you only decoded the nearest keyframe and you ask for frame at
20.0 seconds: you will have the same keyframe as in second 25.0, since the
nearest keyframe behind the requested time is at second 10.0.
..................................................................................................................

Example: Extract 5 frames from a movie starting from time 5 (seconds in movie) every 5 seconds -> 5,10,15,20,25

...
put (“C:/Videos/myvideo.avi") into tMoviePath
put (“C:/Videos/myvideo_frame_") into tJPEGFile

## Fill array
repeat with i = 1 to 5
  put i*5 into tCurrentNumber
  put tJPEGFile & tCurrentNumber & ".jpg" into tArrayName[i]["filename"]
  put tCurrentNumber into tArrayName[i]["time"]
end repeat

 try
    get get xVideoJoinerGetSnapShot(tMoviePath,640,360,"tArrayName",false)    
 catch errornum
      answer errornum
      exit to top
   end try
...

Known issues:
There seem to be some issues with older QuickTime codecs like "Sörensen 3", which may result in poor output image quality, but works fine with more up-to-date codecs!
------------------------------------------------------------

VideoJoiner commands and functions

Function: xVideoJoinerGetParams("tArray",tQuality,tSize)
Gets output resolution, bitrate and framerate parameters for a given set of input parameters.

"tArray" (QUOTES mandatory!) name of the array you are passing, see below.
tQuality = the desired quality of the resulting movie, which is not yet rendered to file with this function!
Possible values for tQuality: "low", "medium" or "high" -> better = higher bit- and framerate

tSize = dimensions of resulting videofile -> "640x360"
If you pass "0x0" as the size parameter, the maximum possible extrapolated resolution will be used to generate the output video.
Means the external will take the dimenson of the largest video dimension of the passed videofile that will cover all other dimensions.

Example:
...
put “C:/Videos/myvideo.avi" into tArray[1]["filename"]
put "0" into tArray[1]["starttime"]
put "10" into tArray[1]["endtime"]

put “C:/Videos/yourvideo.avi" into tArray[2]["filename"]
put "3" into tArray[2]["starttime"]
put "13" into tArray[2]["endtime"]

## Let the external compute the best size:
put "0x0" into tSize

## Low bit- and framerate
put "low" into tQuality
put xVideoJoinerGetParams("tArray",tQuality,tSize) into tResult
...
Will put soemthing like this into tResult:
1001,1024x768,196608000,320000,25.000
-> JobID, Computed size of video, Bitrate of video in bit/seconds, Bit depth of videosound, Framerate of output videofile
Or returns an ERROR if that is the case
---------------------------------------------------------------

Function xVideoJoinerStart("tArray",tOutputFile,tQuality,tSize,tMetadata,tMP3,tMixingRatio)
Syntax similar to xVideoJoinerGetParams, but this will render the videofile to disc!

Hint: Output is always the MP4 format!

tArray (QUOTES mandatory!) name of the array you are passing, see below.

tOutPutFile = abolute path for the resulting videofile
tQuality = the desired quality of the resulting movie, which is not yet rendered to file with this function!
Possible values for tQuality: "low", "medium" or "high" -> better = higher bit- and framerate

tSize = dimensions of resulting videofile -> "640x360"
If you pass "0x0" as the size parameter, the maximum possible extrapolated resolution will be used to generate the output video.
Means the external will take the dimenson of the largest video dimension of the passed videofile taht will ocver all other dimensions.

tMetaData = you can add text as metadata, that you can query with the xVideoJoinerGetMetadata() function, see below.
Maximum 1 KB!

tMP3 = absolute path to any MP3 file
You can add any MP3 file, to mix this to the sound of the video, or to replace the videosound completely.
Leave it empty, if you do not wnat to add an MP3 sound. In taht case you need to pass 0 as tMixingRatio

tMixingRatio = 0 to 100, where 0 = NO MP3 sound = videosound only
Or any value in between, e.g use 50 to have 50% MP3 sound and 50% videosound
Use 100 to only have MP3 sound and no videosound at all.

Example:
## Will create a MP4 vieo which consists from the first 10 secxons of first video and 10 seconds (3 to 13) of second video.
...
put “C:/Videos/myvideo.avi" into tArray[1]["filename"]
put "0" into tArray[1]["starttime"]
put "10" into tArray[1]["endtime"]

put “C:/Videos/yourvideo.avi" into tArray[2]["filename"]
put "3" into tArray[2]["starttime"]
put "13" into tArray[2]["endtime"]

put specialfolderpath("desktop") & "/videojoinerarraytest.mp4" into tOutputFile
put "0x0" into tSize
put "low" into tQuality
put "Hollow world!" into tMetadata
put "C:/Sounds/mymp3.mp3" into tMP3
put 50 into tMixingratio

put xVideoJoinerStart("tArray",tOutputFile,tQuality,tSize,tMetadata,tMP3,tMixingratio) into tResult
put item 1 of tResult into tJobID
...
Will put something like this into tResult:
1001,1024x768,196608000,320000,25.000
JobID, Computed size of video, Bitrate of video in bit/seconds, Bit depth of videosound, Framerate of output videofile
Or returns an ERROR if that is the case

Here the JobID (first item of tResult) is important to query an display the progress of the rendering!

HInt: the external is multithreaded, so the video will be rendered in the background and you can start more than 1 renderjob, if you like and you have a fast machine!

-----------------------------------------------------------------------------------

Function: xVideoJoinerQuery(tJobID) 
Use this to query and display the progress

tJobID = the first item of the result of the xVideoJoinerStart function = a floating value between 0 and 1, where 1 means job is finished!

Example:
command QueryProgress tJobID
  put xVideoJoinerQuery(tJobID) into tProgress
  if tProgress < 1 then
      set the thumbpos of sb "renderprogress" to (tProgress * 100)
      send "QueryProgress tJobID" to me in 1 secs
      put the result into tExportResult
   else   
      ## Rendering complete
      get xVideoJoinerStop(tJobID)
      cancel tExportResult
  end if
end QueryProgress
------------------------------------------------------------------------------------

Function: xVideoJoinerStop(tJobID)

Use this function to cancel any not yet finished renderjob, or to stop a finished job (necessary to avoid memory leaks!)

tJobID = the first item of the result of the xVideoJoinerStart function = a floating value between 0 and 1, where 1 means job is finished!

Example:
...
get xVideoJoinerStop(tJobID)
## Will return something like "1001 stopped" or an ERROR if that is the case
...
--------------------------------------------------------------------------------------

Function xVideoJoinerGetMetadata(tVideo)
Use this to query the meatadata you have set with the xVideoJoinerStart() function.

tVideo = abolute path to the video file you want to get the metadata from.

Example:
...
put xVideoJoinerGetMetadata("C:/Videos/myvideo.avi") into tMetaData
##it also returns an error if that’s the case
...
------------------------------------------------------------------------------------ 