视频标注

简介

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

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

Windows (C++)

获取视频标注对象

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

  • userId 参数指定需要被标注的用户ID，通常发起方指定自己的 userId，也可以根据实际场景指定其他用户以对其视频进行标注。
  • 通常情况下只有一路视频流，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 方法将标注内容截图。

macOS/iOS (Objective-C)

获取视频标注对象

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

  • userId 参数指定需要被标注的用户ID，通常发起方指定自己的 userId，也可以根据实际场景指定其他用户以对其视频进行标注。
  • 通常情况下只有一路视频流，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: 方法将标注内容截图。

Android (Java)

获取视频标注对象

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

  • userId 参数指定需要被标注的用户ID，通常发起方指定自己的 userId，也可以根据实际场景指定其他用户以对其视频进行标注。
  • 通常情况下只有一路视频流，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 方法将标注内容截图。

Electron/Web (Javascript)

获取视频标注对象

标注对象需要开发者主动创建，发起标注的端，需要创建一个 AnnotationWhiteboard 对象，其他用户会接收到SessionManager 的 videoAnnotationStart 事件，在收到该事件后自行创建对应的 AnnotationWhiteboard 对象，创建 AnnotationWhiteboard 时需要传入对应的 userId。

userId 参数指定需要被标注的用户ID，通常发起方指定自己的 userId，也可以根据实际场景指定其他用户以对其视频进行标注。

共享标注事件通知

通过 SessionManager 的 on 方法设置标注管理器回调函数。

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

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

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

设置标注工具和格式

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

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

开始标注

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

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

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

结束标注

  • 如果您只是暂时切到别的地方，可以调用 AnnotationWhiteboard 的 close 方法关闭展示
  • 如果您需要离开标注，可以调用 AnnotationWhiteboard 的 leaveSession 方法结束本端的标注
  • 如果您需要结束标注，其他所有端也需要一起推出，可以调用 AnnotationWhiteboard 的 closeSession 方法结束所有端的标注

注意事项

被标注的的端需要设置视频的真实分辨率到标注白板对象中，通过setAnnotationViewSize方法设置。

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

// 此方法可以查询视频分辨率，兼容web和 electron，需要传入包含视频元素（electron是canvas，web是video标签）的dom
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;
}

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

其他操作

设置权限

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

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

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

撤销与重做

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

清除标注内容

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

设置标注是否可见

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

截图

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

Last updated on 5/20/2021
← Electron共享标注 →