13 min read

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

CaptureService

Inherits from: Instance → Object

CaptureService is a client-side service that allows developers to control how the screenshot and video capture feature integrates with their experiences. It can be used to include preset moments where a capture is automatically taken for a user, and that user can then save, share, or delete the capture.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Methods

Name	Type / Returns	Description
CaptureService:CaptureScreenshot	()	Takes a screenshot and provides a temporary `contentId` to identify it.
CaptureService:CheckUploadCaptureStatusAsync	Tuple	Polls the status of an in-progress capture upload started by `StartUploadCaptureAsync()`.
CaptureService:PromptCaptureGalleryPermissionAsync	boolean	Prompts the user for permission to access their local capture gallery.
CaptureService:PromptSaveCapturesToGallery	()	Prompts the user to save specified captures to their gallery.
CaptureService:PromptShareCapture	()	Prompts the user to share a specified capture.
CaptureService:ReadCapturesFromGalleryAsync	Tuple	Returns a paginated list of captures from the user's gallery.
CaptureService:StartUploadCaptureAsync	Tuple	Begins uploading a capture to the asset system and returns a token used to poll the upload's status.
CaptureService:StartVideoCaptureAsync	VideoCaptureStartedResult	Initiates a video capture recording.
CaptureService:StopVideoCapture	()	Ends a video capture initiated by `StartVideoCaptureAsync()`.
CaptureService:TakeScreenshotCaptureAsync	()	Initiates a screenshot capture.
CaptureService:UploadCaptureAsync	Tuple	Uploads a capture to the asset system and returns the result and asset ID.

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

CaptureService:CaptureScreenshot

This method captures a screenshot for the user but does not immediately save it to their Captures gallery within the experience's main menu. Instead, a temporary contentId is created to identify the new capture.

Note that any screenshots taken by this method will not be accessible via ReadCapturesFromGalleryAsync() or be uploadable via UploadCaptureAsync().

The onCaptureReady callback can be used to prompt the user to save or share the screenshot:

Parameters

Name	Type	Default	Description
onCaptureReady	Function		A callback function that is called with the `contentId` of the new capture once it is ready.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (CaptureService-CaptureScreenshot).

CaptureService:CheckUploadCaptureStatusAsync

Client-side function that checks the status of a capture upload started with StartUploadCaptureAsync(), using the returned token. Returns a tuple of the current UploadCaptureResult and, once the upload finishes successfully, the asset ID of the uploaded capture.

Poll until a terminal state. While processing, the result is UploadCaptureResult.UploadPending and the asset ID is 0. UploadCaptureResult.Success includes the final asset ID; UploadCaptureResult.CaptureModerated means moderation rejected the capture; UploadCaptureResult.UploadFailed means the upload did not complete.

Parameters

Name	Type	Default	Description
token	string		The token returned by `StartUploadCaptureAsync()` that identifies the in-progress upload.

Returns

Type	Description
Tuple	Tuple of (result: `UploadCaptureResult`, assetId: `number`)

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

CaptureService:PromptCaptureGalleryPermissionAsync

This client-side function prompts a user for permission to access their local captures. Once they have accepted or rejected the prompt, it returns a boolean representing their choice. This function is a necessary prerequisite to ReadCapturesFromGalleryAsync and UploadCaptureAsync, as both of these require gallery permissions to work.

Parameters

Name	Type	Default	Description
captureGalleryPermission	CaptureGalleryPermission		An `CaptureGalleryPermission` representing the type of access for which the user will be prompted.

Returns

Type	Description
boolean	A boolean representing whether or not the user has allowed access to their captures.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (PromptCaptureGalleryPermissionAsync-example).

CaptureService:PromptSaveCapturesToGallery

This method prompts the user to save the captures identified by the provided contentIds or Capture objects to their Captures gallery within the experience's main menu.

Parameters

Name	Type	Default	Description
captures	Array		An array of content IDs and/or `Capture` objects.
resultCallback	Function		A callback function that will be invoked with a dictionary mapping each `contentId` and/or `Capture` object to a boolean indicating if the user accepted saving that capture.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Capture"]

CaptureService:PromptShareCapture

This method prompts the user to share the capture identified by the provided contentId or Capture object using the native share sheet on their device.

The capture is shared along with an invite link to the experience when supported. Not all devices support including both a screenshot or video and an invite link.

The launchData will be available in the launchData field for users who join through the invite link.

For users or devices who are not eligible to use share sheets, this method prompts them to download the capture instead.

Parameters

Name	Type	Description
captureContent	Content	A `Content` containing a `contentId` or `Capture` object.
launchData	string	An optional string to include as launch data in the invite link.
onAcceptedCallback	Function	An optional callback function invoked if the user accepts sharing.
onDeniedCallback	Function	An optional callback function invoked if the user denies sharing.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (CaptureService-PromptShareCapture).

CaptureService:ReadCapturesFromGalleryAsync

This client-side function returns a paginated list of captures from the user's gallery as a CapturesPages object sorted reverse-chronologically, which can be used to iterate through the captures. The results can be filtered by capture type with the captureTypeFilters parameter. If this parameter isn't provided, the function returns all captures.

If readFromAllEligibleExperiences is true, captures from all eligible experiences will be read. If false, only those from the current experience will be read. Additionally, captures taken with CaptureScreenshot() and subsequently saved with PromptSaveCapturesToGallery() will not be returned by this method.

Parameters

Name	Type	Default	Description
captureTypeFilters	Array	{}	An array of `CaptureType`.
readFromAllEligibleExperiences	boolean	false	A boolean; default is `false`.

Returns

Type	Description
Tuple	Tuple of (result: `ReadCapturesFromGalleryResult`, capturesPages: `CapturesPages`)

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (ReadCapturesFromGalleryAsync-example).

CaptureService:StartUploadCaptureAsync

Client-side function that begins uploading a Capture (for example, one from ReadCapturesFromGalleryAsync()) to the asset system. Unlike UploadCaptureAsync(), which blocks until the asset is created, this returns as soon as the upload starts with a tuple of UploadCaptureResult and a token string. Use this when the user might leave before the upload finishes; a pending UploadCaptureAsync is lost if the player leaves. Pass the token to CheckUploadCaptureStatusAsync() to poll for completion and the resulting asset ID.

The user must grant gallery access through PromptCaptureGalleryPermissionAsync(); without it, the result is UploadCaptureResult.NeedPermission. The capture must be eligible and present in the gallery. Uploads are rate-limited per user and return UploadCaptureResult.UploadQuotaReached when exceeded.

Parameters

Name	Type	Default	Description
capture	Capture		The `Capture` to upload.

Returns

Type	Description
Tuple	Tuple of (result: `UploadCaptureResult`, token: `string`)

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

CaptureService:StartVideoCaptureAsync

This method initiates a video capture recording. The recording will continue until the StopVideoCapture() method is called, or when 30 seconds have passed, whichever comes first. During the video recording, all user voices are muted.

The onCaptureReady callback can be used to prompt the user to save or share the video capture.

The captureParams parameter is currently non-operational.

Parameters

Name	Type	Default	Description
onCaptureReady	Function		A callback function that is called on video capture completion with a `VideoCaptureResult` and, if successful, a `VideoCapture`.
captureParams	Dictionary	nil	A dictionary of optional parameters that modify capture behavior. Currently non-operational.

Returns

Type	Description
VideoCaptureStartedResult	A `VideoCaptureStartedResult` indicating whether the video recording started successfully.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (CaptureService-StartVideoCaptureAsync).

CaptureService:StopVideoCapture

This method ends a video capture that was started by the StartVideoCaptureAsync() method.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Capture"]

CaptureService:TakeScreenshotCaptureAsync

This method initiates a screenshot capture. The onCaptureReady callback can be used to prompt the user to save or share the screenshot capture.

Use the UICaptureMode parameter in captureParams to specify whether UI elements should be in the screenshot. By default, this is set to UICaptureMode.None.

Parameters

Name	Type	Default	Description
onCaptureReady	Function		A callback function that is called on screenshot capture completion with a `ScreenshotCaptureResult` and, if successful, a `ScreenshotCapture`.
captureParams	Dictionary	nil	A dictionary that modifies capture behavior.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (CaptureService-TakeScreenshotCaptureAsync).

CaptureService:UploadCaptureAsync

This client-side function uploads a capture, like one retrieved from ReadCapturesFromGalleryAsync, to the asset system. It returns a tuple of the result and the asset ID.

Notes:

This function will only work properly if the Maturity and Compliance questionnaire has been filled out for the experience.
For video capture types, there is an upload limit of 20 videos per day per user; when that limit is exceeded, the result is UploadCaptureResult.UploadQuotaReached, which lets you distinguish quota exhaustion from other failures.
This function can take up to several minutes to finish executing, and the user will need to remain in the experience.

Parameters

Name	Type	Default	Description
capture	Capture		The `Capture` to upload.

Returns

Type	Description
Tuple	Tuple of (result: `UploadCaptureResult`, assetId: `number`)

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Capture"]

Code samples: View on Creator Hub (UploadCaptureAsync-example).

Events

Name	Type / Returns	Description
CaptureService.CaptureBegan		Fires immediately before a capture begins.
CaptureService.CaptureEnded		Fires after a capture finishes.
CaptureService.CaptureSaved		Fires when a screenshot capture is saved to the user's gallery.
CaptureService.UserCaptureSaved		Fires when the user saves a capture.

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.

CaptureService.CaptureBegan

This event fires right before a new capture is taken. It can be used to customize the capture experience, for example by hiding certain GUI elements.

Parameters

Name	Type	Default	Description
captureType	CaptureType		An `CaptureType` indicating whether the capture is a screenshot or video.

Field	Value
security	None
capabilities	["Capture"]

CaptureService.CaptureEnded

This event fires after a new capture completes. It can be used to restore any changes made when the CaptureBegan event fired.

Parameters

Name	Type	Default	Description
captureType	CaptureType		An `CaptureType` indicating whether the capture was a screenshot or video.

Field	Value
security	None
capabilities	["Capture"]

CaptureService.CaptureSaved

Deprecated. This event has been superseded by the UserCaptureSaved event.

Fires when a screenshot capture is saved to the user's gallery. Provides a captureInfo dictionary with contentId, filePath, and type. Fires only for screenshot captures, not video captures.

Deprecated; use UserCaptureSaved instead, which fires with the saved capture's contentId directly.

Parameters

Name	Type	Default	Description
captureInfo	Dictionary		A dictionary containing `contentId`, `filePath`, and `type` fields describing the saved capture.

Field	Value
tags	["Deprecated"]
security	None
capabilities	["Capture"]

CaptureService.UserCaptureSaved

This event fires when the user saves a screenshot using the Roblox screenshot capture UI. It can be used for analytics or to prompt the user to share their capture.

Parameters

Name	Type	Default	Description
captureContentId	ContentId		The `contentId` identifying the screenshot that the user saved.

Field	Value
security	None
capabilities	["Capture"]

Properties

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