IJK 播放器使用速查

IJK 播放器使用速查

项目中主要使用 IJK 播放器处理:

相机直播预览
相机视频回放
视频文件播放
UDP / TCP 传输
硬解码和软解码
首帧花屏、卡顿、延时和重连

常用代码位置:

IjkPlayerControl.ets       -> 播放器生命周期和重置
IjkConfigSelect.ets        -> 不同相机的播放器配置
LiveVideoComponent.ets     -> 直播预览
DeclineVideoListItemComponent.ets -> 视频回放

1. 最基本的使用方式

播放直播流

IjkVideoPlayer({
  videoInit: this.videoInit,
  isVisible: Visibility.Visible,
  ijkPlayType: IjkPLayerType.LIVE
});

播放视频文件

IjkVideoPlayer({
  videoInit: this.videoInit,
  isVisible: Visibility.Visible,
  ijkPlayType: IjkPLayerType.PLAYBACK
});

设置播放地址

this.mIVideoPlayer.setUp(this.videoUrl, false);

播放和暂停

this.mIVideoPlayer.play();
this.mIVideoPlayer.pause();

停止和释放

this.mIVideoPlayer.stop();
this.mIVideoPlayer.release();

2. 播放器初始化顺序

IJK 初始化顺序不要随意调换:

this.mIjkMediaPlayer = new IjkMediaPlayer();

this.mIjkMediaPlayer.setContext(
  this.context,
  this.xComponentId
);

this.mIjkMediaPlayer.reset();
this.mIjkMediaPlayer.native_setup();
this.mIjkMediaPlayer.setDataSource(this.videoUrl);
this.mIjkMediaPlayer.prepareAsync();

收到准备完成后再播放:

onPrepared: () => {
  this.mIjkMediaPlayer?.start();
}

基本流程:

创建播放器
  -> 设置 Context
  -> reset
  -> native_setup
  -> 设置地址
  -> prepareAsync
  -> prepared
  -> start

不要在播放器还没有 prepared 时重复调用 start()、reset() 或 prepareAsync()。

3. 直播延时越来越高

直播延时越来越高,通常是播放器缓存一直累积,没有追上实时位置。

关闭播放器包缓存

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'packet-buffering',
  '0'
);

关闭无限缓存

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'infbuf',
  '0'
);

限制最大缓存时长

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'max_cached_duration',
  '1000'
);

可以先这样试:

200  -> 延时最低,但容易卡顿
500  -> 延时和稳定性比较平衡
1000 -> 比较稳
3000 -> 更稳,但延时会明显增加

允许丢帧追赶实时画面

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'framedrop',
  '10'
);

如果画面跟不上但不能丢太多帧,可以先用:

'framedrop', '5'

如果延时越来越高,可以提高到:

'framedrop', '10'

直播刷新数据包

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'flush_packets',
  '1'
);

直播低延时推荐配置

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtsp_transport',
  'udp'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'packet-buffering',
  '0'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'infbuf',
  '0'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'max_cached_duration',
  '500'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'framedrop',
  '5'
);

4. 连接相机直播流

相机局域网预览一般优先使用 UDP:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtsp_transport',
  'udp'
);

UDP 的优点:

延时低
不等待丢失的数据包
适合实时预览

UDP 的问题:

网络差时容易丢包
可能花屏
可能出现画面跳动

如果 UDP 花屏严重,可以改成 TCP:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtsp_transport',
  'tcp'
);

TCP 适合:

网络质量较差
更重视画面完整性
录像回放
不能接受明显花屏

TCP 的问题:

丢包后会等待重传
可能出现卡顿
延时可能变高

5. 首帧花屏怎么处理

首帧花屏通常不是单一原因,优先按下面顺序排查:

1. UDP 丢包或乱序
2. SPS/PPS 或关键帧没有拿完整
3. 探测时间太短
4. 播放器太早开始渲染
5. 硬解码器不兼容
6. 相机本身输出的第一帧异常

增大流探测大小

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'probesize',
  '15360'
);

增大流分析时间

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'analyzeduration',
  '500000'
);

增大最大分析时间

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'analyzemaxduration',
  '500000'
);

增大 UDP 接收缓冲

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'udp-buffer-size',
  '5242880'
);

增大 RTP 乱序重排队列

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtp_reorder_queue_size',
  '120'
);

如果更关注延时,可以降低:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtp_reorder_queue_size',
  '60'
);

首帧阶段不要丢帧

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_CODEC,
  'skip_frame',
  '0'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_CODEC,
  'skip_loop_filter',
  '0'
);

6. 首帧花屏时背景图不要隐藏太早

prepared 只表示播放器准备完成,不一定已经显示了完整画面。

直播背景图最好等到 IJK 的有效播放信息后再隐藏:

if (
  what === 3 &&
  this.playType === IjkPLayerType.LIVE
) {
  EmitterUtils.post(
    EmitterEventEnums.CLOSE_LIVE_VIEW_BG
  );
}

不要只在这里隐藏:

// 可能太早
onPrepared: () => {
  this.isShowBackground = false;
}

更稳的流程:

prepared
  -> 开始解码
  -> 收到有效播放事件
  -> 隐藏背景图

如果背景图消失后仍然花屏,可以延迟隐藏:

if (what === 3) {
  setTimeout(() => {
    this.isShowBackground = false;
  }, 200);
}

7. 首帧慢怎么处理

首帧慢时可以减少探测时间:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'probesize',
  '1024'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'analyzeduration',
  '100000'
);

还可以减少初始帧等待:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'min-frames',
  '2'
);

但这些参数太小可能导致:

流信息识别不完整
首帧花屏
视频格式识别失败
播放器准备失败

所以调试顺序建议:

先解决花屏
再降低 probesize
再降低 analyzeduration
最后调整 min-frames

8. 硬解码怎么用

开启硬解码

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec',
  '1'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec_all_videos',
  '1'
);

硬解码适合:

高分辨率视频
高帧率视频
手机 CPU 占用高
手机发热严重
播放耗电明显

硬解码的常见问题:

黑屏
绿屏
花屏
画面停止
部分相机编码格式不兼容

关闭硬解码

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec',
  '0'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec-audio',
  '0'
);

关闭后使用软件解码:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_CODEC,
  'threads',
  '0'
);

遇到花屏时建议这样对比:

先用硬解码播放
  -> 仍然花屏,切软件解码
  -> 软件解码正常,说明可能是硬解码兼容问题
  -> 软件解码也花屏,再检查 UDP、关键帧和探测参数

硬解码不能解决网络丢包造成的花屏。

9. 某个相机单独配置

不要为了适配一个相机,直接修改所有相机共用配置。

根据机型选择配置

const model = cameraInfo.model;

if (model === 'CAMERA_MODEL_C100_PRO') {
  this.c100ProConfig(mIjkMediaPlayer);
} else if (model === 'CAMERA_MODEL_SJ30') {
  this.sj30Config(mIjkMediaPlayer);
} else {
  this.defaultConfig(mIjkMediaPlayer);
}

单独配置 C100 Pro

private c100ProConfig(
  player: IjkMediaPlayer
): void {
  player.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'rtsp_transport',
    'udp'
  );

  player.setOption(
    IjkMediaPlayer.OPT_CATEGORY_PLAYER,
    'mediacodec',
    '0'
  );

  player.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'probesize',
    '15360'
  );
}

单独配置 SJ30

private sj30Config(
  player: IjkMediaPlayer
): void {
  player.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'rtsp_transport',
    'udp'
  );
}

配置选择最好集中在:

IjkConfigSelect.ets

10. stableFirstFrameConfig 触发软重置太频繁

首帧保护配置一般是为了防止播放器拿到无效帧后直接显示花屏。

但是如果判断条件太敏感,就会出现:

刚开始播放
  -> 判断缓存异常
  -> stop/reset
  -> 重新拉流
  -> 又被判断异常
  -> 再次 reset

常见原因:

1. 只检查一次缓存就重置
2. 网络刚连接时缓存还没有稳定
3. UDP 短时间数据突发
4. 播放器刚 prepare 完成就开始检测
5. 错误回调和定时器同时重置
6. 模式切换时旧播放器和新播放器同时执行

不要一次异常就重置:

// 不建议
if (cachedBytes > threshold) {
  this.mIjkMediaPlayer.stop();
  this.initPlay();
}

改成连续异常确认:

private abnormalCount: number = 0;
private lastResetTime: number = 0;
private readonly maxAbnormalCount: number = 3;
private readonly resetCooldown: number = 30000;

private checkStableFirstFrame(): void {
  const cachedBytes =
    this.mIjkMediaPlayer?.getVideoCachedBytes() ?? 0;

  if (cachedBytes > 0.05 * 1024 * 1024) {
    this.abnormalCount++;
  } else {
    this.abnormalCount = 0;
  }

  const now = Date.now();

  if (
    this.abnormalCount >= this.maxAbnormalCount &&
    now - this.lastResetTime > this.resetCooldown
  ) {
    this.abnormalCount = 0;
    this.lastResetTime = now;

    this.mIjkMediaPlayer?.stop();

    setTimeout(() => {
      this.initPlay();
    }, 1000);
  }
}

启动检测时要避开刚初始化的阶段:

private checkStartTime: number = 0;

startCacheCheck(): void {
  this.checkStartTime = Date.now();

  this.frameRateCheck = setInterval(() => {
    if (Date.now() - this.checkStartTime < 3000) {
      return;
    }

    this.checkStableFirstFrame();
  }, 10000);
}

检测前还要确认当前确实在播放:

if (
  this.playStatus !== PlayStatus.PLAY ||
  !this.mIjkMediaPlayer
) {
  return;
}

11. 防止重复 reset、重复重连

播放器重置必须加锁:

private isResetting: boolean = false;

private resetPlayer(): void {
  if (this.isResetting) {
    return;
  }

  this.isResetting = true;

  this.mIjkMediaPlayer?.stop();

  setTimeout(() => {
    this.mIjkMediaPlayer?.reset();
    this.isResetting = false;
    this.initPlay();
  }, 500);
}

重连前清除旧定时器:

private retryTimer: number = -1;

private scheduleRetry(): void {
  if (this.retryTimer !== -1) {
    clearTimeout(this.retryTimer);
  }

  this.retryTimer = setTimeout(() => {
    this.retryTimer = -1;
    this.initPlay();
  }, 1000) as number;
}

错误回调和软重置都调用重连时,统一走一个方法:

onError: () => {
  this.scheduleRetry();
}

onCacheAbnormal: () => {
  this.scheduleRetry();
}

不要分别写两套:

setTimeout(() => this.initPlay(), 1000);
setTimeout(() => this.initPlay(), 1000);

12. 模式切换后重新拉流很慢

模式切换时重点检查有没有重复执行:

stop();
reset();
prepareAsync();
start();

推荐一次切换只执行一条播放链:

async switchMode(): Promise<void> {
  this.clearRetryTimer();
  this.clearCacheTimer();

  await this.releasePlayer();

  this.createPlayer();
  this.applyConfig();
  this.setDataSource();
  this.prepareAsync();
}

释放播放器:

private async releasePlayer(): Promise<void> {
  if (!this.mIjkMediaPlayer) {
    return;
  }

  const player = this.mIjkMediaPlayer;
  this.mIjkMediaPlayer = undefined;

  player.stop();
  player.release();
}

模式切换时要清理:

重连定时器
缓存检测定时器
错误重试次数
旧播放器
旧播放地址
旧事件监听

13. 播放器错误重试

private retryCount: number = 0;
private readonly maxRetryCount: number = 3;

private retryPlay(): void {
  if (this.retryCount >= this.maxRetryCount) {
    return;
  }

  this.retryCount++;

  setTimeout(() => {
    if (this.isCameraConnected()) {
      this.initPlay();
    }
  }, 1000);
}

播放成功后清零:

onInfo: (what: number) => {
  if (what === 3) {
    this.retryCount = 0;
  }
}

相机已经断开时不要继续重试:

if (!this.isCameraConnected()) {
  return;
}

14. 不需要声音时关闭音频

相机实时预览如果没有音频需求,可以关闭音频解码:

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'allowed_media_types',
  'video'
);

mIjkMediaPlayer.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'an',
  '1'
);

这样可以减少:

音频探测
音频解码
音频缓冲
CPU 占用

15. IJK 配置怎么选择

低延时预览

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtsp_transport',
  'udp'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'packet-buffering',
  '0'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'infbuf',
  '0'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'max_cached_duration',
  '500'
);

花屏优先处理

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'probesize',
  '15360'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'analyzeduration',
  '500000'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'udp-buffer-size',
  '5242880'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtp_reorder_queue_size',
  '120'
);

网络差优先稳定

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_FORMAT,
  'rtsp_transport',
  'tcp'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'packet-buffering',
  '1'
);

CPU 占用高

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec',
  '1'
);

硬解不兼容时:

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_PLAYER,
  'mediacodec',
  '0'
);

player.setOption(
  IjkMediaPlayer.OPT_CATEGORY_CODEC,
  'threads',
  '0'
);

16. 调试日志

遇到播放问题,先把这些日志加上:

LogUtils.info(TAG, `camera=${cameraModel}`);
LogUtils.info(TAG, `url=${videoUrl}`);
LogUtils.info(TAG, `prepare=${Date.now()}`);
LogUtils.info(TAG, `prepared=${Date.now()}`);
LogUtils.info(TAG, `what=${what}, extra=${extra}`);
LogUtils.info(TAG, `retryCount=${this.retryCount}`);
LogUtils.info(
  TAG,
  `cachedBytes=${this.mIjkMediaPlayer?.getVideoCachedBytes()}`
);

重点记录:

开始 prepare
  -> prepared
  -> 开始解码
  -> 收到有效播放事件
  -> 首帧显示
  -> 是否发生 reset

根据时间差可以判断:

prepare 慢       -> 相机或网络问题
prepared 慢      -> IJK 探测问题
首帧慢            -> 关键帧或缓冲问题
首帧花屏          -> UDP、探测、硬解或关键帧问题
播放后越来越慢    -> 缓存或解码跟不上
频繁 reset        -> 首帧保护判断过于敏感

17. 遇到问题直接查这里

延时越来越高:
packet-buffering=0
infbuf=0
减小 max_cached_duration
适当增大 framedrop

首帧花屏:
增大 probesize
增大 analyzeduration
增大 udp-buffer-size
增大 rtp_reorder_queue_size
尝试 TCP
尝试关闭硬解

首帧很慢:
适当减小 probesize
适当减小 analyzeduration
min-frames 调小

硬解黑屏、绿屏、花屏:
mediacodec=0
mediacodec-audio=0
threads=0

软重置频繁:
连续异常多次后再重置
增加 reset 冷却时间
初始化后延迟检测
清理重复的错误重试和定时器

模式切换拉流慢:
只保留一条播放链
释放旧播放器
清理旧定时器
防止旧回调启动新播放器

18. 脱敏后的完整直播案例

下面的地址、机型和业务字段都使用占位符:

private async startLive(): Promise<void> {
  const streamUrl = 'RTSP_STREAM_URL';
  const cameraModel = 'CAMERA_MODEL';

  this.clearRetryTimer();
  this.clearCacheTimer();

  this.mIjkMediaPlayer = new IjkMediaPlayer();

  this.mIjkMediaPlayer.setContext(
    this.context,
    this.xComponentId
  );

  this.mIjkMediaPlayer.reset();
  this.mIjkMediaPlayer.native_setup();

  // 直播使用 UDP
  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'rtsp_transport',
    'udp'
  );

  // 降低直播延时
  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_PLAYER,
    'packet-buffering',
    '0'
  );

  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_PLAYER,
    'infbuf',
    '0'
  );

  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_PLAYER,
    'max_cached_duration',
    '500'
  );

  // 首帧防花屏
  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'probesize',
    '15360'
  );

  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'analyzeduration',
    '500000'
  );

  this.mIjkMediaPlayer.setOption(
    IjkMediaPlayer.OPT_CATEGORY_FORMAT,
    'udp-buffer-size',
    '5242880'
  );

  // 特殊机型单独处理
  if (cameraModel === 'SPECIAL_CAMERA_MODEL') {
    this.mIjkMediaPlayer.setOption(
      IjkMediaPlayer.OPT_CATEGORY_PLAYER,
      'mediacodec',
      '0'
    );
  }

  this.mIjkMediaPlayer.setDataSource(streamUrl);
  this.mIjkMediaPlayer.prepareAsync();
}

播放器信息回调:

onInfo: (what: number, extra: number) => {
  LogUtils.info(
    TAG,
    `what=${what}, extra=${extra}`
  );

  // 等有效播放事件后再隐藏背景图
  if (
    what === 3 &&
    this.playType === IjkPLayerType.LIVE
  ) {
    EmitterUtils.post(
      EmitterEventEnums.CLOSE_LIVE_VIEW_BG
    );
  }
}

播放器错误回调:

onError: (what: number, extra: number) => {
  LogUtils.error(
    TAG,
    `IJK error what=${what}, extra=${extra}`
  );

  this.scheduleRetry();
}

隐私字段统一使用:

RTSP_STREAM_URL
CAMERA_MODEL
CAMERA_IP
CAMERA_SERIAL
DEVICE_ID
XCOMPONENT_ID
posted @ 2026-09-01 16:56  带头大哥d小弟  阅读(73)  评论(0)    收藏  举报