Snapshot

enableContentInspect

Enables or disables the local snapshot upload feature.

virtual int enableContentInspect(bool enabled, const media::ContentInspectConfig &config) = 0;

After enabling this feature, the SDK captures and uploads snapshots of the local user's video based on the module type and frequency you set in ContentInspectConfig. Once the snapshot and upload are complete, the Agora server sends a callback notification to your app server via HTTPS and uploads all snapshots to a third-party cloud storage service.

Note:

Before calling this method, ensure that you have enabled the local snapshot upload feature in the Agora Console.
If the video moderation module is set to use Agora's proprietary extension (CONTENT_INSPECT_SUPERVISION), you must use the local snapshot upload dynamic library libagora_content_inspect_extension.dll. Deleting this library disables the snapshot upload feature.

Timing

You can call this method before or after joining a channel.

Parameters

enabled

Whether to enable the local snapshot upload feature:

true: Enable.
false: Disable.

config

Snapshot upload configuration. See ContentInspectConfig.

Return Values

0: Success.
< 0: Failure.

enableContentInspectEx

Enables or disables the local snapshot upload feature.

virtual int enableContentInspectEx(bool enabled, const media::ContentInspectConfig &config, const RtcConnection& connection) = 0;

This method allows you to capture and upload snapshots from multiple video streams. Once enabled, the SDK captures and uploads snapshots of the local user's video based on the module type and frequency you set in ContentInspectConfig. After the upload is complete, the Agora server sends a callback notification to your application server via HTTPS and uploads all snapshots to a third-party cloud storage service.

Note: Before calling this method, ensure that the local snapshot upload feature is enabled in the Agora Console.

Scenario

This method is applicable in multi-channel scenarios.

Timing

You can call this method before or after joining a channel.

Parameters

enabled

Whether to enable the local snapshot upload feature:

true: Enable.
false: Disable.

config

Configuration for snapshot and upload. See ContentInspectConfig.

connection

Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

takeSnapshot [1/2]

Takes a snapshot of the video stream.

virtual int takeSnapshot(uid_t uid, const char* filePath) = 0;

This method captures a frame from the specified user's video stream, generates a JPG image, and saves it to the specified path.

Note:

This is an asynchronous call. When the method returns, the SDK has not yet completed the snapshot operation.
When used for local video snapshot, this method captures the video stream specified in ChannelMediaOptions. If the video has been pre-processed, such as with watermarking or beautification, the snapshot result includes these effects.

Timing

Call this method after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot was successful and provide detailed information.

Parameters

uid

User ID. To capture a snapshot of the local user's video, set uid to 0.

filePath

Note: Ensure the specified path exists and is writable.

The local path to save the snapshot (including file extension). For example:

Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
iOS: /App Sandbox/Library/Caches/example.jpg
macOS: ～/Library/Logs/example.jpg
Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

Return Values

0: Success.
< 0: Failure.

takeSnapshot [2/2]

Takes a snapshot of the specified view.

virtual int takeSnapshot(uid_t uid, const media::SnapshotConfig& config) = 0;

Note:

This is an asynchronous method. When the method returns, the SDK has not yet completed the snapshot operation.
When used for local video snapshot, it captures the video stream specified in ChannelMediaOptions.

Timing

Call this method after joining a channel.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot was successful and provide detailed information.

Parameters

uid: User ID. To capture a snapshot of the local user's video, set uid to 0.
config: Snapshot configuration. See SnapshotConfig.

Return Values

0: Success.
< 0: Failure.

takeSnapshotEx [1/2]

Takes a snapshot of the specified user's video stream using the connection ID.

virtual int takeSnapshotEx(const RtcConnection& connection, uid_t uid, const char* filePath) = 0;

This method is asynchronous. When you call it, the SDK has not completed the snapshot operation. When used for local video snapshots, it captures the video stream specified in ChannelMediaOptions. If the user's video has been pre-processed (e.g., watermarks or beautification), the snapshot result includes these effects.

Scenario

Applicable in multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successful and provide detailed information.

Parameters

connection

Connection information. See RtcConnection.

uid

User ID. To capture the local user's video, set uid to 0.

filePath

Note: Make sure the specified path exists and is writable.

Local path of the snapshot (including file extension). For example:

Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
iOS: /App Sandbox/Library/Caches/example.jpg
macOS: ～/Library/Logs/example.jpg
Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

Return Values

0: Success.
< 0: Failure.

takeSnapshotEx [2/2]

Captures a snapshot of the specified user's video using the connection ID.

virtual int takeSnapshotEx(const RtcConnection& connection, uid_t uid, const media::SnapshotConfig& config) = 0;

This method captures a frame from the specified user's video stream, generates a JPG image, and saves it to the specified path. The snapshot result includes video preprocessing effects such as watermarks or beautification.

Note:

This method is asynchronous. When you call it, the SDK has not completed the snapshot operation.
When used for local video snapshots, it captures the video stream specified in ChannelMediaOptions.

Scenario

Applicable in multi-channel scenarios.

Timing

Call this method after calling joinChannelEx.

Related Callbacks

After this method is successfully called, the SDK triggers the onSnapshotTaken callback to report whether the snapshot is successful and provide detailed information.

Parameters

connection: Connection information. See RtcConnection.
uid: User ID.
Note: To capture the local user's video, set uid to 0.
config: Snapshot configuration. See SnapshotConfig.

Return Values

0: Success.
< 0: Failure.

onSnapshotTaken

Snapshot result callback.

virtual void onSnapshotTaken(uid_t uid, const char* filePath, int width, int height, int errCode)

After successfully calling the takeSnapshot method, the SDK triggers this callback to report whether the snapshot was successful and provide detailed information.

Trigger Timing

Triggered after successfully calling the takeSnapshot method.

Parameters

uid

User ID. A uid of 0 indicates the local user.

filePath

Local path of the snapshot.

width

Width of the snapshot (pixels).

height

Height of the snapshot (pixels).

errCode

Error code of the snapshot result:

0: Success.
< 0: Failure:
- -1: SDK failed to write file or encode JPEG image.
- -2: No video stream found for the specified user within 1 second after calling takeSnapshot. Possible reasons include: local capture stopped, remote stopped publishing, or video data processing was blocked.
- -3: takeSnapshot method was called too frequently.