---

每日一句正能量

能拍打在礁石上的浪花，才绽放的最壮烈。
安逸的沙滩上不会有惊涛拍岸。人生的华彩乐章，往往诞生于与困难的激烈碰撞中。不要惧怕礁石（困难），因为正是那奋力的一击，才让浪花（生命）迸发出了最震撼的美。

---

一、引言：媒体流处理是音视频应用的「生命线」

在 HarmonyOS 生态中，媒体流处理能力是构建现代音视频应用的基石。无论是直播平台的低延迟推流、短视频应用的预加载无缝切换、在线教育课程的倍速播放与精准拖拽，还是跨设备 RTC 通话的实时采集与传输，都离不开对流媒体数据的精细化控制。

与本地文件播放不同，流媒体处理面临三大核心挑战：网络抖动导致的卡顿问题、多码率源的自适应切换问题、大文件边下载边播放的缓存管理问题。HarmonyOS 6（API 23）提供了完整的媒体流处理能力体系，涵盖 AVPlayer 流式播放、dataSrc 边播边缓存、setMediaSource 预加载、HLS/DASH 自适应码率、音视频轨道切换等高阶特性。本文将从架构设计到代码实战，全面解析媒体流处理的工业级方案。

---

二、整体架构：三层流媒体处理体系

图1：HarmonyOS 媒体流处理整体架构

HarmonyOS 的媒体流处理体系分为三层：

• 应用层：直播播放器（低延迟/弹幕互动）、点播播放器（进度拖拽/倍速播放）、短视频应用（预加载/无缝切换）、RTC 通话（实时采集/传输）。
• 媒体引擎层：AVPlayer 负责流式播放与状态机管理，AVRecorder 负责流式录制与编码，AudioRenderer 负责音频流输出，VideoDecoder 负责视频硬解码加速。
• 协议与传输层：HLS/DASH 支持自适应码率切换，HTTP/HTTPS 支持标准点播下载，HTTP-FLV 支持低延迟直播，分布式软总线 支持跨设备流传输。

---

三、AVPlayer 流媒体播放深度实战

3.1 状态机与事件流转

图2：AVPlayer 状态机与事件流转

AVPlayer 采用严格的状态机设计，共包含 idle、initialized、prepared、playing、paused、completed、stopped、released 八个状态。状态转换必须通过特定 API 触发，非法状态调用将导致错误。

关键规则：所有事件监听必须在 idle 状态下、设置资源前注册，否则可能收不到资源设置过程中的 stateChange 和 error 事件，这是最常见的踩坑点。

3.2 完整代码：流媒体播放器引擎

import { media } from '@kit.MediaKit';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 流媒体播放器引擎
 * 支持 HLS / DASH / HTTP / HTTP-FLV 协议
 */
class StreamingPlayerEngine {
  private avPlayer: media.AVPlayer | null = null;
  private surfaceId: string = '';

  // 播放状态
  @State duration: number = 0;
  @State currentTime: number = 0;
  @State isPlaying: boolean = false;
  @State bufferPercent: number = 0;
  @State availableBitrates: number[] = [];

  /**
   * 初始化播放器并设置事件回调
   */
  async initialize(surfaceId: string): Promise<void> {
    this.surfaceId = surfaceId;
    this.avPlayer = await media.createAVPlayer();

    // ===== 必须在 idle 状态下注册所有事件 =====
    this.registerCallbacks();
  }

  /**
   * 注册播放器事件回调
   */
  private registerCallbacks(): void {
    if (!this.avPlayer) return;

    // 1. 状态机变化（最核心的监听）
    this.avPlayer.on('stateChange', (state: media.AVPlayerState, reason: media.StateChangeReason) => {
      console.info(`[Player] 状态变化: ${state}, 原因: ${reason}`);
      switch (state) {
        case 'idle':
          console.info('[Player] 播放器已重置');
          break;
        case 'initialized':
          console.info('[Player] 资源已设置');
          break;
        case 'prepared':
          console.info('[Player] 准备完成，可以播放');
          this.duration = this.avPlayer!.duration;
          break;
        case 'playing':
          this.isPlaying = true;
          break;
        case 'paused':
          this.isPlaying = false;
          break;
        case 'completed':
          this.isPlaying = false;
          console.info('[Player] 播放完成');
          break;
        case 'error':
          console.error(`[Player] 播放错误: ${reason}`);
          this.avPlayer?.reset();
          break;
      }
    });

    // 2. 错误事件
    this.avPlayer.on('error', (err: BusinessError) => {
      console.error(`[Player] error 事件: ${err.code} - ${err.message}`);
      this.avPlayer?.reset();
    });

    // 3. 进度更新（每秒触发）
    this.avPlayer.on('timeUpdate', (time: number) => {
      this.currentTime = time;
    });

    // 4. 缓冲状态监控（流媒体关键）
    this.avPlayer.on('bufferingUpdate', (infoType: media.BufferingInfoType, value: number) => {
      switch (infoType) {
        case media.BufferingInfoType.BUFFERING_START:
          console.info('[Player] 开始缓冲...');
          break;
        case media.BufferingInfoType.BUFFERING_END:
          console.info('[Player] 缓冲结束');
          break;
        case media.BufferingInfoType.BUFFERING_PERCENT:
          this.bufferPercent = value;
          console.info(`[Player] 缓冲进度: ${value}%`);
          break;
        case media.BufferingInfoType.CACHED_DURATION:
          console.info(`[Player] 已缓存时长: ${value}ms`);
          break;
      }
    });

    // 5. Seek 完成通知
    this.avPlayer.on('seekDone', (seekDoneTime: number) => {
      console.info(`[Player] Seek 完成，当前位置: ${seekDoneTime}ms`);
    });

    // 6. 倍速设置完成
    this.avPlayer.on('speedDone', (speed: number) => {
      console.info(`[Player] 倍速设置完成: ${speed}x`);
    });

    // 7. HLS/DASH 可用码率列表
    this.avPlayer.on('availableBitrates', (bitrates: number[]) => {
      this.availableBitrates = bitrates;
      console.info(`[Player] 可用码率列表: ${bitrates.length} 个`);
    });

    // 8. 码率切换完成
    this.avPlayer.on('bitrateDone', (bitrate: number) => {
      console.info(`[Player] 码率切换完成: ${bitrate}bps`);
    });

    // 9. 轨道切换完成
    this.avPlayer.on('trackChange', (index: number, isSelect: boolean) => {
      console.info(`[Player] 轨道切换: index=${index}, isSelect=${isSelect}`);
    });

    // 10. 播放至结尾
    this.avPlayer.on('endOfStream', () => {
      console.info('[Player] 播放至资源末尾');
    });
  }

  /**
   * 播放网络流媒体（URL 方式）
   */
  async playUrl(url: string): Promise<void> {
    if (!this.avPlayer) {
      throw new Error('播放器未初始化');
    }
    this.avPlayer.url = url;
    // 设置显示画面（视频播放必需）
    if (this.surfaceId) {
      this.avPlayer.surfaceId = this.surfaceId;
    }
    await this.avPlayer.prepare();
    await this.avPlayer.play();
  }

  /**
   * 播放本地文件（fdSrc 方式）
   */
  async playFile(filePath: string): Promise<void> {
    if (!this.avPlayer) return;
    const file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
    const stat = fs.statSync(filePath);
    this.avPlayer.fdSrc = {
      fd: file.fd,
      offset: 0,
      length: stat.size,
    };
    if (this.surfaceId) {
      this.avPlayer.surfaceId = this.surfaceId;
    }
    await this.avPlayer.prepare();
    await this.avPlayer.play();
  }

  /**
   * 暂停/继续播放
   */
  togglePause(): void {
    if (!this.avPlayer) return;
    if (this.isPlaying) {
      this.avPlayer.pause();
    } else {
      this.avPlayer.play();
    }
  }

  /**
   * 精准跳转（单位：毫秒）
   * @param timeMs 目标时间点
   * @param mode 跳转模式：0=精准模式，1=最近关键帧，2=最近同步帧
   */
  async seek(timeMs: number, mode: media.SeekMode = media.SeekMode.SEEK_MODE_CLOSEST_SYNC): Promise<void> {
    if (!this.avPlayer) return;
    await this.avPlayer.seek(timeMs, mode);
  }

  /**
   * 设置播放倍速（0.125x ~ 4.0x）
   * 注意：直播场景不支持倍速
   */
  setPlaybackRate(rate: number): void {
    if (!this.avPlayer) return;
    if (rate < 0.125 || rate > 4.0) {
      console.error('[Player] 倍速超出范围');
      return;
    }
    this.avPlayer.setPlaybackRate(rate);
  }

  /**
   * HLS/DASH 码率切换
   * @param bitrate 目标码率（必须从 availableBitrates 中选择）
   */
  switchBitrate(bitrate: number): void {
    if (!this.avPlayer || this.availableBitrates.length === 0) {
      console.warn('[Player] 当前资源不支持码率切换');
      return;
    }
    this.avPlayer.setBitrate(bitrate);
  }

  /**
   * DASH 轨道切换（清晰度/语言/字幕）
   */
  async switchTrack(trackType: media.MediaType, targetWidth?: number, targetHeight?: number): Promise<void> {
    if (!this.avPlayer) return;

    this.avPlayer.getTrackDescription((error: BusinessError, arrList: Array<media.MediaDescription>) => {
      if (error || !arrList) {
        console.error(`[Player] 获取轨道失败: ${error?.message}`);
        return;
      }

      for (const desc of arrList) {
        const index = desc[media.MediaDescriptionKey.MD_KEY_TRACK_INDEX] as number;
        const type = desc[media.MediaDescriptionKey.MD_KEY_TRACK_TYPE] as media.MediaType;
        const width = desc[media.MediaDescriptionKey.MD_KEY_WIDTH] as number;
        const height = desc[media.MediaDescriptionKey.MD_KEY_HEIGHT] as number;

        if (type === trackType) {
          if (targetWidth && targetHeight) {
            if (width === targetWidth && height === targetHeight) {
              this.avPlayer!.selectTrack(index);
              return;
            }
          } else {
            this.avPlayer!.selectTrack(index);
            return;
          }
        }
      }
    });
  }

  /**
   * 释放播放器资源
   */
  async release(): Promise<void> {
    if (this.avPlayer) {
      await this.avPlayer.release();
      this.avPlayer = null;
    }
  }
}

3.3 流媒体协议支持

图3：流媒体协议能力矩阵与适用场景

协议	自适应码率	直播	点播	Seek	倍速	DRM	延迟	典型场景
HLS	✓	✓	✓	✓	✓	✓	中	CDN 直播/点播、苹果生态兼容
DASH	✓	✓	✓	✓	✓	✓	中	多语言字幕、多音轨、DRM 版权保护
HTTP	—	—	✓	✓	✓	—	低	短视频点播、本地文件、进度精准拖拽
HTTP-FLV	—	✓	—	—	—	—	极低	游戏直播推流、实时互动

---

四、流式数据源与缓存策略

图4：流媒体缓存策略：预加载与边播边缓存

4.1 策略一：setMediaSource 预加载（API 12+）

适用于短视频首帧优化场景，播放器在后台预下载流媒体数据并暂存于内存，用户点击播放时直接从内存读取，实现「秒开」体验。

/**
 * 使用 setMediaSource 实现预加载播放
 * @param url 流媒体地址
 * @param preferredBufferDuration 预缓冲时长（秒）
 */
async function playWithPreload(url: string, preferredBufferDuration: number = 3): Promise<void> {
  const avPlayer = await media.createAVPlayer();

  // 创建媒体源（支持自定义 HTTP 头域）
  const headers: Record<string, string> = {
    'User-Agent': 'HarmonyOS-Player/1.0',
    'Referer': 'https://example.com',
  };
  const mediaSource = media.createMediaSourceWithUrl(url, headers);

  // 配置播放策略
  const playbackStrategy: media.PlaybackStrategy = {
    preferredWidth: 1920,           // 优先选择 1080p 分辨率
    preferredHeight: 1080,
    preferredBufferDuration: preferredBufferDuration,  // 预缓冲 3 秒
    preferredHdr: false,            // 不强制 HDR
    preferredBufferDurationForPlaying: 1,  // 起播所需缓冲 1 秒
    thresholdForAutoQuickPlay: 5,   // 自动快速播放阈值
  };

  // 设置媒体源与策略（必须在 idle 状态下调用）
  await avPlayer.setMediaSource(mediaSource, playbackStrategy);

  // 注册事件并播放...
  avPlayer.on('stateChange', (state) => {
    if (state === 'prepared') {
      avPlayer.play();
    }
  });
}

4.2 策略二：dataSrc 边播边缓存

适用于长视频和直播场景，应用从远端下载数据的同时写入本地文件，播放器通过回调接口读取已下载部分，实现「边下载边播放边缓存」的三重能力。

import { fileIo as fs } from '@kit.CoreFileKit';

/**
 * 边播边缓存引擎
 * 实现：远端下载 → 本地文件写入 → 播放器回调读取
 */
class PlayWhileCachingEngine {
  private avPlayer: media.AVPlayer | null = null;
  private cacheFilePath: string = '';
  private downloadOffset: number = 0;
  private fileSize: number = -1;
  private isDownloading: boolean = false;

  /**
   * 启动边播边缓存
   * @param streamUrl 远端流媒体地址
   * @param cachePath 本地缓存文件路径
   */
  async start(streamUrl: string, cachePath: string): Promise<void> {
    this.cacheFilePath = cachePath;
    this.avPlayer = await media.createAVPlayer();

    // 创建本地缓存文件
    const cacheFile = fs.openSync(cachePath, fs.OpenMode.WRITE_ONLY | fs.OpenMode.CREATE);

    // 启动远端下载（示例使用 fetch，实际可用更高效的下载器）
    this.startDownload(streamUrl, cacheFile);

    // 配置 dataSrc
    const dataSrcDescriptor: media.AVDataSrcDescriptor = {
      fileSize: this.fileSize, // -1 表示未知大小（直播场景）
      callback: (outBuffer: ArrayBuffer, length: number, pos?: number): number => {
        return this.readCachedData(outBuffer, length, pos);
      }
    };

    this.avPlayer.dataSrc = dataSrcDescriptor;

    // 注册事件并准备播放
    this.avPlayer.on('stateChange', (state) => {
      if (state === 'prepared') {
        this.avPlayer?.play();
      }
    });

    await this.avPlayer.prepare();
  }

  /**
   * 从本地缓存文件读取数据供播放器消费
   */
  private readCachedData(outBuffer: ArrayBuffer, length: number, pos?: number): number {
    try {
      const cacheFile = fs.openSync(this.cacheFilePath, fs.OpenMode.READ_ONLY);
      const readPos = pos ?? this.downloadOffset;

      // 检查是否已下载到该位置
      const stat = fs.statSync(this.cacheFilePath);
      if (readPos >= stat.size) {
        fs.closeSync(cacheFile);
        return 0; // 数据尚未下载到，返回 0 表示等待
      }

      const actualLen = Math.min(length, stat.size - readPos);
      const buffer = new ArrayBuffer(actualLen);
      fs.read(cacheFile.fd, buffer, { offset: readPos, length: actualLen });
      fs.closeSync(cacheFile);

      const target = new Uint8Array(outBuffer);
      target.set(new Uint8Array(buffer));

      return actualLen;
    } catch (e) {
      console.error(`[Cache] 读取缓存失败: ${e}`);
      return -1;
    }
  }

  /**
   * 启动远端下载（简化示例）
   */
  private async startDownload(url: string, cacheFile: fs.File): Promise<void> {
    this.isDownloading = true;

    // 实际实现应使用分块下载或流式下载
    // 此处为伪代码示意
    const response = await fetch(url);
    const reader = response.body?.getReader();
    if (!reader) return;

    while (this.isDownloading) {
      const { done, value } = await reader.read();
      if (done) break;

      // 写入本地缓存文件
      fs.writeSync(cacheFile.fd, value.buffer);
      this.downloadOffset += value.length;
    }

    fs.closeSync(cacheFile);
    this.isDownloading = false;
  }

  /**
   * 停止播放与下载
   */
  async stop(): Promise<void> {
    this.isDownloading = false;
    await this.avPlayer?.stop();
    await this.avPlayer?.release();
  }
}

注意事项：使用 dataSrc 播放 MP4/M4A 格式时，必须保证 moov 字段（媒体信息）在 mdat 字段（媒体数据）之前，或者 moov 之前的字段小于 10MB，否则会导致解析失败无法播放。

---

五、实时音频流处理

对于 RTC 通话、语音对讲等实时场景，HarmonyOS 提供了音频采集与渲染的低延迟流处理能力：

import { audio } from '@kit.AudioKit';

/**
 * 实时音频流处理器
 * 实现：麦克风采集 → PCM 数据处理 → 网络传输 / 本地播放
 */
class RealtimeAudioStream {
  private audioCapturer: audio.AudioCapturer | null = null;
  private audioRenderer: audio.AudioRenderer | null = null;

  /**
   * 初始化音频采集器（麦克风输入）
   */
  async initCapturer(): Promise<void> {
    const capturerInfo: audio.AudioCapturerInfo = {
      source: audio.SourceType.SOURCE_TYPE_MIC,
      capturerFlags: 0,
    };

    const capturerOptions: audio.AudioStreamInfo = {
      samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
      channels: audio.AudioChannel.CHANNEL_2,
      sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
      encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW,
    };

    this.audioCapturer = await audio.createAudioCapturer(capturerInfo, capturerOptions);
  }

  /**
   * 开始采集并实时处理音频流
   * @param onAudioData 音频数据回调（PCM 格式）
   */
  async startCapture(onAudioData: (pcmData: ArrayBuffer) => void): Promise<void> {
    if (!this.audioCapturer) return;

    await this.audioCapturer.start();

    // 循环读取音频数据
    const bufferSize = 4096; // 每次读取 4KB
    while (this.audioCapturer.state === audio.AudioState.STATE_RUNNING) {
      const buffer = await this.audioCapturer.read(bufferSize, true);
      if (buffer.byteLength > 0) {
        onAudioData(buffer);
      }
    }
  }

  /**
   * 初始化音频渲染器（扬声器输出）
   */
  async initRenderer(): Promise<void> {
    const rendererInfo: audio.AudioRendererInfo = {
      usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION,
      rendererFlags: 0,
    };

    const rendererOptions: audio.AudioStreamInfo = {
      samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
      channels: audio.AudioChannel.CHANNEL_2,
      sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
      encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW,
    };

    this.audioRenderer = await audio.createAudioRenderer(rendererInfo, rendererOptions);
  }

  /**
   * 播放接收到的 PCM 音频流
   */
  async renderAudio(pcmData: ArrayBuffer): Promise<void> {
    if (!this.audioRenderer) return;

    if (this.audioRenderer.state !== audio.AudioState.STATE_RUNNING) {
      await this.audioRenderer.start();
    }

    await this.audioRenderer.write(pcmData);
  }

  /**
   * 释放资源
   */
  async release(): Promise<void> {
    await this.audioCapturer?.stop();
    await this.audioCapturer?.release();
    await this.audioRenderer?.stop();
    await this.audioRenderer?.release();
  }
}

---

六、性能优化与最佳实践

6.1 缓冲策略优化

场景	推荐策略	缓冲时长	说明
短视频（<60s）	setMediaSource 预加载	3~5s	首帧优先，内存缓存
长视频点播	dataSrc 边播边缓存	10~30s	磁盘缓存，支持断点续播
直播（HLS/FLV）	自适应缓冲	2~5s	低延迟优先，容忍少量卡顿
弱网环境	降级策略	动态调整	自动切换低码率，延长缓冲

6.2 常见问题与解决方案

问题	原因	解决方案
play() 无反应	未等待 prepared 状态	监听 stateChange，确认 prepared 后再调用 play()
durationUpdate 不触发	资源无效或未调用 prepare()	检查 URL 可达性、网络权限、格式兼容性
Seek 后画面卡顿	HLS 分片资源不支持精准定位	使用 SEEK_MODE_CLOSEST_SYNC 模式
多次播放报错	未释放旧实例	每次播放前调用 release() 或创建新实例
码率切换无效	资源非 HLS/DASH 或码率不在列表中	检查 availableBitrates 返回值长度
字幕不显示	未加载字幕文件	使用 addSubtitleFromFd() 加载 SRT 文件

6.3 权限声明

// module.json5
"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:internet_reason"
  },
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:microphone_reason"
  }
]

---

七、总结与展望

本文基于 HarmonyOS 6（API 23），系统梳理了媒体流处理的全链路技术方案。核心要点总结如下：

1. AVPlayer 状态机 是流媒体播放的核心，idle → initialized → prepared → playing 的标准流程必须严格遵守，所有事件监听必须在设置资源前完成注册；
2. 协议支持 方面，HLS/DASH 支持自适应码率、DRM 加密、多轨道切换，适合直播与点播；HTTP-FLV 适合超低延迟直播；HTTP 适合标准点播；
3. 缓存策略 方面，setMediaSource 预加载适合短视频首帧优化，dataSrc 边播边缓存适合长视频与直播，两者可根据场景灵活选择；
4. 高阶特性 包括 HLS 码率手动切换、DASH 音视频轨道选择、缓冲状态实时监控、倍速播放（0.125x~4.0x）等，满足复杂业务需求；
5. 实时音频流 通过 AudioCapturer 与 AudioRenderer 实现低延迟采集与播放，适用于 RTC、语音对讲等实时通信场景。

未来可探索的方向包括：结合 AI 网络预测算法实现智能预加载（预测用户下一步观看内容并提前缓存）、利用分布式软总线实现跨设备无缝流转（手机播放 → 智慧屏续播）、以及对接 QUIC 协议进一步提升弱网环境下的流媒体传输稳定性。

---

转载自：https://blog.csdn.net/u014727709/article/details/163645746
欢迎 👍点赞✍评论⭐收藏，欢迎指正