The Video object can play a video inside a project. The video renders inside the game canvas itself, allowing other objects to appear on top of it and shader effects to be applied, unlike with form controls.
Browser makers have not been able to agree on one video format that can play everywhere. As a result to guarantee that video playback will work on all browsers and on all platforms, it is necessary to encode your videos in at least two formats.
The Video plugin allows you to set three sources for a video in the following formats:
- WebM with VP8 or VP9 codec (.webm)
- Ogg Theora (.ogv)
- MPEG-4 with h.264 codec (.mp4)
Browsers which support WebM usually also support Ogg Theora, so it is not necessary to specify both a WebM and Ogg Theora source. It should only be necessary to specify a h.264 source and either a WebM source or an Ogg Theora source. Since WebM is a newer and more advanced format than Ogg Theora, it is recommended to specify a WebM and h.264 source.
The Video plugin will prefer to play WebM first if supported and a source provided, Ogg Theora second, and h.264 last.
Be sure to import video files to the Videos project folder. If video files are added in any other project folder, e.g. Files, they may be exported to a different folder and fail to load.
Due to the complexities of video compression and the patent-encumbrance of h.264, Construct does not provide a video importer like it does with audio. You must encode your video files yourself, and then import them as project files. WebM and Ogg Theora are free formats and you should be able to find free encoders, whereas h.264 encoders may involve a fee.
When publishing a project using video playback to the web, be sure that your server has the correct MIME types set up otherwise video playback may fail after export.
On some browsers, particularly mobile browsers, video playback cannot begin unless triggered by a user input event. The Play action will work in a user input trigger like On touch start, but if done outside of that it cannot play right away. To work around this the video plugin will wait until the next touch event to start playing the video. This also applies to autoplaying videos: it will not start until the first touch.
This restriction generally only applies to web browsers. Usually if you publish an app, the restriction is able to be removed because the app can adjust the permissions.
- WebM source
- Ogg Theora source
- H.264 source
- Names of the project files for the video in different formats. For more information, see Video formats above.
- The autoplay or preload mode. This can be:
- No: nothing is done until the video is requested to be played.
- Preload: on startup the video will start downloading the video data, but will not start playing it yet. This can allow video playback to start more quickly when requested. Some platforms (e.g. mobile devices on cellular data connections) may ignore this.
- Yes: on startup the video will start downloading the video data, and also start playing it as soon as it determines the progress and transfer rate are sufficient to play through to the end without stalling for buffering. Some mobile platforms will not start playing until the first touch event - see Compatibility for more information.
- Play in background
- If disabled, then switching browser tab, minimising the browser window, switching to a different mobile app, or otherwise hiding the window will pause the video and resume it when switching back. This is intended to avoid annoying the user with continued audio playback when deciding to do something else, and it also helps save battery on mobile devices. However for some types of app it may be desirable to keep playing in the background, in which case enabling this allows continued playback even when in the background.
- Initially visibile
- Whether the video is initially visible or invisible. Note that if it is invisible, audio playback may still be heard when playing, so it may be desirable to also mute the video.
- Has ended
- True if the video playback has reached the end of the video and stopped.
- Is muted
- True if the audio playback from the video has been muted.
- Is paused
- True if the video playback has been paused.
- Is playing
- True if the video playback is actively playing.
- On playback event
- Triggers when a playback event occurs. This can be one of:
- Can play: triggered when enough data is available to play at least a couple of frames, but there may not be enough data to play through to the end.
- Can play through: triggered when the browser determines that the load progress and transfer rate are sufficient for playback through to the end without stalling for buffering. However this is not a guarantee, since the transfer rate could drop or be cut off completely.
- Ended: triggered when playback reaches the end of the video.
- Error: triggered if an error occurs during video loading, decoding or playback.
- Started loading: triggered when the browser begins loading video data.
- Played: triggered when playback begins.
- Paused: triggered upon pausing the video playback.
- Stalled: triggered if the video download rate is too slow to keep up the current playback rate. This will cause the video to pause while it finishes loading the rest of the video, also known as buffering.
- Pause the video playback if it is currently playing.
- Start playing the video. On some platforms this can only happen in a user input event. For more information, see the section on Compatibility.
- Set looping
- Set whether the video is looping, so that it restarts from the beginning when it reaches the end.
- Set muted
- Set whether the audio playback from the video is muted (inaudible) or unmuted.
- Set playback time
- Set the video playback time to a specific time in seconds (i.e. seek to the given time). Due to the way video encoding technologies work, the video may only be able to seek close to but not exactly on the specified time.
- Set source
- Set a different video file to play. As with the object properties, three formats can be specified. Setting the source does not automatically start playing the video; use the Play action to start it after changing the source.
- Set volume
- Set the volume of the audio playback from the video, in decibels attenuation. 0 is full volume, -10 dB is approximately half as loud, etc. The audio cannot be amplified: positive volume values will be treated as 0.
- The video duration in seconds, if the video has loaded enough for this to be determined.
- The current playback time in seconds.
- The dimensions of the source video, in pixels.
- The current audio playback volume in dB attenuation.