初始化

在初始化Link Visual视频Media SDK前，需要正确集成安全图片。详细请参见 集成安全图片 。

依赖引入

// 1. 在根目录下的build.gradle中添加Aliyun Maven仓库的引用
allprojects {
    repositories {
        maven {
            url "http://maven.aliyun.com/nexus/content/repositories/releases"
// 2. App build.gradle中添加依赖
implementation('com.aliyun.iotx:linkvisual-media:2.4.2-ilop')

更多版本发布信息请看 Link Visual SDK更新记录 。

混淆配置

# keep and don't warn Link Visual
-dontwarn com.aliyun.iotx.linkvisual.**
-keep class com.aliyun.iotx.linkvisual.media.** { *; }

SDK接口文档

LinkVisual Media SDK文档（Android）

播放器

视频播放器按功能分为三种。

• 直播播放器
  • 支持接入LinkVisual设备的直播播放。
  • 具有播放延迟低的特性。
  • 具备与设备之间P2P的通信能力。
• 点播播放器 （设备录像）
  • 用于设备本地录像回放的播放，可调整播放进度。
  • 具备与设备之间P2P的通信能力。
• 点播播放器（HLS云存录像）
  • 用于基于HLS的云端录像回放的播放，支持MPEG-TS和fMP4容器，AES-128加密方式。

播放器功能表

播放器的使用示例：

• 直播播放器

  // 构造播放器实例
  LVLivePlayer player = new LVLivePlayer(getApplicationContext());
  // 设置textureview，可使用SDK提供的带画面缩放的ZoomableTextureView组件, 画面不旋转
  player.setTextureView(zoomableTextureView, LVVideoRotationMode.LV_VIDEO_ROTATE_0_CLOCKWISE);
  // 设置必要的监听
  player.setPlayerListener(new ILVPlayerListener() {
      @Override
      public void onError(LVPlayerError error) {
          // 播放报错
      @Override
      public void onPlayerStateChange(LVPlayerState state) {
          Log.d(TAG, "play state= " + state.name());
          switch (state) {
              case STATE_BUFFERING:
                  // 显示正在缓冲
                  break;
              case STATE_IDLE:
                  break;
              case STATE_READY:
                  // 隐藏正在缓冲
                  updatePlayInfo();
                  break;
              case STATE_ENDED:
                  // 隐藏正在缓冲
                  break;
              default:
                  break;
      @Override
      public void onRenderedFirstFrame(int elapsedTimeInMs) {
          // 显示回调，elapsedTimeInMs为出图耗时
      @Override
      public void onVideoSizeChanged(int width, int height) {
          // 宽高变化回调
      @Override
      public void onSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中私有格式的SEI数据帧回调，不再建议使用
      @Override
      public void onStandardSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中标准的SEI数据帧回调
      @Override
      public void onVideoJitterBufferEmpty() {
  // 设置数据源，数据源为设备的IotId
  player.setLiveDataSource(iotId, LVStreamType.LV_STREAM_TYPE_MAJOR);
  // 设置自动重连次数
  player.setReconnectCount(3);
  // 设置解码策略为硬解码优先
  player.setDecoderStrategy(LVDecoderStrategy.LV_DECODER_STRATEGY_HARDWARE_FIRST);
  // 设置画面模式为保持宽高
  player.setVideoScalingMode(LVVideoScalingMode.LV_VIDEO_SCALING_MODE_FIT);
  // 设置播放停止时保留最后一帧画面
  player.setPlayerStoppedDrawingMode(LVPlayerStoppedDrawingMode.LV_ALWAYS_KEEP_LAST_FRAME);
  // 开始播放
  player.start();
  // 停止播放
  player.stop();
  // 释放播放器资源
  player.release();     

• 点播播放器 （设备录像）

  // 构造播放器实例
  LVVodPlayer player = new LVVodPlayer(getApplicationContext());
  // 设置textureview，可使用SDK提供的带画面缩放的ZoomableTextureView组件
  player.setTextureView(zoomableTextureView);
  // 设置必要的监听
  player.setPlayerListener(new ILVPlayerListener() {
      @Override
      public void onError(LVPlayerError error) {
          // 播放报错
      @Override
      public void onPlayerStateChange(LVPlayerState state) {
          Log.d(TAG, "play state= " + state.name());
          switch (state) {
              case STATE_BUFFERING:
                  // 显示正在缓冲
                  break;
              case STATE_IDLE:
                  break;
              case STATE_READY:
                  // 隐藏正在缓冲
                  updatePlayInfo();
                  break;
              case STATE_ENDED:
                  // 隐藏正在缓冲
                  break;
              default:
                  break;
      @Override
      public void onRenderedFirstFrame(int elapsedTimeInMs) {
          // 显示回调，elapsedTimeInMs为出图耗时
      @Override
      public void onVideoSizeChanged(int width, int height) {
          // 宽高变化回调
      @Override
      public void onSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中私有格式的SEI数据帧回调，不再建议使用
      @Override
      public void onStandardSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中标准的SEI数据帧回调
      @Override
      public void onVideoJitterBufferEmpty() {
  // 设置播放完成监听
  player.setVodCompletionListener(new ILVVodPlayerCompletionListener() {
      @Override
      public void onCompletion() {
          // 播放完成
  // 设置数据源：以下两种方式都可以
  // 1. 按设备文件名，初始播放偏移为20S
  player.setDataSourceByLocalRecordFileName(iotId, "fileNamexxxxxxxx", 20000);
  // 2. 按设备时间，从2022-08-29 17:54:14到2022-08-30 02:47:34的录像，初始播放偏移为20S，类型为所有录像
  player.setDataSourceByLocalRecordTime(iotId, 1661766854, 1661798854, 20000, 99);
  // 设置解码策略为硬解码优先
  player.setDecoderStrategy(LVDecoderStrategy.LV_DECODER_STRATEGY_HARDWARE_FIRST);
  // 设置画面模式为保持宽高
  player.setVideoScalingMode(LVVideoScalingMode.LV_VIDEO_SCALING_MODE_FIT);
  // 开始播放
  player.start();
  // 暂停
  player.pause();
  // 恢复
  player.resume();
  // 停止播放
  player.stop();
  // 释放播放器资源
  player.release();                 

• 点播播放器（HLS云存）

  // 构造播放器实例
  LVVodPlayer player = new LVVodPlayer(getApplicationContext());
  // 设置textureview，可使用SDK提供的带画面缩放的ZoomableTextureView组件
  player.setTextureView(zoomableTextureView);
  // 设置必要的监听
  player.setPlayerListener(new ILVPlayerListener() {
      @Override
      public void onError(LVPlayerError error) {
          // 播放报错
      @Override
      public void onPlayerStateChange(LVPlayerState state) {
          Log.d(TAG, "play state= " + state.name());
          switch (state) {
              case STATE_BUFFERING:
                  // 显示正在缓冲
                  break;
              case STATE_IDLE:
                  break;
              case STATE_READY:
                  // 隐藏正在缓冲
                  updatePlayInfo();
                  break;
              case STATE_ENDED:
                  // 隐藏正在缓冲
                  break;
              default:
                  break;
      @Override
      public void onRenderedFirstFrame(int elapsedTimeInMs) {
          // 显示回调，elapsedTimeInMs为出图耗时
      @Override
      public void onVideoSizeChanged(int width, int height) {
          // 宽高变化回调
      @Override
      public void onSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中私有格式的SEI数据帧回调，不再建议使用
      @Override
      public void onStandardSeiInfoUpdate(byte[] buffer, int length, long timeStamp) {
          // 码流中标准的SEI数据帧回调
      @Override
      public void onVideoJitterBufferEmpty() {
  // 设置播放完成监听
  player.setVodCompletionListener(new ILVVodPlayerCompletionListener() {
      @Override
      public void onCompletion() {
          // 播放完成
  // 设置数据源，按云存文件名，初始播放偏移为20S
  player.setDataSourceByCloudRecordFileName(iotId, "fileNamexxxxxxxx", 20000);
  // 设置解码策略为硬解码优先
  player.setDecoderStrategy(LVDecoderStrategy.LV_DECODER_STRATEGY_HARDWARE_FIRST);
  // 设置画面模式为保持宽高
  player.setVideoScalingMode(LVVideoScalingMode.LV_VIDEO_SCALING_MODE_FIT);
  // 开始播放
  player.start();
  // 暂停
  player.pause();
  // 恢复
  player.resume();
  // 停止播放
  player.stop();
  // 释放播放器资源
  player.release();                 

播放器状态介绍

通过设置播放器状态监听器，可接收到状态变更事件，用于相关UI元素的变更。

状态变更事件如：播放中发生错误、主动停止播放等。

• IDLE：播放器没有任何内容播放时的状态。
• BUFFERING：播放器正在缓冲，当前的位置还不可以播放。状态变更事件如：开始播放时缓冲、seekTo()后重新缓冲、网络不佳引起点播缓冲。
• READY：播放器已经有内容在播放。状态变更事件如：首帧数据已经渲染、seekTo()缓冲完成开始播放新内容。对于点播播放器，若已seekTo()或播放到文件结尾，则会回调 OnCompletionListener.onCompletion() 方法，状态会自动切换到ENDED。
• ENDED：播放器已结束播放。播放出错或stop()或播放结束后会切换到该状态。

播放器错误列表

语音对讲

提供App和IPC设备之间端到端的单/双向实时对讲能力。

• 单讲：App端采集并发送音频数据到设备端进行播放，App端采集音频期间手机保持声音静默。
• 全双工对讲：App端和设备端都需要同时做采音和放音，设备端必须支持AEC，否则不建议使用该方案。
• 半双工对讲：APP端和设备端都需要做采音和放音，一端上始终不会出现同时采音和放音的情况，因此设备不要求支持AEC，使用上类似对讲机，由APP端在一次对讲会话中可多次人为控制录音的开启和结束。

支持以下格式的音频。

语音对讲使用方式：

1. 创建语音对讲实例，并设置音频参数。

   liveIntercom = new LVLiveIntercom(getApplicationContext(), AudioParams.AUDIOPARAM_MONO_8K_G711A);

2. 注册监听器，并处理语音对讲回调。

   请在对应的事件回调中处理，包括对讲开始、录音开始和结束、音量回调（用于UI展示）。

   在语音通道建立和对讲过程中，可能发生的错误详见语音对讲错误列表。

   liveIntercom.setLiveIntercomListener(new ILVLiveIntercomListener() {
       @Override
       public void onTalkReady() {
           // 对端已链接，可以开始说话了
       @Override
       public void onRecorderStart() {
           speakBtn.setEnabled(false);
           // 录音开启
       @Override
       public void onRecorderEnd() {
           // 录音结束
       @Override
       public void onRecorderVolume(int volume) {
       @Override
       public void onError(LVLiveIntercomError error) {
           // 对讲发生错误：code: + error.getCode() + error.getSubCode() +  msg: + error.getMessage());
   }

3. 设置增益水平。

   可以设置App端声音采集的增益值，提供“-1 - None, 0 - Mild, 1 - Medium , 2 - high , 3 - Aggressive , 4 - very Aggressive , 5 - Max”六种水平供选择（默认值为无），请根据设备效果来调整。

   liveIntercom.setGainLevel(-1);

4. 设置对讲模式。
   提供五种模式供选择：

   • 单讲：App端采集并发送音频数据到设备端进行播放，App端采集音频期间手机保持声音静默。
   • 全双工对讲（独立）：App端和设备端都需要同时做采音和放音，设备端必须支持AEC，否则不建议使用该方案将会使用设备对讲通道的声音进行播放，可以单独存在不依赖直播通道。
   • 全双工对讲（伴随直播）：App端和设备端都需要同时做采音和放音，设备端必须支持AEC，否则不建议使用该方案将会使用设备直播通道的声音进行播放，要求必须有已开播的直播通道，可通过LVLivePlayer.audioFocus()方法在对讲开启前选择对应的已存在的直播通道。
   • 半双工对讲（独立）：APP端和设备端都需要做采音和放音，一端上始终不会出现同时采音和放音的情况，因此设备不要求支持AEC；使用上类似对讲机，由APP端在一次对讲会话中可多次人为控制录音的开启和结束；将会使用设备对讲通道的声音进行播放，可以单独存在不依赖直播通道；使用限制：该模式需要设备端SDK使用v2.3.3及以上版本的支持，如果使用较旧的设备SDK，将会降级到全双工对讲。
   • 半双工对讲（伴随直播）：APP端和设备端都需要做采音和放音，一端上始终不会出现同时采音和放音的情况，因此设备不要求支持AEC；使用上类似对讲机，由APP端在一次对讲会话中可多次人为控制录音的开启和结束；将会使用设备直播通道的声音进行播放，要求必须有已开播的直播通道，可通过LVLivePlayer.audioFocus()方法在对讲开启前选择对应的已存在的直播通道；使用限制：该模式需要设备端SDK使用v2.3.3及以上版本的支持，如果使用较旧的设备SDK，将会降级到全双工对讲。

   liveIntercom.setLiveIntercomMode(LVLiveIntercomMode.DoubleTalk);

5. 开始对讲。

   对讲开始后，会请求音频焦点，并设置到通话模式，同时将对端播放声音强制路由到扬声器（若已连接蓝牙耳机或者线控耳机则路由到耳机上）。

   // 开始对讲
   liveIntercom.start(iotId);

6. 对讲机讲话状态切换（仅半双工对讲需要关注）。

   开启半双工对讲后，由用户来主动切换对讲状态，按需去做收放音。

   // 该状态下APP端停止播放，采集音频发给设备端，同时设备端会停止音频采集，播放APP端采集的声音
   liveIntercom.listen(true);
   // 该状态下APP端恢复播放，同时设备端会停止播放声音，恢复音频采集
   liveIntercom.listen(false);

7. 结束对讲。

   对讲结束后释放音频焦点，并设置到常规模式，同时取消强制音频播放路由到扬声器规则。对讲过程中默认开启手机回声消除。

   // 停止对讲
   liveIntercom.stop();

8. 释放对讲资源。

   对讲功能不再使用需要主动释放资源。

   // 释放对讲
   liveIntercom.release();

语音对讲错误列表

音频文件录制、播放及上传

提供录制音频文件、播放本地或者网络音频文件及上传音频文件的能力。

录制及播放音频文件支持以下格式。

音频文件录制、播放及上传的使用方式：

• 音频文件录制

  // 创建音频文件录音机
  LVAudioFileRecorder recorder = new LVAudioFileRecorder(getApplicationContext());
  // 设置录制监听器
  recorder.setRecorderListener(new ILVAudioFileRecorderListener() {
              @Override
              public void onRecordStart() {
                  appendLog("录音开始");
                  isRecording = true;
              @Override
              public void onRecordEnd() {
                  appendLog("录音结束");
                  isRecording = false;
              @Override
              public void onRecordVolume(int volume) {
              @Override
              public void onError(LVAudioFileErrorCode code, String message) {
                  appendLog("录制出错： code:" + code + " msg:" + message);
                  isRecording = false;
  // 设置录音参数配置并启动录音
  File audioFile = new File(String.format("/sdcard/%d.amr", System.currentTimeMillis()));
  LVAudioFileCode code = recorder.startRecorder(AudioParams.AUDIOPARAM_MONO_8K_AMR, audioFile.getAbsolutePath());
  // 停止录制
  recorder.stopRecorder();
  // 录音机资源释放
  recorder.release();

• 音频文件播放

  // 创建音频文件播放器
  LVAudioFilePlayer player = new LVAudioFilePlayer(getApplicationContext());
  // 设置播放监听器
  player.setPlayerListener(new ILVAudioFilePlayerListener() {
          @Override
          public void onCompletion() {
              appendLog("播放结束");
  // 播放本地文件
  LVAudioFileCode code = player.startPlay(LVAudioFileType.LV_AUDIO_FILE_TYPE_WAV, "/sdcard/test.wav");
  // 播放网络文件
  LVAudioFileCode code = player.startPlay("https://link-vision-temp-sh.oss-cn-shanghai.aliyuncs.com/test.amr");
  // 停止播放
  player.stopPlay();
  // 播放器资源释放
  player.release();

• 文件上传

  // 创建文件上传器
  LVOSSUploader uploader = new LVOSSUploader(getApplicationContext());
  // 设置文件上传监听器
  uploader.setOSSUploaderCallback(new ILVOSSUploaderListener() {
              @Override
              public void onError(String sessionId, String fileName, int code, String message) {
                  appendLog("上传失败 sessionId=" + sessionId + " fileName=" + fileName + " code=" + code + " message=" + message);
              @Override
              public void onProgress(long uploadBytes, long totalBytes) {
                  appendLog("上传进度 " + uploadBytes + "/" + totalBytes);
              @Override
              public void onCompletion(String sessionId, String fileName) {
                  appendLog("上传完成 sessionId=" + sessionId + " fileName=" + fileName);
  // 开始上传
  uploader.upload(audioFile.getAbsolutePath(), "test.wav", "123456", "https://oss.example.com/test.wav");
  // 上传器资源释放
  uploader.release();

音频文件错误列表

从1.x SDK迁移到2.x版本指南

Android Media SDK在2.0.0版本对接口、方法和类进行了大幅改动。如果您正在使用2.0.0-ilop以下版本，建议通过本文提供的方法升级至2.0.0-ilop。

重要变化

升级步骤

gradle集成，方式与1.x版本类似，修改版本号即可，混淆配置无变化。

implementation('com.google.android.exoplayer:exoplayer-core:2.10.5')
implementation('com.google.android.exoplayer:exoplayer-ui:2.8.3')
implementation('com.google.android.exoplayer:exoplayer-hls:2.10.5')

-dontwarn com.google.android.exoplayer2.**

API变化细节（建议通过文本搜索来定位）

全局组件

直播播放器

enum LVPlayerCode{
    /** 执行成功 */
    LV_PLAYER_SUCCESS  = 0,
    /** 执行失败, 通用错误 */
    LV_PLAYER_ERROR_FAILED  = -1,
    /** 错误的输入参数 */
    LV_PLAYER_ERROR_INVALID_PARAMETER   = -2,
    /** 不支持的接口 */
    LV_PLAYER_ERROR_UNSUPPORTED = -3,
};

com.aliyun.iotx.linkvisual.media.player.bean.LVVideoScalingMode {
//保持宽高
LV_VIDEO_SCALING_MODE_FIT,
//强制填充
LV_VIDEO_SCALING_MODE_FILL;
}

com.aliyun.iotx.linkvisual.media.player.listener.ILVPlayerListener {
    void onError(LVPlayerError error);
    void onPlayerStateChange(LVPlayerState state);
    void onRenderedFirstFrame(int elapsedTimeInMs);
    void onVideoSizeChanged(int width, int height);
    void onSeiInfoUpdate(byte[] buffer, int length, long timeStamp);    void onVideoJitterBufferEmpty();
}

com.aliyun.iotx.linkvisual.media.player.listener.ILVPlayerExternalRenderListener {
    void onVideoFrameUpdate(int width, int height, long timestampInMs);
    void onAudioHeader(int audioBitPerSample, int audioSamplesPerSec, int audioChannel);
    boolean onAudioData(byte[] buffer, int offset, int length);
}

点播播放器

enum LVPlayerCode{
    /** 执行成功 */
    LV_PLAYER_SUCCESS  = 0,
    /** 执行失败, 通用错误 */
    LV_PLAYER_ERROR_FAILED  = -1,
    /** 错误的输入参数 */
    LV_PLAYER_ERROR_INVALID_PARAMETER   = -2,
    /** 不支持的接口 */
    LV_PLAYER_ERROR_UNSUPPORTED = -3,
};

com.aliyun.iotx.linkvisual.media.player.bean.LVVideoScalingMode {
//保持宽高
LV_VIDEO_SCALING_MODE_FIT,
//强制填充
LV_VIDEO_SCALING_MODE_FILL;
}

com.aliyun.iotx.linkvisual.media.player.listener.ILVPlayerListener {
    void onError(LVPlayerError error);
    void onPlayerStateChange(LVPlayerState state);
    void onRenderedFirstFrame(int elapsedTimeInMs);
    void onVideoSizeChanged(int width, int height);
    void onSeiInfoUpdate(byte[] buffer, int length, long timeStamp);    void onVideoJitterBufferEmpty();
}

com.aliyun.iotx.linkvisual.media.player.listener.ILVVodPlayerCompletionListener{
    void onCompletion();
}

com.aliyun.iotx.linkvisual.media.player.listener.ILVPlayerExternalRenderListener {
    void onVideoFrameUpdate(int width, int height, long timestampInMs);
    void onAudioHeader(int audioBitPerSample, int audioSamplesPerSec, int audioChannel);
    boolean onAudioData(byte[] buffer, int offset, int length);
}

语音对讲

LVLiveIntercomCode {
    //执行成功
    LV_LIVE_INTERCOM_SUCCESS,
    //执行失败, 通用错误
    LV_LIVE_INTERCOM_ERROR_FAILED,
    //错误的输入参数
    LV_LIVE_INTERCOM_ERROR_INVALID_PARAMETER,
    //不支持的接口
    LV_LIVE_INTERCOM_ERROR_UNSUPPORTED
}

ILVLiveIntercomListener {
    void onTalkReady();
    void onRecorderStart();
    void onRecorderEnd();
    void onRecorderVolume(int volume);
    void onError(LVLiveIntercomError error);
}

ILVLiveIntercomVoiceChangeListener{
    boolean onAudioData(byte[] pcm, int length);    
}