更新时间:2024-12-06 GMT+08:00

客户端对象(HWLLSClient)

本章节介绍了低时延直播Web SDK的HWLLSClient接口详情。

表1 主入口接口

接口

描述

startPlay

开始播放,客户端根据输入的URL到服务端拉取对应的主播流。

switchPlay

快速切换下一路流播放。

stopPlay

停止播放。

replay

重新播放。

startPlayCustomize

自定义播放

resume

恢复播放。

pause

暂停播放。

pauseVideo

暂停视频。

resumeVideo

恢复视频。

pauseAudio

暂停音频。

resumeAudio

恢复音频。

setPlayoutVolume

设置播放音量。

getPlayoutVolume

获取音频音量。

muteAudio

静音

streamStatistic

设置是否开启流信息统计。

enableStreamStateDetection

开启/关闭音视频码流状态探测功能。

on

注册客户端对象事件回调接口。

off

取消注册客户端对象事件回调接口。

destroyClient

销毁客户端对象。

fullScreenToggle

开启关闭全屏

startPlay

startPlay(url: string, options: StartPlayOptions): Promise<void>

功能说明

开始播放,客户端根据输入的URL到服务端拉取对应的主播流。

请求参数

  • url:string类型,必选。拉流URL,格式如:webrtc://{domain}/{AppName}/{StreamName}。
    • webrtc://:固定不变,表示使用webrtc方式拉流。
    • domain:拉流域名,使用在华为云注册的拉流域名。
    • AppName:应用名,使用在华为云注册的应用名。
    • StreamName:流名,和推流的流名保持一致。
  • options:必选,StartPlayOptions类型。播放配置参数,StartPlayOptions定义如下:{
    • elementId:必选,播放DOM标识ID。
    • objectFit:可选,string类型,默认值为cover。支持的枚举值如下:
      • contain:优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
      • cover:优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
      • fill:视频内容完全填充视窗。如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
    • muted:可选,boolean类型,true表示静音,false表示不静音。默认值为false。
    • sessionId:可选,string类型,一次完整会话的统一标识。
    • showLoading:可选,boolean类型,true表示开启loading的展示效果,默认为false。当该参数设置为true时,起播loading效果同步开启,播放过程中发生缓冲时loading的效果,需根据setParameter接口中的LOADING_CONFIG进行设置。
      • Android端QQ浏览器不支持该功能。
      • 建议showLoading不设置,或者设置为false。
    • autoPlay:可选,boolean类型,true表示开启自动起播功能,false表示非自动起播,需要人为触发播放,默认为true。
    • poster:可选,对象定义如下:{
      • url:可选,string类型。设置播放封面图片完整地址,图片格式限JPGPNG和静态GIF格式,大小不超过1MB,尺寸不超过1920 x 1080,文件名不得含有中文字符。
      • mode:可选,string类型。默认值为crop。支持的枚举值如下:{
        • fill:视频内容完全填充视窗,如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
        • crop:海报(即视频播放封面)原始尺寸大小展示,如果超出播放区域,则会对超出部分进行裁剪,否则在播放窗口居中展示。

        }

      • startEnable:可选,boolean类型。启动播放时是否展示播放封面,true表示展示,false表示不展示播放封面,默认值false。该参数只在设置非自动播放场景下生效。
      • pauseEnable:可选,boolean类型。触发暂停操作时,是否在播放页面展示播放封面,true表示展示播放封面,false表示不展示,默认值false。

      }

    • webrtcConfig:可选,WebRTCConfig类型。指定媒体类型进行拉流的配置参数,WebRTCConfig定义如下:{
      • receiveVideo:可选,boolean类型。设置是否拉取视频进行播放,true表示拉取视频进行播放,false表示不拉取视频播放,默认值true。该属性值和receiveAudio不能同时设置为false。
      • receiveAudio:可选,boolean类型。设置是否拉取音频进行播放,true表示拉取音频进行播放,false表示不拉取音频播放,默认值true。该属性值和receiveVideo不能同时设置为false。

    }

    • domainPolicy:可选,DomainPolicy类型。指定接入域名的策略,该设置仅在schedulePolicy参数为"DNS"模式时生效,DomainPolicy定义如下:{
      • 0:可选,number类型。表示使用用户自定义域名,默认值0。
      • 1:可选,number类型。表示使用公共接入域名。

      }

    • autoDowngrade:可选,boolean类型。true表示启用自动降级,false表示不启用自动降级,默认false。
    • downgradeUrl:可选,对象定义如下 :{
      • hlsUrl?:可选, string类型。标识降级hls播放地址。
      • flvUrl?:可选,string类型。标识降级flv播放地址。

      }

返回参数

Promise<void>:返回一个Promise对象。

在低延时直播服务发生故障的场景下,可根据特定错误码(HWLLS_BUSSINESS_DOWNGRADE),进行播放降级,请参考SDK使用

switchPlay

switchPlay(url: string, options: StartPlayOptions): Promise<void>

功能说明

起播成功后,快速切换下一路流播放。

请求参数

  • url:必选,string类型。拉流URL,格式如:webrtc://{domain}/{AppName}/{StreamName}。
    • webrtc://:固定不变,表示使用webrtc方式拉流。
    • domain:拉流域名,使用在华为云注册的拉流域名。
    • AppName:应用名,使用在华为云注册的应用名。
    • StreamName:流名,和推流的流名保持一致。
  • options:可选,StartPlayOptions类型。播放配置参数,如果不携带该参数,则复用首次起播携带的options数据。StartPlayOptions定义如下:{
    • elementId:必选,播放DOM标识ID。
    • objectFit:可选,string类型,默认值为cover。支持的枚举值如下:
      • contain:优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
      • cover:优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
      • fill:视频内容完全填充视窗。如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
    • muted:可选,boolean类型,true表示静音,false表示不静音。默认值为false。
    • sessionId:可选,string类型,一次完整会话的统一标识。
    • showLoading:可选,boolean类型,true表示开启loading的展示效果,默认为false。当该参数设置为true时,起播loading效果同步开启,播放过程中发生缓冲时loading的效果,需根据setParameter接口中的LOADING_CONFIG进行设置。
    • autoPlay:可选,boolean类型,true表示开启自动起播功能,false表示非自动起播,需要人为触发播放,默认为true。
    • poster:可选,对象定义如下:{
      • url:可选,string类型。设置播放封面图片完整地址,图片格式限JPGPNG和静态GIF格式,大小不超过1MB,尺寸不超过1920 x 1080,文件名不得含有中文字符。
      • mode:可选,string类型。默认值为cover。支持的枚举值如下:{
        • fill:视频内容完全填充视窗,如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
        • crop:海报(即视频播放封面)原始尺寸大小展示,如果超出播放区域,则会对超出部分进行裁剪,否则在播放窗口居中展示。

        }

      • startEnable:可选,boolean类型。启动播放时是否展示播放封面,true表示展示,false表示不展示播放封面,默认值false。该参数只在设置非自动播放场景下生效。
      • pauseEnable:可选,boolean类型。触发暂停操作时,是否在播放页面展示播放封面,true表示展示播放封面,false表示不展示,默认值false。

      }

    • webrtcConfig:可选,WebRTCConfig类型。指定媒体类型进行拉流的配置参数,WebRTCConfig定义如下:{
      • receiveVideo:可选,boolean类型。设置是否拉取视频进行播放,true表示拉取视频进行播放,false表示不拉取视频播放,默认值true。该属性值和receiveAudio不能同时设置为false。
      • receiveAudio:可选,boolean类型。设置是否拉取音频进行播放,true表示拉取音频进行播放,false表示不拉取音频播放,默认值true。该属性值和receiveVideo不能同时设置为false。

    }

    • schedulePolicy:可选,SchedulePolicy类型。指定接入调度策略,SchedulePolicy定义如下:{
      • DNS:可选,string类型。表示域名DNS解析接入,默认值"DNS"。
      • HTTPDNS:可选,string类型。表示使用HTTPDNS接入域名。

      }

    • domainPolicy:可选,DomainPolicy类型。指定接入域名的策略,该设置仅在schedulePolicy参数为"DNS"模式时生效,DomainPolicy定义如下:{
      • 0:可选,number类型。表示使用用户自定义域名,默认值0。
      • 1:可选,number类型。表示使用公共接入域名。

      }

返回参数

Promise<void>:返回一个Promise对象。

在低延时直播服务发生故障的场景下,可根据特定错误码(HWLLS_BUSSINESS_DOWNGRADE),进行播放降级,请参考SDK使用

stopPlay

stopPlay(): boolean

功能说明

停止播放。

请求参数

返回参数

boolean:停止播放结果。true表示成功,false表示失败。

replay

replay(): Promise<boolean>

功能说明

重新播放。

请求参数

返回参数

Promise<boolean>:重新播放结果,true表示成功,false表示失败。

startPlayCustomize

startPlayCustomize(url: string, options: StartPlayOptions): Promise<boolean>

功能说明

自定义播放。

请求参数

  • url:必选,string类型。拉流URL,自定义URL播放
  • options:可选,StartPlayOptions类型。播放配置参数,如果不携带该参数,则复用首次起播携带的options数据。StartPlayOptions定义如下:{
    • elementId:必选,播放DOM标识ID。
    • objectFit:可选,string类型,默认值为cover。支持的枚举值如下:
      • contain:优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频尺寸与显示视窗尺寸不一致,在保持长宽比的前提下,将视频进行缩放后填满视窗,缩放后的视频四周会有一圈黑边。
      • cover:优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,则视频流会按照显示视窗的比例进行周边裁剪或图像拉伸后填满视窗。
      • fill:视频内容完全填充视窗。如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
    • muted:可选,boolean类型,true表示静音,false表示不静音。默认值为false。
    • sessionId:可选,string类型,一次完整会话的统一标识。
    • showLoading:可选,boolean类型,true表示开启loading的展示效果,默认为false。当该参数设置为true时,起播loading效果同步开启,播放过程中发生缓冲时loading的效果,需根据setParameter接口中的LOADING_CONFIG进行设置。
    • autoPlay:可选,boolean类型,true表示开启自动起播功能,false表示非自动起播,需要人为触发播放,默认为true。
    • poster:可选,对象定义如下:{
      • url:可选,string类型。设置播放封面图片完整地址,图片格式限JPGPNG和静态GIF格式,大小不超过1MB,尺寸不超过1920 x 1080,文件名不得含有中文字符。
      • mode:可选,string类型。默认值为cover。支持的枚举值如下:{
        • fill:视频内容完全填充视窗,如果视频的宽高比与视窗不相匹配,那么视频将被拉伸以适应视窗。
        • crop:海报(即视频播放封面)原始尺寸大小展示,如果超出播放区域,则会对超出部分进行裁剪,否则在播放窗口居中展示。

        }

      • startEnable:可选,boolean类型。启动播放时是否展示播放封面,true表示展示,false表示不展示播放封面,默认值false。该参数只在设置非自动播放场景下生效。
      • pauseEnable:可选,boolean类型。触发暂停操作时,是否在播放页面展示播放封面,true表示展示播放封面,false表示不展示,默认值false。

      }

    • webrtcConfig:可选,WebRTCConfig类型。指定媒体类型进行拉流的配置参数,WebRTCConfig定义如下:{
      • receiveVideo:可选,boolean类型。设置是否拉取视频进行播放,true表示拉取视频进行播放,false表示不拉取视频播放,默认值true。该属性值和receiveAudio不能同时设置为false。
      • receiveAudio:可选,boolean类型。设置是否拉取音频进行播放,true表示拉取音频进行播放,false表示不拉取音频播放,默认值true。该属性值和receiveVideo不能同时设置为false。

    }

    • schedulePolicy:可选,SchedulePolicy类型。指定接入调度策略,SchedulePolicy定义如下:{
      • DNS:可选,string类型。表示域名DNS解析接入,默认值"DNS"。
      • HTTPDNS:可选,string类型。表示使用HTTPDNS接入域名。

      }

    • domainPolicy:可选,DomainPolicy类型。指定接入域名的策略,该设置仅在schedulePolicy参数为"DNS"模式时生效,DomainPolicy定义如下:{
      • 0:可选,number类型。表示使用用户自定义域名,默认值0。
      • 1:可选,number类型。表示使用公共接入域名。

      }

返回参数

Promise<void>:返回一个Promise对象。

resume

resume(): Promise<boolean>

功能说明

恢复播放。

请求参数

返回参数

Promise<boolean>:恢复音视频播放结果,true表示成功,false表示失败。

pause

pause(): boolean

功能说明

暂停音视频播放。

请求参数

返回参数

boolean:暂停播放结果,true表示成功,false表示失败。

pauseVideo

pauseVideo(): boolean

功能说明

暂停视频,暂停后卡在当前画面。

请求参数

返回参数

boolean:暂停视频播放结果,true表示成功,false表示失败。

resumeVideo

resumeVideo(): Promise<boolean>

功能说明

恢复视频播放。

请求参数

返回参数

Promise<boolean>:恢复视频播放结果,true表示成功,false表示失败。

pauseAudio

pauseAudio(): boolean

功能说明

暂停音频。

请求参数

返回参数

boolean:暂停音频播放结果,true表示成功,false表示失败。

resumeAudio

resumeAudio(): Promise<boolean>

功能说明

恢复音频。

请求参数

返回参数

Promise<boolean>:恢复音频播放结果,true表示成功,false表示失败。

setPlayoutVolume

setPlayoutVolume(volume: number): boolean

功能说明

设置音频音量,iOS 不支持。

请求参数

volume:必选,number类型,取值范围为[0,100],音频的音量值。

返回参数

boolean:设置音频音量是否成功,true表示成功,false表示失败。

getPlayoutVolume

 getPlayoutVolume(): number

功能说明

获取音频音量。

请求参数

返回参数

number:音量值,取值范围为[0,100]。

muteAudio

muteAudio(isMute: boolean): void

功能说明

静音。

请求参数

  • isMute:必选,boolean类型,是否静音,true表示静音,false表示取消静音。

返回参数

streamStatistic

streamStatistic(enable: boolean, interval: number): void

功能说明

设置是否开启流信息统计。

请求参数

  • enable:必选,boolean类型,是否开启流信息统计,true表示开启统计。
  • interval:必选,number类型,设置统计间隔,单位为秒,取值范围为[1, 60],默认值为1。

返回参数

enableStreamStateDetection

enableStreamStateDetection(enable: boolean, interval: number, interruptRetry:StreamInterruptRetry): boolean

功能说明

开启/关闭音、视频码流状态探测功能,开启后可探测推流侧是否处于断流的状态。

请求参数

  • enable:必选,boolean类型,true表示开启音视频码流状态探测,false表示关闭音视频码流状态探测。默认值为false。
  • interval:必选,number类型,单位为秒,取值范围为[1,60]。音视频无码流状态的判断时间。默认值为3,推荐设置为3。
  • interruptRetry:可选,StreamInterruptRetry类型。断流重试播放配置参数,StreamInterruptRetry定义为:{

    enable:boolean类型,开启断流后尝试自动恢复播放。默认值为false,即不开启自动重试。

    retryInterval:number类型,拉流播放的重试周期,单位为秒。最小值10,最大值建议不超过60,默认值为30。

    retryTimes:number类型,尝试重新恢复播放的最大重试次数。最小值1,默认值为30。

    }

返回参数

boolean:是否成功,true表示成功,false表示失败。

Android端QQ浏览器不支持该功能。

on

on(event: string, handler: function, withTimeout?: boolean): void

功能说明

注册客户端对象事件回调接口。

请求参数
  • event:必选,string类型,事件名称。具体请参见HWLLSClientEvent
  • handler:必选,function类型,事件处理方法。
  • withTimeout:选填,boolean类型,是否超时报错

返回参数

off

off(event: string, handler: function): void

功能说明

取消注册客户端对象事件回调接口。

请求参数
  • event:必选,string类型,事件名称。具体请参见HWLLSClientEvent
  • handler:必选,function类型,事件处理方法。

返回参数

destroyClient

destroyClient(): void

功能说明

销毁客户端对象。

请求参数

返回参数

fullScreenToggle

fullScreenToggle(isExit: boolean): void

功能说明

开启关闭全屏。

请求参数

isExit:必选,布尔类型,默认false。

返回参数