需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

本地截图上传

  • C++

更新时间不可用

enableContentInspect

启用或关闭本地截图上传功能。

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

启用该功能后，SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率，对本地用户发送的视频进行截图并上传。截图和上传完成后，声网服务器会通过 HTTPS 请求将回调通知发送到你的应用服务器，并将所有截图上传至第三方云存储服务。

注：

  • 在调用该方法前，请确保你已在声网控制台启用了本地截图上传功能。
  • 当视频审核模块设置为使用声网自研扩展（CONTENT_INSPECT_SUPERVISION）进行视频审核时，需要使用本地截图上传动态库 libagora_content_inspect_extension.dll。删除该库将禁用截图上传功能。

调用时机

该方法可以在加入频道前或加入频道后调用。

参数

参数名描述
enabled

是否启用本地截图上传功能：

  • true：启用本地截图上传功能。
  • false：关闭本地截图上传功能。
config

截图上传配置，详见 ContentInspectConfig。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

enableContentInspectEx

启用或关闭本地截图上传功能。

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

该方法可对多个视频流进行截图并上传。启用该功能后，SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率，对本地用户发送的视频进行截图并上传。截图上传完成后，声网服务器会通过 HTTPS 请求将回调通知发送至你的应用服务器，并将所有截图上传至第三方云存储服务。

注： 调用该方法前，请确保你已在声网控制台启用了本地截图上传功能。

适用场景

该方法适用于多频道场景。

调用时机

该方法可在加入频道前或加入频道后调用。

参数

参数名描述
enabled

是否启用本地截图上传功能：

  • true：启用本地截图上传功能。
  • false：关闭本地截图上传功能。
config

截图和上传的配置。详见 ContentInspectConfig。

connection

连接信息。详见 RtcConnection。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

takeSnapshot [1/2]

截取视频流快照。

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

该方法用于从指定用户的视频流中截取一帧图像，生成 JPG 图片，并保存到指定路径。

注：

  • 该方法为异步调用，调用返回时 SDK 尚未完成截图操作。
  • 用于本地视频截图时，该方法会对 ChannelMediaOptions 中指定的视频流进行截图。如果用户的视频已进行预处理，例如添加水印或美颜，截图结果中会包含这些预处理效果。

调用时机

请在加入频道后调用该方法。

相关回调

成功调用该方法后，SDK 会触发 onSnapshotTaken 回调，报告截图是否成功以及截图的详细信息。

参数

参数名描述
uid

用户 ID。若要截取本地用户的视频，请将 uid 设置为 0。

filePath

注： 请确保指定路径存在且可写。

截图的本地路径（包含文件扩展名）。例如：

  • 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
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

takeSnapshot [2/2]

截取指定观察点的视频截图。

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

注：

  • 该方法为异步方法，调用返回时 SDK 尚未完成截图操作。
  • 用于本地视频截图时，会对 ChannelMediaOptions 中指定的视频流进行截图。

调用时机

在加入频道后调用该方法。

相关回调

成功调用该方法后，SDK 会触发 onSnapshotTaken 回调，报告截图是否成功以及截图的详细信息。

参数

参数名描述
uid

用户 ID。若要截取本地用户的视频，请将 uid 设置为 0。

config

截图配置，详见 SnapshotConfig。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

takeSnapshotEx [1/2]

使用连接 ID 对指定用户的视频流进行截图。

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

该方法为异步调用，调用该方法时 SDK 尚未完成截图操作。用于本地视频截图时，会对 ChannelMediaOptions 中指定的视频流进行截图。如果用户的视频已被预处理（如添加水印或美颜），截图结果中会包含这些预处理效果。

适用场景

适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用该方法。

相关回调

成功调用该方法后，SDK 会触发 onSnapshotTaken 回调，报告截图是否成功以及截图的详细信息。

参数

参数名描述
connection

连接信息，详见 RtcConnection。

uid

用户 ID。若要对本地用户的视频进行截图，请将 uid 设置为 0。

filePath

注： 请确保指定的路径存在且可写。

截图的本地路径（包含文件扩展名）。例如：

  • 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
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

takeSnapshotEx [2/2]

通过连接 ID 获取指定用户的视频截图。

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

该方法从指定用户的视频流中截取一帧图像，生成 JPG 图片，并保存到指定路径。截图结果中会包含视频预处理效果，例如水印或美颜。

注：

  • 该方法为异步调用，调用返回时 SDK 尚未完成截图操作。
  • 用于本地视频截图时，将对 ChannelMediaOptions 中指定的视频流进行截图。

适用场景

适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用该方法。

相关回调

成功调用该方法后，SDK 会触发 onSnapshotTaken 回调，报告截图是否成功以及截图的详细信息。

参数

参数名描述
connection

连接信息。详见 RtcConnection。

uid

用户 ID。

注： 若要截取本地用户的视频，请将 uid 设置为 0。

config

截图配置。详见 SnapshotConfig。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：调用成功。
  • < 0：调用失败。

所属接口类

onSnapshotTaken

截图结果回调。

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

调用 takeSnapshot 方法成功后，SDK 会触发该回调，用于报告截图是否成功以及截图的详细信息。

触发时机

调用 takeSnapshot 方法成功后触发。

参数

参数名描述
uid

用户 ID。uid 为 0 表示本地用户。

filePath

截图的本地路径。

width

截图的宽度（像素）。

height

截图的高度（像素）。

errCode

截图结果的错误码：

  • 0：成功。

  • < 0：失败：

    • -1：SDK 写入文件或编码 JPEG 图像失败。
    • -2：调用 takeSnapshot 方法成功后 1 秒内未找到指定用户的视频流。可能原因包括：本地采集停止、远端停止发布或视频数据处理阻塞。
    • -3：调用 takeSnapshot 方法过于频繁。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利