【HarmonyOS 7新能力｜041】弱网直播优化工程封装：把接入逻辑放进可维护的分层结构

直播在弱网环境中的难点不是"检测到网速慢就降码率"，而是网络、解码、缓冲和业务互动同时变化。策略过于敏感会频繁切换清晰度，策略反应太慢又会先发生卡顿。可靠的质量治理需要连续感知、稳定决策、可撤销执行和效果反馈，形成闭环，而不是在播放器回调里堆叠条件判断。

说明：本文出现的 LiveQualityPort、NetworkEstimator 等均为教学抽象，不是 HarmonyOS SDK 的真实接口。具体媒体能力、网络指标、编码参数和支持设备，请以当前官方文档、目标 SDK 与真实直播服务为准。

1. 质量目标必须是多维的

画质、流畅度、延迟和稳定性无法同时无限提高。赛事直播偏向低延迟，教学直播可能更重视清晰度，连麦还要约束上行。策略先定义场景目标，再对不同指标设置可接受范围。

ts 复制代码

export interface LiveQualityGoal {
  scene: 'watch' | 'interactive' | 'cohost'
  priority: readonly ('smoothness' | 'latency' | 'clarity')[]
  maxBufferMs: number
  maxRecoveryMs: number
}

这些值来自产品目标与实测，不应散落在页面。编排层根据场景读取对应目标。

2. 四层架构分离感知和执行

直播页面只展示状态和用户选择；质量编排层聚合指标、执行规则并维护状态机；媒体网络适配层封装播放器、编码器与链路探测；指标与状态仓库保存短期窗口、策略版本和切换结果。

ts 复制代码

export interface LiveQualityPort {
  readPlaybackSample(): Promise<PlaybackSample>
  applyProfile(profile: MediaProfile): Promise<ApplyResult>
}

export interface QualityStateStore {
  append(sample: QualitySample): Promise<void>
  latestDecision(sessionId: string): Promise<QualityDecision | undefined>
}

页面不能直接改码率，底层回调也不能直接弹提示。所有变化经过同一决策入口。

3. 采集最少且有解释力的指标

可用指标包括吞吐趋势、往返时延、丢包、抖动、缓冲长度、解码耗时和卡顿事件。不要依赖单一瞬时带宽，也不要为了"全面"高频采集无关设备数据。

ts 复制代码

export interface QualitySample {
  sessionId: string
  at: number
  throughputKbps?: number
  rttMs?: number
  lossRate?: number
  bufferMs: number
  droppedFrames: number
  stalled: boolean
}

缺失指标保留为未知，不用零代替。零可能被误解为极差网络，触发错误降级。

4. 用时间窗口抵抗瞬时抖动

网络指标天然有噪声。评估器在滑动窗口中计算趋势和稳定性，同时给最近样本更高权重。窗口太短会抖动，太长会迟钝，应按直播类型配置。

ts 复制代码

export interface NetworkEstimate {
  level: 'good' | 'limited' | 'poor' | 'unknown'
  trend: 'improving' | 'stable' | 'degrading'
  confidence: number
  observedAt: number
}

function weightedAverage(values: number[]): number {
  const weights = values.map((_, index) => index + 1)
  return values.reduce((sum, value, index) => sum + value * weights[index], 0) /
    weights.reduce((sum, value) => sum + value, 0)
}

评估结果表达置信度，样本不足时不贸然切换。

5. 弱网直播质量闭环

闭环依次完成指标采集、网络评估、策略决策、参数应用、体验反馈和策略校正。卡顿或断流进入异常旁路，恢复后逐步回升，不瞬间跳回最高质量。

ts 复制代码

export type QualityAction =
  | { kind: 'keep' }
  | { kind: 'downgrade'; target: MediaProfile; reason: string }
  | { kind: 'upgrade'; target: MediaProfile; reason: string }
  | { kind: 'recover'; mode: 'rebuffer' | 'reconnect' }

策略输出动作而非直接调用播放器，便于在执行前再次校验当前状态。

6. 迟滞控制避免质量来回跳

降级可以较快，升级应更谨慎。为相邻档位设置不同进入、退出阈值，并要求条件持续一定时间。每次切换后设置冷却窗口，除非发生严重卡顿。

ts 复制代码

export interface HysteresisPolicy {
  degradeAfterMs: number
  upgradeAfterMs: number
  switchCooldownMs: number
  emergencyBufferMs: number
}

function mayUpgrade(state: QualityState, now: number, policy: HysteresisPolicy): boolean {
  return state.goodSince !== undefined &&
    now - state.goodSince >= policy.upgradeAfterMs &&
    now - state.lastSwitchAt >= policy.switchCooldownMs
}

迟滞规则放在纯函数中，通过时间轴测试覆盖边界。

7. 质量档位是成组参数

一次调整可能涉及分辨率、码率、帧率、缓冲目标和编码策略。把它们封装为经过验证的档位，避免运行时产生不兼容组合。

ts 复制代码

export interface MediaProfile {
  id: string
  bitrateKbps: number
  width: number
  height: number
  frameRate: number
  targetBufferMs: number
}

档位需与服务端转码、播放器能力和设备性能一致。示例字段不代表推荐值，生产参数必须联调验证。

8. 切换操作必须幂等可回滚

网络回调可能重复触发，执行器以 sessionId + decisionRevision 去重。参数应用成功后再更新确认状态；失败则保留原档位或进入安全降级。

ts 复制代码

export interface QualityDecision {
  revision: number
  sessionId: string
  desiredProfileId: string
  reasonCode: string
  decidedAt: number
}

async function applyOnce(decision: QualityDecision): Promise<void> {
  if (decision.revision <= state.confirmedRevision) return
  const result = await adapter.applyProfile(profileOf(decision.desiredProfileId))
  if (result.ok) state.confirm(decision)
  else state.recordFailure(decision, result.code)
}

这样"想切换"和"已经生效"不会混为一谈。

9. 卡顿与断流采用不同恢复路径

短时卡顿可先扩大缓冲或降档；持续无数据需要检查连接并重建播放会话；服务端拒绝或鉴权过期则停止盲目重试。恢复策略按错误类别决定。

ts 复制代码

export type RecoveryPlan =
  | { action: 'rebuffer'; timeoutMs: number }
  | { action: 'reconnect'; delayMs: number }
  | { action: 'refreshAuth' }
  | { action: 'stop'; userMessageKey: string }

恢复过程中保留清晰状态提示，用户退出立即取消。后台限制必须遵循平台规范。

10. 网络恢复后逐级回升

网络从差转好时，直接升到最高档会形成新一轮缓存压力。编排器一次只提升一个档位，观察稳定窗口后再继续，并尊重用户手动选择的上限。

ts 复制代码

function nextUpgrade(current: MediaProfile, catalog: MediaProfile[]): MediaProfile {
  const index = catalog.findIndex(item => item.id === current.id)
  return catalog[Math.min(index + 1, catalog.length - 1)]
}

用户锁定省流或特定清晰度时，自动策略不能越过其偏好。

11. 可观测性关注体验结果

记录策略前后缓冲、卡顿、档位、切换原因和实际应用结果。仅统计"降级次数"没有意义，应观察卡顿是否减少、恢复是否变快以及是否产生频繁切换。

ts 复制代码

export interface QualityTrace {
  sessionId: string
  revision: number
  fromProfile: string
  toProfile: string
  reasonCode: string
  applied: boolean
  observedStallAfterMs?: number
}

指标不包含直播内容、聊天文本和用户身份原文，采样与上报遵循隐私规则。

12. 验收清单与总结

测试使用可重复网络条件覆盖渐进变差、瞬时抖动、长时弱网、断流恢复和逐步转好。验证未知指标不会误判、档位不高频振荡、切换失败可回滚、用户退出能取消、网络恢复不会激进升级。最终在真实设备和发布构建中观察长时间播放、功耗与端到端体验。

弱网直播治理的关键不是某个神奇参数，而是稳定闭环：多维采样形成趋势判断，迟滞策略输出有限动作，执行器确认实际生效，体验结果再校正策略。通过分层和状态机约束变化，直播才能在复杂网络中保持可控、可恢复、可验证。