17 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

VideoFrame

Inherits from: GuiObject → GuiBase2d → GuiBase → Instance → Object

A VideoFrame renders a rectangle, like a Frame does, with a moving video image. The video must be from a file uploaded to the Roblox website.

The video is scaled to fit the entirety of the rectangle, but looks best when displayed at its native resolution.

2D and 3D Sound

A VideoFrame placed underneath SurfaceGui on a BasePart will emit its sound from that part's BasePart.Position.

A VideoFrame exhibits the Doppler effect, meaning its frequency and pitch varies with the relative motion of whatever part it is attached to.

The volume of the VideoFrame will be determined by the distance between the client's sound listener (by default the Camera position) and the position of the VideoFrame's part.

A VideoFrame is considered "global" if it is not placed underneath SurfaceGui on a BasePart. In this case, the sound will play at the same volume throughout the entire place.

Inherits from: GuiObject

Memory category: Gui

Code samples: View on Creator Hub (creating-and-playing-a-video).

Properties

Name	Type / Returns	Description
VideoFrame.IsLoaded	boolean	Indicates when the `VideoFrame.Video` has loaded from Roblox servers and is ready to play.
VideoFrame.Looped	boolean	Sets whether or not the `VideoFrame.Video` repeats once it has finished when it is playing.
VideoFrame.MaximumResolution	VideoSampleSize	Internal-only. Caps the resolution the video is allowed to stream at, expressed as an `VideoSampleSize`.
VideoFrame.Playing	boolean	Indicates whether the `VideoFrame.Video` is currently playing. It can be set to start or pause playback.
VideoFrame.Resolution	Vector2	Gets the original source resolution of the `VideoFrame.Video` file.
VideoFrame.RollOffMaxDistance	float	The maximum distance, in studs, a listener can be from the video's part and still hear its audio.
VideoFrame.RollOffMinDistance	float	The minimum distance, in studs, at which the video's audio starts to attenuate.
VideoFrame.RollOffMode	RollOffMode	Controls how the video's audio volume attenuates with distance.
VideoFrame.TimeLength	double	Indicates the length of the `VideoFrame.Video` in seconds.
VideoFrame.TimePosition	double	Indicates the progress in seconds of the `VideoFrame.Video`.
VideoFrame.Video	ContentId	The content ID of the video file a `VideoFrame` object is associated with.
VideoFrame.VideoContent	Content	The video content a `VideoFrame` is associated with, as either an asset content ID (same value as `Video`) or a direct reference to a `VideoCapture` object for local screen recordings.
VideoFrame.Volume	float	Indicates how loud the `VideoFrame.Video` is currently playing back.

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject.Active	boolean	Determines whether this UI element sinks input.
GuiObject.AnchorPoint	Vector2	Determines the origin point of a `GuiObject`, relative to its absolute size.
GuiObject.AutomaticSize	AutomaticSize	Determines whether resizing occurs based on child content.
GuiObject.BackgroundColor	BrickColor	Determines the color of the `GuiObject` background.
GuiObject.BackgroundColor3	Color3	Determines the `GuiObject` background color.
GuiObject.BackgroundTransparency	float	Determines the transparency of the `GuiObject` background and border.
GuiObject.BorderColor	BrickColor	Determines the color of the `GuiObject` border.
GuiObject.BorderColor3	Color3	Determines the color of the `GuiObject` border.
GuiObject.BorderMode	BorderMode	Determines in what manner the `GuiObject` border is laid out relative to its dimensions.
GuiObject.BorderSizePixel	int	Determines the pixel width of the `GuiObject` border.
GuiObject.ClipsDescendants	boolean	Determines if descendant `GuiObjects` outside of the bounds of a parent GUI element should render.
GuiObject.Draggable	boolean	Determines whether a `GuiObject` (and its descendants) can be dragged around the screen.
GuiObject.GuiState	GuiState	Determines whether the player's mouse is being actively pressed on the `GuiObject` or not.
GuiObject.InputSink	InputSink	Controls whether, and how, the `GuiObject` sinks input that occurs over it.
GuiObject.Interactable	boolean	Determines whether the `GuiButton` can be interacted with or not, or if the `GuiState` of the `GuiObject` is changing or not.
GuiObject.LayoutOrder	int	Controls the sort order of the `GuiObject` when used with a `UIGridStyleLayout`.
GuiObject.NextSelectionDown	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved downward.
GuiObject.NextSelectionLeft	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved to the left.
GuiObject.NextSelectionRight	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved to the right.
GuiObject.NextSelectionUp	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved upward.
GuiObject.Position	UDim2	Determines the pixel and scalar position of the `GuiObject`.
GuiObject.Rotation	float	Determines the number of degrees by which the `GuiObject` is rotated.
GuiObject.Selectable	boolean	Determine whether the `GuiObject` can be selected by a gamepad.
GuiObject.SelectionImageObject	GuiObject	Overrides the default selection adornment used for gamepads.
GuiObject.SelectionOrder	int	The order of `GuiObjects` selected by the gamepad UI selection.
GuiObject.Size	UDim2	Determines the pixel and scalar size of the `GuiObject`.
GuiObject.SizeConstraint	SizeConstraint	Sets the `Size` axes that the `GuiObject` will be based on, relative to the size of its parent.
GuiObject.Transparency	float	A mixed property of `BackgroundTransparency` and `TextTransparency`.
GuiObject.Visible	boolean	Determines whether the `GuiObject` and its descendants will be rendered.
GuiObject.ZIndex	int	Determines the order in which a `GuiObject` renders relative to others.

Inherited from GuiBase2d

Name	Type / Returns	Description
GuiBase2d.AbsolutePosition	Vector2	Describes the actual screen position of a `GuiBase2d` element, in pixels.
GuiBase2d.AbsoluteRotation	float	Describes the actual screen rotation of a `GuiBase2d` element, in degrees.
GuiBase2d.AbsoluteSize	Vector2	Describes the actual screen size of a `GuiBase2d` element, in pixels.
GuiBase2d.AutoLocalize	boolean	When set to `true`, localization will be applied to this `GuiBase2d` and its descendants.
GuiBase2d.Localize	boolean	Automatically set to true when a localization table's `LocalizationTable.Root` targets this object, or an ancestor of this object.
GuiBase2d.RootLocalizationTable	LocalizationTable	A reference to a `LocalizationTable` to be used to apply automated localization to this `GuiBase2d` and its descendants.
GuiBase2d.SelectionBehaviorDown	SelectionBehavior	Customizes gamepad selection behavior in the down direction.
GuiBase2d.SelectionBehaviorLeft	SelectionBehavior	Customizes gamepad selection behavior in the left direction.
GuiBase2d.SelectionBehaviorRight	SelectionBehavior	Customizes gamepad selection behavior in the right direction.
GuiBase2d.SelectionBehaviorUp	SelectionBehavior	Customizes gamepad selection behavior in the up direction.
GuiBase2d.SelectionGroup	boolean	Allows customization of gamepad selection movement.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

VideoFrame.IsLoaded

This property will be true when the VideoFrame.Video has loaded from Roblox servers and is ready to play.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":false,"can_save":false}
capabilities	["Audio","UI"]

VideoFrame.Looped

This property sets whether or not the VideoFrame.Video repeats once it has finished when it is playing.

Field	Value
type	boolean
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.MaximumResolution

Internal-only. Caps the resolution the video is allowed to stream at, as an VideoSampleSize rather than exact pixel dimensions.

The video may still stream below the cap on a slow connection. Defaults to VideoSampleSize.Full.

Field	Value
type	VideoSampleSize
tags	["Hidden"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI","InternalTest"]

VideoFrame.Playing

This property indicates whether the VideoFrame.Video is currently playing. It can be set to start or pause playback as an alternative to the VideoFrame:Play() and VideoFrame:Pause() functions.

Field	Value
type	boolean
tags	["NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.Resolution

This property gets the original source resolution of the VideoFrame.Video file.

Field	Value
type	Vector2
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":false,"can_save":false}
capabilities	["Audio","UI"]

VideoFrame.RollOffMaxDistance

The maximum distance, in studs, a client's listener can be from the VideoFrame's part and still hear its audio. Defaults to 10000.

This property only affects playback when the VideoFrame is 3D, as described in the class's "2D and 3D Sound" section; it has no effect on a global VideoFrame. How RollOffMaxDistance affects the attenuation of the sound depends on the RollOffMode property.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.RollOffMinDistance

The minimum distance, in studs, at which the VideoFrame's audio begins to attenuate (decrease in volume). Defaults to 1.

This property only affects playback when the VideoFrame is 3D, as described in the class's "2D and 3D Sound" section; it has no effect on a global VideoFrame. How RollOffMinDistance affects the attenuation of the sound depends on the RollOffMode property.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.RollOffMode

Controls how the volume of the VideoFrame's audio attenuates (fades out) as the distance between the listener and the video's part changes. Defaults to RollOffMode.Inverse.

This property only affects playback when the VideoFrame is 3D, as described in the class's "2D and 3D Sound" section; it has no effect on a global VideoFrame. For details on the different modes, see RollOffMode.

Field	Value
type	RollOffMode
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.TimeLength

This property indicates the length of the VideoFrame.Video in seconds. If the video is not loaded, this value will be 0.

Field	Value
type	double
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":false,"can_save":false}
capabilities	["Audio","UI"]

VideoFrame.TimePosition

This property indicates the progress in seconds of the VideoFrame.Video. It can be changed to move the playback position of the video both before and during playback.

Field	Value
type	double
tags	["NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.Video

The content ID of the video file a VideoFrame object is associated with. To save resources and improve performance, set this property to "" when the VideoFrame is not visible or in use.

Field	Value
type	ContentId
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

Code samples: View on Creator Hub (creating-and-playing-a-video).

VideoFrame.VideoContent

The video content a VideoFrame object is associated with. Setting this property is equivalent to setting Video, and reading it returns a content ID equal to Video.

When referencing a video by content ID, build the value with the corresponding Content constructor: Content.fromAssetId() for a numeric asset ID, or Content.fromUri() for an rbxassetid:// URI.

Unlike Video, which only accepts a content ID string, VideoContent can also hold a direct reference to a VideoCapture object, such as one retrieved through CaptureService:ReadCapturesFromGalleryAsync(). This lets a local screen recording play back on the VideoFrame without first uploading it to Roblox. Build the value with Content.fromObject(), for example videoFrame.VideoContent = Content.fromObject(capture).

Field	Value
type	Content
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

VideoFrame.Volume

This property determines how loud the VideoFrame.Video plays back. It can be set to a number between 0 and 100.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Video
serialization	{"can_load":true,"can_save":true}
capabilities	["Audio","UI"]

Methods

Name	Type / Returns	Description
VideoFrame:Pause	()	Sets `VideoFrame.Playing` to `false`, pausing playback if the `VideoFrame.Video` is playing.
VideoFrame:Play	()	Sets `VideoFrame.Playing` to `true`, playing the `VideoFrame.Video` from the current `VideoFrame.TimePosition`.

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject:TweenPosition	boolean	Smoothly moves a GUI to a new `UDim2`.
GuiObject:TweenSize	boolean	Smoothly resizes a `GuiObject` to a new `UDim2`.
GuiObject:TweenSizeAndPosition	boolean	Smoothly moves a GUI to a new size and position.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

VideoFrame:Pause

Sets VideoFrame.Playing to false, pausing playback if the VideoFrame.Video is playing.

As VideoFrame.TimePosition is not reset, when the video is resumed it will continue from its previous position.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Audio","UI"]

VideoFrame:Play

Sets VideoFrame.Playing to true, playing the VideoFrame.Video from the current VideoFrame.TimePosition. To save resources and improve performance, set the VideoFrame.Video property to "" when the VideoFrame is not visible or in use.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Audio","UI"]

Code samples: View on Creator Hub (creating-and-playing-a-video).

Events

Name	Type / Returns	Description
VideoFrame.DidLoop		Fires whenever the `VideoFrame.Video` loops.
VideoFrame.Ended		Fires when the `VideoFrame.Video` has completed playback and stopped.
VideoFrame.Loaded		Fires when the `VideoFrame.Video` is loaded.
VideoFrame.Paused		This event fires whenever the `VideoFrame.Video` is paused using `VideoFrame:Pause()` or by setting `VideoFrame.Playing` to false.
VideoFrame.Played		Fires whenever the `VideoFrame.Video` is played using the `VideoFrame:Play()` function or by setting `VideoFrame.Playing` to true.

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject.DragBegin		Fired when a player begins dragging the object.
GuiObject.DragStopped		Fired when a player stops dragging the object.
GuiObject.InputBegan		Fired when a user begins interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.InputChanged		Fired when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.InputEnded		Fired when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.MouseEnter		Fires when a user moves their mouse into a GUI element.
GuiObject.MouseLeave		Fires when a user moves their mouse out of a GUI element.
GuiObject.MouseMoved		Fires whenever a user moves their mouse while it is inside a GUI element.
GuiObject.MouseWheelBackward		Fires when a user scrolls their mouse wheel back when the mouse is over a GUI element.
GuiObject.MouseWheelForward		Fires when a user scrolls their mouse wheel forward when the mouse is over a GUI element.
GuiObject.SelectionGained		Fired when the GuiObject is being focused on with the Gamepad selector.
GuiObject.SelectionLost		Fired when the Gamepad selector stops focusing on the GuiObject.
GuiObject.TouchLongPress		Fires when the player starts, continues and stops long-pressing the UI element.
GuiObject.TouchPan		Fires when the player moves their finger on the UI element.
GuiObject.TouchPinch		Fires when the player performs a pinch or pull gesture using two fingers on the UI element.
GuiObject.TouchRotate		Fires when the player performs a rotation gesture using two fingers on the UI element.
GuiObject.TouchSwipe		Fires when the player performs a swipe gesture on the UI element.
GuiObject.TouchTap		Fires when the player performs a tap gesture on the UI element.

Inherited from GuiBase2d

Name	Type / Returns	Description
GuiBase2d.SelectionChanged		Fires when the gamepad selection moves to, leaves, or changes within the connected `GuiBase2d` or any descendant `GuiObjects`.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.

VideoFrame.DidLoop

An event that fires whenever the VideoFrame.Video loops. Returns the content ID of the video.

Parameters

Name	Type	Default	Description
video	string		The content ID of the video that looped.

Field	Value
security	None
capabilities	["Audio","UI"]

VideoFrame.Ended

This event fires when the VideoFrame.Video has completed playback and stopped.

Parameters

Name	Type	Default	Description
video	string		The content ID of the paused that ended.

Field	Value
security	None
capabilities	["Audio","UI"]

VideoFrame.Loaded

This event fires when the VideoFrame.Video is loaded.

Parameters

Name	Type	Default	Description
video	string		The content ID of the loaded video.

Field	Value
security	None
capabilities	["Audio","UI"]

VideoFrame.Paused

This event fires whenever the VideoFrame.Video is paused using VideoFrame:Pause() or by setting VideoFrame.Playing to false.

Parameters

Name	Type	Default	Description
video	string		The content ID of the paused video.

Field	Value
security	None
capabilities	["Audio","UI"]

VideoFrame.Played

This event fires whenever the VideoFrame.Video is played using the VideoFrame:Play() function or by setting VideoFrame.Playing to true.

Parameters

Name	Type	Default	Description
video	string		The content ID of the played video.

Field	Value
security	None
capabilities	["Audio","UI"]