Type Function
Library media.*
Return value none
Revision Release 2023.3686
Keywords media, video, playback, remote video
See also native.newVideo()


Plays the video at the specified path (both local and remote) in a device-specific popup media player.

During video playback, the media player interface takes over. If the showControls function argument is true, the user can adjust playback (start, stop, seek, etc.). Additionally, you may specify a listener to get notified when the video has ended. Note that this function is asynchronous, so any code that follows will be executed. After that, the application code will continue to run on iOS devices, but on Android devices, the application will be suspended until the video playback is complete.

Supported video formats are platform- and version-dependent. The iOS video player supports playback of movie files with the .mov, .mp4, .m4v, and .3gp filename extensions and using the following compression standards:



This API is not supported on Windows.


If the path to the video is a URL, you must add the INTERNET permission to the build.settings file in order to play the video.

settings =
   android =
      usesPermissions =


media.playVideo( path [, baseSource ], showControls, listener )
path (required)

String. The local filename or a remote URL for the video.

baseSource (optional)

Constant. Optional parameter that controls how the local filename path is interpreted. It can either be one of the system-defined directory constants, or media.RemoteSource (use this to access video on a remote server).

showControls (required)

Boolean. If true, then the user can adjust playback (start, stop, seek, etc.).

listener (optional)

Listener. Listener to notify when the video has ended. The listener can be either a function listener or a table listener. If it's a table, it must have a completion method. The event dispatched to the listener will be a completion event.


local onComplete = function( event )
   print( "video session ended" )
media.playVideo( "movie.m4v", true, onComplete )