视频标注

简介

Pano SDK 支持视频标注，即在视频窗口上使用常用工具进行标注，以丰富沟通和交互场景。

各端 SDK 相关接口，请查看下列介绍：

Windows (C++)

获取视频标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kChannelServiceWhiteboard。

通过 RtcEngine 实例的 getAnnotationManager 方法获取标注管理器 (AnnotationManager)。
再通过 AnnotationManager 的 getVideoAnnotation(uint64_t userId, int streamId) 方法获取视频标注对象 (PanoAnnotation)。

userId 参数指定需要被标注的用户ID，可以是自己，也可以是其他用户。

  • 通常情况下只有一路视频流，streamId 请传 0。使用 多路视频 的开发者，请按实际场景传参。

视频标注事件通知

通过 AnnotationManager 的 setCallback 方法设置标注管理器回调函数。
和视频标注相关的事件通知有：

  • onVideoAnnotationStart(uint64_t userId, int streamId): 视频标注开始
  • onVideoAnnotationStop(uint64_t userId, int streamId): 视频标注结束

通过 PanoAnnotation 的 setCallback 方法设置标注回调函数。
相应的事件通知例如：

  • onAnnoRoleChanged: 标注角色类型变化通知
  • onSnapshotComplete: 标注截图完成通知

设置标注工具和格式

通过 PanoAnnotation 的相关方法设置标注工具和格式，例如：

  • setToolType: 设置工具类型 (注意：标注图形不支持填充)
  • setLineWidth: 设置线宽
  • setColor: 设置颜色
  • setFontStyle: 设置字体样式
  • setFontSize: 设置字体大小

开始标注

通过 PanoAnnotation 的 startAnnotation(void *window) 方法开启标注并设置显示窗口。

  • 如果有使用视频标注的场景，建议设置视频渲染窗口，而不是视频数据接收槽：
    • 开启视频时建议使用 RtcEngine 的 startVideo(void *window, const VideoConfig &config) 方法；
    • 订阅其他用户的视频时，建议使用 RtcEngine 的 subscribeVideo(uint64_t userId, void *window, const VideoConfig &config) 方法；
  • 如果对自己的视频进行标注，window 参数应与上述 startVideo 方法传入的 window 一致。
  • 如果对其他用户的视频进行标注，window 参数应与上述 subscribeVideo 方法传入的 window 一致。
  • 收到 "视频标注开始" (onVideoAnnotationStart) 通知时，可以获取被标注的 userId。
    • 如果 userId 是自己，说明自己被其他用户标注，window 参数应与上述 startVideo 方法传入的 window 一致。
    • 如果 userId 是其他用户，说明其他用户被标注，window 参数应与上述 subscribeVideo 方法传入的 window 一致。

结束标注

通过 PanoAnnotation 的 stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoAnnotation 的 setRoleType 方法设置权限角色，支持以下角色：

  • ADMIN: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
  • ATTENDEE: 普通参与者
  • VIEWER: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoAnnotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 PanoAnnotation 的 clearContents 方法清除所有标注内容 (需要 ADMIN 权限)，clearUserContents(uint64_t userId) 方法清除指定用户标注的内容 (清除其他用户的标注需要 ADMIN 权限)。

设置标注是否可见

通过 PanoAnnotation 的 setVisible(bool visible) 方法设置标注是否可见。

截图

通过 PanoAnnotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 PanoAnnotation 的 setOption 方法：

  • option 参数设置为 ENABLE_CURSORPOS_SYNC，param 参数设置为布尔值来设置是否同步光标位置给其他用户。
  • option 参数设置为 ENABLE_SHOW_REMOTE_CURSOR，param 参数设置为布尔值来设置是否显示其他用户的光标位置。
  • 这两个参数默认都是关闭的。
bool param1 = true;
panoAnnotation->setOption(AnnoOption::ENABLE_CURSORPOS_SYNC, &param1, sizeof(param1));
bool param2 = true;
panoAnnotation->setOption(AnnoOption::ENABLE_SHOW_REMOTE_CURSOR, &param2, sizeof(param2));

macOS/iOS (Objective-C)

获取视频标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kPanoChannelServiceWhiteboard。

通过 PanoRtcEngineKit 实例的 annotationManager 属性获取标注管理器 (PanoRtcAnnotationManager)。
再通过 PanoRtcAnnotationManager 的 - videoAnnotation:stream: 方法获取视频标注对象 (PanoRtcAnnotation)。

userId 参数指定需要被标注的用户ID，可以是自己，也可以是其他用户。

  • 通常情况下只有一路视频流，streamId 请传 0。使用 多路视频 的开发者，请按实际场景传参。

视频标注事件通知

通过 PanoRtcAnnotationManager 的 - setDelegate: 方法设置标注管理器回调对象。
和视频标注相关的事件通知有：

  • - onVideoAnnotationStart:stream: 视频标注开始
  • - onVideoAnnotationStop:stream: 视频标注结束

通过 PanoRtcAnnotation 的 - setDelegate: 方法设置标注回调对象。
相应的事件通知例如：

  • - onAnnoRoleChanged: 标注角色类型变化通知
  • - onSnapshotComplete:name: 标注截图完成通知

设置标注工具和格式

通过 PanoRtcAnnotation 的相关方法设置标注工具和格式，例如：

  • - setToolType: 设置工具类型 (注意：标注图形不支持填充)
  • - setLineWidth: 设置线宽
  • - setColor: 设置颜色
  • - setFontStyle: 设置字体样式
  • - setFontSize: 设置字体大小

开始标注

通过 PanoRtcAnnotation 的 - startAnnotation: 方法开启标注并设置显示窗口。

  • 如果有使用视频标注的场景，建议设置视频渲染视图，而不是外置渲染器：
    • 开启视频时建议使用 PanoRtcEngineKit 的 - startVideoWithView:config: 方法；
    • 订阅其他用户的视频时，建议使用 PanoRtcEngineKit 的 - subscribeVideo:withView:config: 方法；
  • 如果对自己的视频进行标注，view 参数应与上述 - startVideoWithView:config: 方法传入的 view 一致。
  • 如果对其他用户的视频进行标注，view 参数应与上述 - subscribeVideo:withView:config: 方法传入的 view 一致。
  • 收到 "视频标注开始" (- onVideoAnnotationStart:stream:) 通知时，可以获取被标注的 userId。
    • 如果 userId 是自己，说明自己被其他用户标注，view 参数应与上述 - startVideoWithView:config: 方法传入的 view 一致。
    • 如果 userId 是其他用户，说明其他用户被标注，view 参数应与上述 - subscribeVideo:withView:config: 方法传入的 view 一致。

结束标注

通过 PanoRtcAnnotation 的 - stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoRtcAnnotation 的 - setRoleType: 方法设置权限角色，支持以下角色：

  • kPanoWBRoleAdmin: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
  • kPanoWBRoleAttendee: 普通参与者
  • kPanoWBRoleViewer: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoRtcAnnotation 的 - undo 方法撤销上一次操作，- redo 方法重做上一次操作。

清除标注内容

通过 PanoRtcAnnotation 的 - clearContents 方法清除所有标注内容 (需要 kPanoWBRoleAdmin 权限)，- clearUserContents: 方法清除指定用户标注的内容 (清除其他用户的标注需要 kPanoWBRoleAdmin 权限)。

设置标注是否可见

通过 PanoRtcAnnotation 的 - setVisible: 方法设置标注是否可见。

截图

通过 PanoRtcAnnotation 的 - snapshot: 方法将标注内容截图。

同步光标位置

通过 PanoRtcAnnotation 的 - setOption:forType: 方法：

  • type 参数设置为 kPanoAnnoOptionCursorPosSync，option 参数设置为带 BOOL 值的 NSNumber 来设置是否同步光标位置给其他用户。
  • type 参数设置为 kPanoAnnoOptionShowRemoteCursor，option 参数设置为带 BOOL 值的 NSNumber 来设置是否显示其他用户的光标位置。
  • 这两个参数默认都是关闭的。
[self.panoAnnotation setOption:@YES forType:kPanoAnnoOptionCursorPosSync]; // 同步光标位置给其他用户
[self.panoAnnotation setOption:@YES forType:kPanoAnnoOptionShowRemoteCursor]; // 显示其他用户的光标位置

Android (Java)

获取视频标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kChannelServiceWhiteboard。

通过 RtcEngine 实例的 getAnnotationMgr 方法获取标注管理器 (PanoAnnotationManager)。
再通过 PanoAnnotationManager 的 getVideoAnnotation(long userId, int streamId) 方法获取视频标注对象 (PanoAnnotation)。

userId 参数指定需要被标注的用户ID，可以是自己，也可以是其他用户。

  • 通常情况下只有一路视频流，streamId 请传 0。使用 多路视频 的开发者，请按实际场景传参。

视频标注事件通知

通过 PanoAnnotationManager 的 setCallback 方法设置标注管理器回调函数。
和视频标注相关的事件通知有：

  • onVideoAnnotationStart(long userId, int streamId): 视频标注开始
  • onVideoAnnotationStop(long userId, int streamId): 视频标注结束

通过 PanoAnnotation 的 setCallback 方法设置标注回调函数。
相应的事件通知例如：

  • onAnnoRoleChanged: 标注角色类型变化通知
  • onSnapshotComplete: 标注截图完成通知

设置标注工具和格式

通过 PanoAnnotation 的相关方法设置标注工具和格式，例如：

  • setToolType: 设置工具类型 (注意：标注图形不支持填充)
  • setLineWidth: 设置线宽
  • setColor: 设置颜色
  • setFontStyle: 设置字体样式
  • setFontSize: 设置字体大小

开始标注

通过 PanoAnnotation 的 startAnnotation(RtcWbView view) 方法开启标注并设置显示窗口。

  • 如果对自己的视频进行标注，view 参数应与调用 RtcEngine 的 setLocalVideoRender 方法传入的 render 一致。
  • 如果对其他用户的视频进行标注，view 参数应与调用 RtcEngine 的 setRemoteVideoRender 方法传入的 render 一致。
  • 收到 "视频标注开始" (onVideoAnnotationStart) 通知时，可以获取被标注的 userId。
    • 如果 userId 是自己，说明自己被其他用户标注，view 参数应与上述 setLocalVideoRender 方法传入的 render 一致。
    • 如果 userId 是其他用户，说明其他用户被标注，view 参数应与上述 setRemoteVideoRender 方法传入的 render 一致。

结束标注

通过 PanoAnnotation 的 stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoAnnotation 的 setRoleType 方法设置权限角色，支持以下角色：

  • Admin: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
  • Attendee: 普通参与者
  • Viewer: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoAnnotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 PanoAnnotation 的 clearContents 方法清除所有标注内容 (需要 Admin 权限)，clearUserContents (long userId) 方法清除指定用户标注的内容 (清除其他用户的标注需要 Admin 权限)。

设置标注是否可见

通过 PanoAnnotation 的 setVisible(boolean visible) 方法设置标注是否可见。

截图

通过 PanoAnnotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 PanoAnnotation 的：

  • enableCursorPosSync 方法设置是否同步光标位置给其他用户
  • enableShowRemoteCursor 方法设置是否显示其他用户的光标位置，当启用时，需要传入一个 PanoLabelView 用于显示远端光标位置

Electron/Web (Javascript)

如需在 Electron 中使用标注功能，请集成 Web SDK。

获取视频标注对象

通过 RtsService 实例的 getAnnotation 方法获取视频标注对象(Annotation)：

  • annotationId 参数指定需要被标注的用户ID，可以是自己，也可以是其他用户。
  • sourceType 参数配置为 "video" 表示视频共享标注。

视频标注事件通知

通过 RtsService 实例的 on 方法注册标注回调通知。

和视频标注相关的事件通知有：

  • videoAnnotationStart: 视频标注开始
  • videoAnnotationStop: 视频标注结束

Annotation 和普通白板对象类似，与普通白板对象的方法和事件一致。

设置标注工具和格式

通过 Annotation 的相关方法设置标注工具和格式，例如：

  • setToolType: 设置工具类型
  • lineWidth = 3: 设置线宽
  • strokeStyle = 'rgba(33, 212, 183, 1)': 设置画笔颜色
  • fontSize = 14: 设置字体大小

开始标注

创建 Annotation 对象即代表标注开始，如果您是频道中第一个创建该对象的，其他用户会收到标注开始事件。

通过 Annotation 的 open(dom: HTMLElement) 方法开启标注并设置显示窗口。

  • 收到 "视频标注开始" (onVideoAnnotationStart) 通知时，可以获取被标注的 userId。
  • 如果 userId 是自己，说明自己被其他用户标注。
  • 如果 userId 是其他用户，说明其他用户被标注。

结束标注

  • 如果您只是暂时切到别的地方，可以调用 Annotation 的 close 方法关闭展示
  • 如果您需要离开标注，可以调用 Annotation 的 leave 方法结束本端的标注
  • 如果您需要结束标注，并且将其他所有端一起退出，可以调用 Annotation 的 stop 方法结束所有端的标注

注意事项

需要设置视频的真实分辨率到标注对象中，用以计算标注显示的位置，通过setAnnotationViewSize方法设置。

可以使用以下工具方法获取视频分辨率：

// 此方法可以查询视频分辨率，兼容 Electron 和 Web
// 需要传入包含视频元素的 DOM（Electron 是 Canvas，Web 是 video 标签）
function getVideoResolution(domRef: HTMLElement) {
  const videoDom: any =
    domRef.getElementsByTagName('video')[0] ||
    domRef.getElementsByTagName('canvas')[0];
  if (videoDom) {
    return {
      width:
        videoDom instanceof HTMLVideoElement
          ? videoDom.videoWidth
          : videoDom.width,
      height:
        videoDom instanceof HTMLVideoElement
          ? videoDom.videoHeight
          : videoDom.height,
    };
  }
  return undefined;
}

// 标注白板设置标注分辨率
annotation.setAnnotationViewSize(getVideoResolution(domRef));

其他操作

设置权限

通过 Annotation 的 setRoleType 方法设置权限角色，支持以下角色：

  • ADMIN: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
  • ATTENDEE: 普通参与者

设置权限角色时，会触发相应回调。

撤销与重做

通过 Annotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 Annotation 的 clearContents 方法清除所有标注内容 (需要 ADMIN 权限)，clearUserContents 方法清除指定用户标注的内容 (清除其他用户的标注需要 ADMIN 权限)。

设置标注是否可见

通过 Annotation 的 hideWhiteboard 方法设置标注是否可见。

截图

通过 Annotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 Annotation 的 cursorSyncType 属性设置光标同步类型。

rtcWhiteboard.cursorSyncType = 'write'; // 仅在鼠标按下做绘制动作时同步光标位置
Last updated on 4/1/2022
← Flutter共享标注 →