mergAV

mergAV is an iOS and OS X 10.6+ external that adds functions and commands related to the AVFoundation framework.
This currently includes using the standard iOS modal dialogs to pick, record, save and edit video and displaying
a video preview control to record video, detect barcodes and capture still images.

function mergAVPick [pSource],[pQuality],[pDuration],[pIncludeVideo],[pIncludePhoto],[pPopoverRect],[pOriginalImage]

Picks a video from a recording or the library and saves it in the temporary folder and returns the file path. iOS Only.

Parameters:

  • pSource - (optional with "camera" default) the source of the video which will be one of:

    • library
    • album
    • camera
    • rear camera
    • front camera
  • pQuality - (optional with "medium" default) the quality of the video
    • high - iOS 3.1+
    • medium - iOS 3.1+
    • low - iOS 3.1+
    • 640x480 - iOS 4.0+
    • 1280x720 - iOS 5.0+
    • 960x540 - iOS 5.0+
  • pDuration - (optional with 600 default) The maximum duration of the video
  • pIncludeVideo - (optional with "true" default) Allow the user to pick video.
    • true
    • false
  • pIncludePhoto - (optional with "false" default) Allow the user to pick photo's.
    • true
    • false
  • pPopoverRect - (optional with "" default) The rect to display the popover from if picking an existing video or photo. If not specified the target rect will be used.
  • pOriginalImage - (optional with "false" default) (iOS8 only) This option is for picking images from the library where you want the original image data rather than the image that iOS normally gives us from the image picker.
    • true
    • false

Returns one of:

  • mergAV:Error: source not available
  • mergAV:Error: no video recording
  • mergAV:Error: failed
  • mergAV: cancelled
  • The path to the saved video file

Code sample

put mergAVPick("library","medium",180) into tVideoPath
put mergAVPick("front camera","low") into tVideoPath

function mergAVEditVideo pFilePath,[pQuality],[pDuration]

Edits the video and saves the result in the temporary folder and returns the file path. iOS Only.

Parameters:

  • pFilePath - the file path of the video
  • pQuality - (optional with "medium" default) the quality of the video
    • high - iOS 3.1+
    • medium - iOS 3.1+
    • low - iOS 3.1+
    • 640x480 - iOS 4.0+
    • 1280x720 - iOS 5.0+
    • 960x540 - iOS 5.0+
  • pDuration - (optional with 600 default) the maximum duration of the video

Returns one of:

  • mergAV:Error: can't edit video
  • mergAV: cancelled
  • The path to the saved video file

Code sample

put mergAVEditVideo(tVideoPath,"medium",180) into tEditedVideoPath
put mergAVEditVideo(tVideoPath,"low") into tEditedVideoPath

function mergAVCanSaveVideo pFilePath

Checks to see if the video file is compatible with the photo library. iOS Only.

Parameters:

  • pFilePath - the file path of the video

Returns true if the video can be saved to the library

Code sample

if mergAVCanSaveVideo(tVideoPath) then show btn "edit"

function mergAVCanAccessPhotoLibrary

Checks the authorisation status of the app to access the photo library. iOS 6.0+ Only.

Returns true if the app can access the photo library

Code sample

if mergAVCanSaveVideo(tVideoPath) then show btn "edit"

function mergAVCanRecord [pType]

Checks if the user has authorised the app to record audio or video

Parameters:

  • pType - (optional with "video" default) The type of media to check if the user has authorised recording of. On of:

    • video
    • audio

Returns true if the app can record that type of media

command mergAVRequestMediaAccess [pType]

Request access for the media type from the user. The mergAVMediaAccess message is sent to the object that called mergAVRequestMediaAccess

Parameters:

  • pType - (optional with "video" default) The type of media to check if the user has authorised recording of. On of:

    • video
    • audio

message mergAVMediaAccess pType,pGranted

Set to the object that called mergAVRequestMediaAccess

Parameters:

  • pType - The media type. One of:|video|audio
  • pGranted - true if access was granted

command mergAVSaveVideo pFilePath

Saves video file to the library. iOS Only.

Parameters:

  • pFilePath - the file path of the video

Code sample

mergAVSaveVideo tVideoPath

function mergAVVideoThumbnail pFilePath,[pSize],[pTime]

Create a thumbnail image of a video. iOS Only.

Parameters:

  • pFilePath - the file path of the video
  • pSize - (optional with "100,100" default) the max width,max height that the thumbnail should be scaled and fit to
  • pTime - (optional with 1 default) the time in the video that the thumbnail is taken from

Returns a thumbnail from a video in PNG format.

command mergAVSaveImage pFilePath

Saves image file to the library including metadata. iOS Only.

Parameters:

  • pFilePath - the file path of the image

function mergAVImageThumbnail pFilePath,[pSize]

Create a thumbnail image from an image file. iOS Only.

Parameters:

  • pFilePath - the file path of the image
  • pSize - (optional with "100,100" default) the max width,max height that the thumbnail should be scaled and fit to

Returns a thumbnail from an image in PNG format.

command mergAVCamCreate

Create the camera control.

Sets the result to If the user is not authorized for audio and video recording there is an error message and the control is not created

command mergAVCamDelete

Delete the camera control.

command mergAVCamSet pProp,pValue

Set a property of the camera control.

Parameters:

  • pProp - the property to set which will be one of:

    • rect - the rect of the control
    • visible - the visible of the control
    • quality - the quality of the camera which will be one of:
      • photo
      • high
      • medium
      • low
      • 352x288
      • 640x480
      • iFrame960x540
      • 1280x720
      • iFrame1280x720. The camera defaults to high.
    • camera - one of:
      • rear camera
      • front camera. The camera defaults to rear. You may use a device id as returned by video devices or muxed devices.
    • microphone - This will be a device id as returned by audio devices.
    • flash - one of:
      • on
      • off
      • auto. The camera defaults to auto.
    • torch - one of:
      • on
      • off
      • auto. The camera defaults to auto.
    • exposure mode - one of: locked
      • auto - the device automatically adjusts the exposure once and then changes the exposure mode to locked.
      • continuous. If set to auto - the device continuously monitors exposure levels and auto exposes when necessary.
    • white balance mode - one of: locked
      • auto - the device automatically adjusts the white balnce once and then changes the white balnce mode to locked.
      • continuous. If set to auto - the device continuously monitors white balnce levels and adjusts when necessary.
    • max frame rate - a frame rate in frames per second
    • min frame rate - a frame rate in frames per second
    • zoom - (iOS only) a number between 1.0 and the max zoom
  • pValue - the value to set the property to

function mergAVCamGet pProp

Get the current property of the camera control.

Parameters:

  • pProp - the property to return which will be one of:

    • rect - the rect of the control
    • visible - the visible of the control
    • quality - the quality of the camera which will be one of:
      • photo
      • high
      • medium
      • low
      • 352x288
      • 640x480
      • iFrame960x540
      • 1280x720
      • iFrame1280x720. The camera defaults to high.
    • camera - one of:
      • rear camera
      • front camera. The camera defaults to rear. You may use a device id as returned by video devices or muxed devices.
    • microphone - This will be a device id as returned by audio devices.
    • flash - one of:
      • on
      • off
      • auto. The camera defaults to auto.
    • torch - one of:
      • on
      • off
      • auto. The camera defaults to auto.
    • video devices - a tab delimited list of video devices with the first item the device id and the second a device name (read only).
    • audio devices - a tab delimited list of audio devices with the first item the device id and the second a device name (read only).
    • muxed devices - a tab delimited list of audio devices with the first item the device id and the second a device name (read only).
    • exposure mode - one of: locked
      • auto - the device automatically adjusts the exposure once and then changes the exposure mode to locked.
      • continuous. If set to auto - the device continuously monitors exposure levels and auto exposes when necessary.
    • white balance mode - one of: locked
      • auto - the device automatically adjusts the white balnce once and then changes the white balnce mode to locked.
      • continuous. If set to auto - the device continuously monitors white balnce levels and adjusts when necessary.
    • max frame rate - a frame rate in frames per second
    • min frame rate - a frame rate in frames per second
    • zoom - (iOS only) a number between 1.0 and the max zoom
    • max zoom - (iOS only) the maximum the video can be zoomed (read only)

Returns the property

command mergAVCamCaptureImage [pAnimate],[pJPEGQuality],[pFilePath],[pThumbnailSize]

Capture an image from the camera control. The shutter sound is part of the AVFramework.

Parameters:

  • pAnimate - (optional with "true" default) animate the image capture with a white flash.

    • true
    • false
  • pJPEGQuality - (optional with 1 default) a value between 0 and 1 for the compression quality for the JPEG data returned.
  • pFilePath - (optional with "" default) the file path to save the image
  • pThumbnailSize - (optional with "" default) the size of the thumbnail to send in the mergAVImageCaptured message. If not specified the thumbnail is the full image size.

message mergAVCamImageCaptured pImage

Sent to the control that called mergAVCaptureImage

Parameters:

  • pImage - the image in JPEG format. This will be either the full size image or the thumbnail size if a thumbnail was requested.

message mergAVCamImageSaved pFilePath

Sent to the control that called mergAVCaptureImage

Parameters:

  • pFilePath - the file path the image was saved to as JPEG.

Code sample

on mouseUp
  mergAVCamCaptureImage false,0.8,the documents folder&"/photo.jpg",(100,100)
end mouseUp
 
on mergAVCamImageCaptured pImage
  put pImage into image "thumbnail"
end mergAVCamImageCaptured
 
on mergAVCamImageSaved pFilePath
  set the filename of image "full size" to pFilePath
end mergAVCamImageSaved

command mergAVCamStartRecording pFilePath

Start recording a video.

Parameters:

  • pFilePath - the file path to save the video

command mergAVCamStopRecording

Stop recording a video.

message mergAVCamRecordingFinished pFilePath

Sent to the control that called mergAVCaptureImage when the recording is finished.

Parameters:

  • pFilePath - the path of the video file

message mergAVCamRecordingBegan

Sent to the control that called mergAVCaptureImage when the recording begins.

Code sample

on mouseUp
   if the label of me = "Start Recording" then
      set the label of me to "Stop Recording"
      mergAVCamStartRecording
   else
      set the label of me to "Start Recording"
      mergAVCamStopRecording
   end if
end mouseUp
 
on mergAVCamRecordingBegan
   show graphic "recording"
end mergAVCamRecordingBegan
 
on mergAVCamRecordingFinished pFilePath
   hide graphic "recording"
   put mergAVCamVideoThumbnail(pFile,(the width of image 1,the height of image 1)) into image 1
   set the uFile of image 1 to pFile
end mergAVCamRecordingFinished

command mergAVCamStartBarcodeReader [pBarcodeTypes]

Start detecting barcodes.

Parameters:

  • pBarcodeTypes - (optional with if default) if you want to limit the barcode reader to specific barcode types to improve performance then use this parameter to provide a return delimited list of barcode types. The barcode types must match those returned by the mergAVCamBarcodeTypes function.

command mergAVCamStopBarcodeReader

Stop detecting barcodes.

message mergAVCamBarcodeFound pBarcode,pBarcodeType

Sent to the control that called mergAVCamStartBarcodeReader when a barcode is detected.

Parameters:

  • pBarcode - the text or number read from the barcode
  • pBarcodeType - the type string for the barcode

function mergAVCamBarcodeTypes

Get a list of possible barcode types

Returns A list of supported barcode types

function mergAVAssetCreate pURL

Create an asset from a URL

Parameters:

  • pURL - the url to load the asset from

Returns a pointer to the asset in memory

command mergAVAssetRelease pAssetPointer

Release the asset from memory

Parameters:

  • pAssetPointer - a pointer to the asset in memory

function mergAVAssetGet pAssetPointer,pProp

Get the value of an asset property. This function also works on an asset composition.

Parameters:

  • pAssetPointer - a pointer to the asset in memory
  • pProp - the name of the property requsted which will be one of:
    • composable
    • duration
    • exportable
    • has protected content
    • lyrics
    • playable
    • preferred rate
    • preferred volume
    • provides precise duration and timing
    • readable
    • metadata formats
    • available chapter locales
    • media characteristics with media selection options - iOS only
    • tracks
    • preferred transform - the affine transform that should be applied to the asset

Returns the property requested

function mergAVAssetTrackGet pAssetPointer,pAssetTrackID,pProp

Get the value of an asset track property. This function also works on an asset composition track.

Parameters:

  • pAssetPointer - a pointer to the asset in memory
  • pAssetTrackID - the id of the asset track
  • pProp - the name of the property requsted which will be one of:
    • enabled
    • estimated data rate
    • extended language tag
    • language code
    • media type
    • natural size
    • natural time scale
    • nominal frame rate
    • self contained
    • time range - start time and duration in milliseconds
    • playable
    • total sample data length
    • preferred volume
    • metadata formats
    • preferred transform - the affine transform that should be applied to the asset track

Returns the property requested

function mergAVCompositionCreate

Create a composition.

Returns a pointer to the composition in memory

command mergAVCompositionRelease pCompositionPointer

Release a composition from memory

Parameters:

  • pCompositionPointer - a pointer to the composition in memory

command mergAVCompositionInsertAsset pCompositionPointer,pAssetPointer,pStart,pDuration,pTime

Insert all tracks from an asset time range into a composition at a specified time.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pAssetPointer - a pointer to the asset in memory
  • pStart - the start time in milliseconds of the asset that you want added to the composition
  • pDuration - the duration in milliseconds of the asset that you want added to the composition
  • pTime - the time in milliseconds in the composition that you want the asset to be added to

command mergAVCompositionInsertEmptyTimeRange pCompositionPointer,pStart,pDuration

Insert an empty time range into all tracks of a composition.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pStart - the start time in milliseconds of the asset that you want added to the composition
  • pDuration - the duration in milliseconds of the asset that you want added to the composition

command mergAVCompositionScaleTimeRange pCompositionPointer,pStart,pCurrentDuration,pNewDuration

Scale time range into all tracks of a composition.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pStart - the start time in milliseconds of the time range you want to scale
  • pCurrentDuration - the new duration in milliseconds of the time range you want to scale
  • pNewDuration - the new duration in milliseconds of the time range you want to scale

function mergAVCompositionTrackCompatibleWithAssetTrack pCompositionPointer,pAssetPointer,pAssetTrackID

Get the id of a composition track that is compatible with a specified asset track

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pAssetPointer - a pointer to the asset in memory
  • pAssetTrackID - the id of the asset track

Returns the id of a composition track that can be used to add the asset track to the composition

function mergAVCompositionTrackCreate pCompositionPointer,pMediaType

Creates a composition tract in a composition.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pMediaType - the media type of the composition track to be created

Returns the id of the composition track created

command mergAVCompositionTrackInsertAssetTrack pCompositionPointer,pCompositionTrackID,pAssetPointer,pAssetTrackID,pStart,pDuration,pTime

Insert a time range of an asset track into a composition track at a specified time.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pCompositionTrackID - the id of the composition track
  • pAssetPointer - a pointer to the asset in memory
  • pAssetTrackID - the id of the asset track
  • pStart - the start in milliseconds time of the asset track that you want added to the composition track
  • pDuration - the duration in milliseconds of the asset track that you want added to the composition track
  • pTime - the time in milliseconds in the composition track that you want the asset to be added to

command mergAVCompositionTrackInsertEmptyTimeRange pCompositionPointer,pCompositionTrackID,pStart,pDuration

Insert an empty time range into a track of a composition.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pCompositionTrackID - the id of the composition track
  • pStart - the start time in milliseconds of the empty time range to add to the composition track
  • pDuration - the duration in milliseconds of the empty time range that you want added to the composition track

command mergAVCompositionTrackScaleTimeRange pCompositionPointer,pCompositionTrackID,pStart,pCurrentDuration,pNewDuration

Scale time range into a track of a composition.

Parameters:

  • pCompositionPointer - a pointer to the composition in memory
  • pCompositionTrackID - the id of the composition track
  • pStart - the start time in milliseconds of the time range you want to scale
  • pCurrentDuration - the new duration in milliseconds of the time range you want to scale
  • pNewDuration - the new duration in milliseconds of the time range you want to scale

function mergAVVideoCompositionCreate

Create a video composition. A video composition provides information to the export session on how to render the exported video.

Returns a pointer to the video composition in memory

command mergAVVideoCompositionRelease pVideoCompositionPointer

Release a video composition from memory

Parameters:

  • pVideoCompositionPointer - a pointer to the video composition in memory

command mergAVVideoCompositionSet pVideoCompositionPointer,pProp,pValue

Parameters:

  • pVideoCompositionPointer - a pointer to the video composition in memory
  • pProp - the name of the property you are setting which will be one of:
    • frame duration - in milliseconds
    • render size - width,height
    • render scale - real number used to zoom in on the video
  • pValue - the value to set the property to.

command mergAVVideoCompositionAddInstruction pVideoCompositionPointer,pStart,pDuration

Add an instruction to a video composition

Parameters:

  • pVideoCompositionPointer - a pointer to the video composition in memory
  • pStart - the time start time of the instruction in milliseconds
  • pDuration - the duration of the instruction in milliseconds

command mergAVVideoCompositionAddLayerInstruction pVideoCompositionPointer,pCompositionPointer,pCompositionTrackID,[pTransform],[pTransformTransition],[pOpacity],[pOpacityTransition]

Add a layer instruction to the last instruction added to the video composition. Layer instructions present tracks in highest to lowest order so the first layer added will be the top layer.

Parameters:

  • pVideoCompositionPointer - a pointer to the video composition in memory
  • pCompositionPointer - a pointer to the composition in memory
  • pCompositionTrackID - the id of the composition track
  • pTransform - (optional with "" default) an affine transform in the form "a,b,c,d,tx,ty" to be applied to the composition track at the start of the instruction
  • pTransformTransition - (optional with "" default) an affine transform in the form "a,b,c,d,tx,ty" to be applied to the composition track as a ramp from pTransform at the end of the instruction. If not set pTransform will remain constant.
  • pOpacity - (optional with 2 default) a value between 0 and 1 for the opacity at to be applied to the composition track at the start of the instruction.
  • pOpacityTransition - (optional with 2 default) a value between 0 and 1 for the opacity at to be applied to the composition track as a ramp from pOpacity at the end of the instruction. If not set pOpacity will remain constant.

function mergAVAssetExportSessionCreate pAssetPointer,pPreset

Create an asset export session to write a composition to a file.

Parameters:

  • pAssetPointer - a pointer to the asset in memory. This may also be a composition pointer.
  • pPreset - an asset export session preset available from mergAVAssetExportSessionCompatiblePresets(pAssetPointer).

Returns a pointer to the asset export session in memory

command mergAVAssetExportSessionRelease pAssetExportSessionPointer

Release an asset export session from memory

Parameters:

  • pAssetExportSessionPointer - a pointer to the asset export session in memory

function mergAVAssetExportSessionCompatiblePresets pAssetPointer

Get a list of asset export session presets that are compatible with an asset.

Parameters:

  • pAssetPointer - a pointer to the asset in memory. This may also be a composition pointer.

Returns a list of asset export session presets that are compatible with the asset.

function mergAVAssetExportSessionPresets

Get a list of asset export session presets.

Returns a list of asset export session presets.

command mergAVAssetExportSessionSet pAssetExportSessionPointer,pProp,pValue

Parameters:

  • pAssetExportSessionPointer - a pointer to the asset export session in memory
  • pProp - the name of the property you are setting which will be one of:
    • output url
    • output file type
    • file length limit
    • audio mix - Not yet implemented
    • should optimize for network use
    • video composition - a pointer to a video composition in memory
    • metadata - Not yet implemented
    • time range - Not yet implemented
  • pValue - the value to set the property to.

function mergAVAssetExportSessionGet pAssetExportSessionPointer,pProp

Parameters:

  • pAssetExportSessionPointer - a pointer to the asset export session in memory
  • pProp - the name of the property you are getting which will be one of:
    • supported file types
    • status
    • progress
    • error

Returns the value of the property

command mergAVAssetExportSessionExport pAssetExportSessionPointer,pCompletionHandler

Export the asset to a file asynchronously.

Parameters:

  • pAssetExportSessionPointer - a pointer to the asset export session in memory
  • pCompletionHandler - the callback message to send when the export is complete

command mergAVAssetExportSessionCancelExport pAssetExportSessionPointer

Cancel an export.

Parameters:

  • pAssetExportSessionPointer - a pointer to the asset export session in memory

function mergAVAffineTransformIdentity

This will return the affine transform that makes no changes to the image.

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformMakeRotation pAngle

This will return the affine transform identity rotated by pAngle.

Parameters:

  • pAngle - the angle in radians

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformMakeScale pScaleX,pScaleY

This will return the affine transform identity scaled by pScaleX and pScaleY.

Parameters:

  • pScaleX - the scale to apply in the X direction where 1 makes no chage and 2 doubles the size.
  • pScaleY - the scale to apply in the Y direction where 1 makes no chage and 2 doubles the size.

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformMakeTranslation pTranslateX,pTranslateY

This will return the affine transform identity moved by pTranslateX and pTranslateY.

Parameters:

  • pTranslateX - the value to move the x-axis.
  • pTranslateY - the value to move the y-axis.

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformConcat pTransform1,pTransform2

Concatenate two affine transforms

Parameters:

  • pTransform1 - an affine transform as "a,d,c,d,tx,ty"
  • pTransform2 - an affine transform as "a,d,c,d,tx,ty"

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformInvert pTransform

Invert an affine transform.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformRotate pTransform,pAngle

This will return the affine transform rotated by pAngle.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pAngle - the angle in radians

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformScale pTransform,pScaleX,pScaleY

This will return the affine transform scaled by pScaleX and pScaleY.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pScaleX - the scale to apply in the X direction where 1 makes no chage and 2 doubles the size.
  • pScaleY - the scale to apply in the Y direction where 1 makes no chage and 2 doubles the size.

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformTranslate pTransform,pTranslateX,pTranslateY

This will return the affine transform moved by pTranslateX and pTranslateY.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pTranslateX - the value to move the x-axis.
  • pTranslateY - the value to move the y-axis.

Returns an affine transform as "a,d,c,d,tx,ty"

function mergAVAffineTransformRect pTransform,pRect

This will apply the affine transform to a rect and return the result.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pRect - the rect to be transformed in the form "left,top,right,bottom"

Returns the transformed rect.

function mergAVAffineTransformSize pTransform,pSize

This will apply the affine transform to a size and return the result.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pSize - the size to be transformed in the form "width,height"

Returns the transformed size.

function mergAVAffineTransformPoint pTransform,pPoint

This will apply the affine transform to a point and return the result.

Parameters:

  • pTransform - an affine transform as "a,d,c,d,tx,ty"
  • pPoint - the point to be transformed in the form "x,y"

Returns the transformed point.

function mergAVPlayerCreate pAssetPointer,[pVideoCompositionPointer]

Create a player control from an asset or composition with an optional video composition.

Parameters:

  • pAssetPointer - a pointer to the asset in memory. This may also be a composition pointer.
  • pVideoCompositionPointer - (optional with a default) a pointer to the video composition in memory

Returns a pointer to the asset export session in memory

function mergAVPlayerCreateFromURL pURL

Create a player control from a url.

Parameters:

  • pURL - the url to load the asset to play from

Returns a pointer to the asset export session in memory

command mergAVPlayerRelease pPlayerPointer

Release a player from memory

Parameters:

  • pPlayerPointer - a pointer to the player in memory

command mergAVPlayerSet pPlayerPointer,pProperty,pValue

Set a player property.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pProperty - the name of the property you are setting which will be one of:
    • rect - the rect of the control
    • visible - the visible of the control
    • rate - the play rate of the player where 0 is paused. 1 is normal forward play and -1 is reverse. See "can play fast forward" and "can play fast reverse" properties
    • video gravity - how to size the video within the rect of the player. One of:
      • stretch
      • aspect
      • aspect fill
    • forward playback end time - set the time at which playback should end when the playback rate is positive. Time should be in milliseconds. The value of this property has no effect on playback when the rate is negative.
    • reverse playback end time - set the time at which playback should end when the playback rate is negative. Time should be in milliseconds. The value of this property has no effect on playback when the rate is positive.
  • pValue - the value to set the property to.

function mergAVPlayerGet pPlayerPointer,pProperty

Get a player property.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pProperty - the name of the property you are getting which will be one of:
    • rect - the rect of the control
    • visible - the visible of the control
    • rate - the play rate of the player where 0 is paused. 1 is normal forward play and -1 is reverse. See "can play fast forward" and "can play fast reverse" properties
    • video gravity - how to size the video within the rect of the player. One of:
      • stretch
      • aspect
      • aspect fill
    • forward playback end time - set the time at which playback should end when the playback rate is positive. Time should be in milliseconds. The value of this property has no effect on playback when the rate is negative.
    • reverse playback end time - set the time at which playback should end when the playback rate is negative. Time should be in milliseconds. The value of this property has no effect on playback when the rate is positive.
    • can play fast forward - true if the player can play at a rate greater than 1
    • can play fast reverse - true if the player can play at a rate less than -1
    • ready for display - true if the player is ready for display
    • duration - the duration of the player. Times are in milliseconds.
    • current time - the current time of the player. Times are in milliseconds.

Returns the value of the property

command mergAVPlayerDo pPlayerPointer,pDo,[pOption1],[pOption2],[pOption3]

Perform a specified operation with the player.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pDo - the thing you want the player to do which will be one of:
    • play - start playing
    • pause - pause the player
    • seek - seek a time in the player. pOption1 must be a time in milliseconds. To have a highly accurate seek you may provide two additional times in pOption2 and pOption3 however this may result in a much slower seek. The message mergAVSeekCompletion is sent to the control that called mergAVPlayerDo.
    • replace asset - replace the player asset with a new one. pOption1 must be a valid asset pointer.
    • step by count - moves the player's current item's current time forward or backward by a specified number of steps. pOption1 must be an integer. A positive number steps forward, a negative number steps backward.
  • pOption1 - (optional with "" default) a player action option
  • pOption2 - (optional with "" default) a player action option
  • pOption3 - (optional with "" default) a player action option

function mergAVPlayerCreatePeriodicTimeObserver pPlayerPointer,pTime,pCallback

Observer periodic times while a player is playing and send a custom message to the contol that created the player. The message is also invoked whenever time jumps and whenever playback starts or stops. If the interval corresponds to a very short interval in real time, the player may invoke the block less frequently than requested. Even so, the player will invoke the block sufficiently often for the app to update indications of the current time appropriately in its end-user interface.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pTime - a time in milliseconds.
  • pCallback - a callback message to send when the player reaches the periodic time. The message has two parameters:|the pointer for the player|time in milliseconds.

Returns a pointer the time observer that was created

function mergAVPlayerCreateBoundaryTimeObserver pPlayerPointer,pTimes,pCallback

Observer boundary times while a player is playing and send a custom message to the contol that created the player.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pTimes - a list of times in milliseconds.
  • pCallback - a callback message to send when the player reaches the time. The message has two parameters:|the pointer for the player|time in milliseconds.

Returns a pointer the time observer that was created

command mergAVPlayerReleaseTimeObserver pPlayerPointer,pTimeObserverPointer

Stop observing the periodic or boundary times and release the time observer from memory.

Parameters:

  • pPlayerPointer - a pointer to the player in memory
  • pTimeObserverPointer - a pointer the time observer to be released

message AVPlayerItemDidPlayToEndTimeNotification pPlayerPointer

Sent to the control that created the player when the player played to the end.

Parameters:

  • pPlayerPointer - a pointer to the player in memory

message AVPlayerItemFailedToPlayToEndTimeNotification pPlayerPointer

Sent to the control that created the player when the player failed to play to the end.

Parameters:

  • pPlayerPointer - a pointer to the player in memory

message AVPlayerItemTimeJumpedNotification pPlayerPointer

Sent to the control that created the player when when the item’s current time has changed discontinuously.

Parameters:

  • pPlayerPointer - a pointer to the player in memory

message AVPlayerItemPlaybackStalledNotification pPlayerPointer

iOS 6 only. Sent to the control that created the player when when some media did not arrive in time to continue playback.

Parameters:

  • pPlayerPointer - a pointer to the player in memory

command mergAVAudioSessionSetCategory pCategory,[pMixWithOthers],[pDuckOthers],[pAllowBluetooth],[pDefaultToSpeaker]

Set the audio session category.

Parameters:

  • pCategory -

    • ambient - For an app in which sound playback is nonprimary—that is, your app can be used successfully with the sound turned off. This category is also appropriate for “play along�? style apps, such as a virtual piano that a user plays over iPod audio. When you use this category, audio from other apps mixes with your audio. Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).
    • solo ambient - The default category; used unless you set a category
    • playback - For playing recorded music or other sounds that are central to the successful use of your app. When using this category, your app audio continues with the Silent switch set to silent or when the screen locks. (The switch is called the Ring/Silent switch on iPhone.) This category normally prevents audio from other apps from mixing with your app's audio.
    • record - For recording audio; this category silences playback audio. Recording continues with the screen locked.
    • play and record - Allows recording (input) and playback (output) of audio, such as for a VOIP (voice over IP) app. Your audio continues with the Silent switch set to silent and with the screen locked. (The switch is called the Ring/Silent switch on iPhone.)This category is appropriate for simultaneous recording and playback, and also for apps that record and play back but not simultaneously. If you want to ensure that sounds such as Messages alerts do not play while your app is recording, use the "record" category instead.This category normally prevents audio from other apps from mixing with your app's audio unless pMixWithOthers is true.
    • audio processing - For using an audio hardware codec or signal processor while not playing or recording audio. Use this category, for example, when performing offline audio format conversion. This category disables playback (audio output) and disables recording (audio input). Audio processing does not normally continue when your app is in the background. However, when your app moves to the background, you can request additional time to complete processing.
    • multi-route - Allows you to output distinct streams of audio data to different output devices at the same time. For example, you would use this category to route audio to both a USB device and a set of headphones. Use of this category requires a more detailed knowledge of, and interaction with, the capabilities of the available audio routes. This category may be used for input, output, or both.
  • pMixWithOthers - (optional with "false" default) Setting this property to true allows audio mixing with other apps. Other aspects of these categories, such as their Silent switch behavior, are not affected. (The switch is called the Ring/Silent switch on iPhone.) When the audio session category changes, such as during an interruption, the value of this property reverts to false. To regain mixing behavior you must then re-set this property.
    • true
    • false
  • pDuckOthers - (optional with "false" default) For audio session categories that allow audio mixing with other apps, specifies whether other audio should be reduced in level when your app produces sound. This property has a value of false by default. When your app is finished playing sound, be sure to set this property back to false to remove ducking.
    • true
    • false
  • pAllowBluetooth - (optional with "false" default) Allows a paired Bluetooth device to appear as an available audio input route. By default, the value of this property is false. This property can be used to modify the "record" or "play and record" categories. Attempting to set this property to true will fail for all other categories. This property affects the "play and record" category as follows: If the audio input to the device is coming from a Bluetooth headset, setting this property to true results in audio output also going to the Bluetooth headset.
    • true
    • false
  • pDefaultToSpeaker - (optional with "false" default) Specifies whether or not to route audio to the speaker (instead of to the receiver) when no other audio route, such as a headset, is connected. By default, the value of this property is false. This property retains its value through an audio route change (such as when plugging in or unplugging a headset), and upon interruption; it reverts to its default value only upon an audio session category change. This property can be used only with the "play and record" category.
    • true
    • false

Sets the result to an error message if setting the category failed

command mergAVAudioSessionSetMode pMode

iOS5+. Set the audio session mode. An audio session mode is a key that identifies a set of device audio configuration details, such as whether or not the device performs automatic gain adjustment on incoming audio. A mode refines the configuration provided by a category.

Parameters:

  • pMode -

    • default - When this mode is in use, audio session behavior matches that of iOS versions prior to iOS 5.0. You can use this mode with every audio session category. On devices more than one built-in microphone, the primary microphone is used.
    • voice chat - Specify this mode if your app is performing two-way voice communication, such as using Voice over Internet Protocol (VoIP). When this mode is in use, the device’s tonal equalization is optimized for voice. For use with the "play an record" audio session category. On devices with more than one built-in microphone, the primary microphone is used.
    • video recording - Specify this mode if your app is recording a movie. For use with the "record" audio session category. Also works with the "play and record" category. On devices with more than one built-in microphone, the microphone closest to the video camera is used. Using this mode may result in the system providing appropriate audio signal processing.
    • measurement - Specify this mode if your app is performing measurement of incoming audio. When this mode is in use, the device does not perform automatic gain adjustment on incoming audio. For use with the "record" or "play and record" audio session categories. On devices with more than one built-in microphone, the primary microphone is used.
    • movie playback - iOS 6 only. Specify this mode if your app is playing back movie content. When this mode is in use, the device engages any appropriate signal processing hardware to improve audio content played over the built-in speaker.

Sets the result to an error message if setting the category failed

command mergAVAudioSessionSetActive pActive

Activate/deactivate the audio session. Use mergNotify to handle interruption notifications like AVAudioSessionDidEndInterruptionNotification and AVAudioSessionDidBeginInterruptionNotification. After an interruption reset the category and reactivate your audio session.

Parameters:

  • pActive -

    • true
    • false

Sets the result to an error message if setting the category failed

function mergAVAudioSessionOtherAudioIsPlaying

When a user launches your app, sound may already be playing on the device. This is especially salient if your app is a game. For example, the iPod may be playing music, or Safari may be streaming audio. In such a case, “Sound�? in iOS Human Interface Guidelines advises you to assume that the user expects the other audio to continue as they play your game. In such a case, use the Ambient category, which supports mixing with other audio; and do not play your usual background soundtrack.

Returns bool-enum