• 音视频
• 前端

dash.js 通过一套集中维护在Settings.js中的配置对象，为播放器行为提供了高度可定制的能力。本文以官方 Settings 文档为核心，结合 Settings.js 源码与仓库内的真实示例（samples 与单元测试），系统讲解配置项的分层结构、updateSettings/getSettings/resetSettings的完整 API 用法，并逐类拆解 debug、ABR、buffer、live、DRM、CMCD 等核心配置组，帮助你掌握从“改一个日志开关”到“深度调优自适应码率”的完整实战能力。

配置体系概览：一切从 Settings.js 开始

dash.js 的所有配置都定义在 src/core/Settings.js 中。该文件通过 JSDoc@typedef PlayerSettings描述了完整配置 schema，并在文件内部的defaultSettings对象中给出了每一项的默认值（Settings.js 源码默认值）。

配置对象按命名空间分层组织，顶层包含三大块：

settings = { debug: { ... }, // 调试与日志相关 streaming: { ... }, // 流媒体播放相关（主体） errors: { ... } // 错误恢复相关 }

streaming内部又按功能域拆分为buffer、gaps、abr、delay、protection、text、cmcd、cmsd、utcSynchronization、liveCatchup、scheduling、capabilities等众多子命名空间。这种“路径即键名”的设计（例如streaming.abr.maxBitrate.video）使得配置项可以按点路径精确定位，也便于通过 URL 参数、UI 控件或脚本逐项覆盖。

一个实用的管理入口：仓库在 samples/dash-if-reference-player/app/js/SettingsController.js 中把 settings 映射成了可视化的开关面板，参考它可以看到各配置项在真实播放器中的可调范围与默认勾选状态。

三个核心 API：updateSettings / getSettings / resetSettings

官方文档给出的标准方式是：播放器初始化后，通过updateSettings方法修改设置。三个方法都在 MediaPlayer.js 中暴露：

官方文档给出的最简示例（修改日志级别）：

player.updateSettings({ debug: { logLevel: dashjs.Debug.LOG_LEVEL_WARNING } });

updateSettings 的深层语义：深合并，不是整体替换

从 Settings.js 的 update/mixinSettings 实现 可以看到两个关键行为：

1. 按路径深合并（deep merge）：updateSettings({a: x})与updateSettings({b: y})的先后调用，等价于一次updateSettings({a: x, b: y})——未传入的路径不会被重置。这就是文档所说“Anything left unspecified is not modified”。
2. 未知键名会告警：mixinSettings 在遍历新配置时，如果某个键在默认 schema 中不存在，会向控制台输出Settings parameter xxx is not supported，这能帮助你尽早发现拼写错误的配置路径。

另外值得注意：部分关键设置更新后会立即广播事件，驱动相关控制器实时响应。源码中的DISPATCH_KEY_MAP（Settings.js#L1196-L1214）把streaming.delay.liveDelay、streaming.liveCatchup.enabled、streaming.abr.rules.*.active、streaming.abr.maxBitrate/minBitrate等路径映射到对应事件，例如：

• 更新streaming.delay.liveDelay→ 触发SETTING_UPDATED_LIVE_DELAY，StreamController.js#L149-L150 监听后即时调整直播延迟；
• 更新streaming.abr.maxBitrate.video→ 触发SETTING_UPDATED_MAX_BITRATE，BolaRule.js#L86 监听后即时刷新码率上下限约束。

也就是说，热更新并不是简单地改一个对象，而是真正驱动运行时行为的实时变更。

一次调用多个配置组：来自官方示例的完整写法

manual-load-with-custom-settings.html 是官方“custom settings”示例页的完整代码，展示了初始化后一次配置多个命名空间：

player = dashjs.MediaPlayer().create(); player.initialize(); /* initialize the MediaPlayer instance */ player.updateSettings({ 'debug': { 'logLevel': dashjs.Debug.LOG_LEVEL_NONE /* turns off console logging */ }, 'streaming': { 'scheduling': { 'scheduleWhilePaused': false, /* stops the player from loading segments while paused */ }, 'buffer': { 'fastSwitchEnabled': true /* enables buffer replacement when switching bitrates for faster switching */ } } }); player.setAutoPlay(false); player.attachView(video); player.attachSource(url);

这套写法在仓库的数十个示例页中保持一致，适合作为接入自定义配置的通用模板。

Debug 设置：精确控制日志输出

debug是最高频的调试入口，包含两个字段（默认值见 Settings.js#L1221-L1224）：

logLevel的可选常量定义在 src/core/Debug.js，从小到大为：

• LOG_LEVEL_NONE（0）：控制台不输出任何消息
• LOG_LEVEL_FATAL（1）：仅致命错误（导致播放完全失败）
• LOG_LEVEL_ERROR（2）：错误消息
• LOG_LEVEL_WARNING（3）：警告消息
• LOG_LEVEL_INFO（4）：信息消息
• LOG_LEVEL_DEBUG（5）：调试消息（最高级别，输出全部）

从 Debug.js doLog 实现 可以确认：当settings.get().debug.logLevel >= level时才写入控制台，因此级别是累积的——例如设为LOG_LEVEL_WARNING时，warning、error、fatal 都会输出。示例 listening-to-SCTE-EMSG-events.html 中就用player.updateSettings({ 'debug': { 'logLevel': dashjs.Debug.LOG_LEVEL_DEBUG }})开启了完整日志来跟踪事件。

Streaming 设置：播放器行为调优的主体

streaming下涵盖十余个功能子域，本节挑选实战中最常调整的几类展开；未展开项（如metrics、timeShiftBuffer、events、capabilities等）的完整默认值均可直接查阅 Settings.js 默认值。

ABR 自适应码率设置

streaming.abr是自适应码率的核心配置组（默认值见 Settings.js#L1419-L1519），包含规则开关、吞吐量计算、码率上下限、初始码率与自动切换开关。

1. 码率上下限与初始码率（单位 kbps）

player.updateSettings({ streaming: { abr: { maxBitrate: { audio: -1, video: 5000 }, // -1 表示不设上限 minBitrate: { audio: -1, video: 2000 }, // -1 表示不设下限 initialBitrate: { audio: -1, video: 800 },// -1 表示由播放器自行决定 autoSwitchBitrate: { audio: true, video: false } } } });

官方示例 max-min-bitrate.html 的说明指出：将视频上限设为 5 Mbit/s 后，即使清单里有 8 Mbit/s 的 Representation，播放器也绝不会选超过 4 Mbit/s 的档位。从 AbrController.js#L372-L379 可以看到这些约束在 Representation 筛选阶段的实现：representationBitrate > maxBitrate或representationBitrate < minBitrate的档位会被直接排除；AbrController.js#L712 则读取initialBitrate作为启动码率。autoSwitchBitrate.video: false可将视频锁定在初始码率（见 initial-bitrate.html）。

2. ABR 规则开关

dash.js 支持通过rules逐条启用/禁用内部 ABR 规则。仓库 abr.html 示例展示了“启用吞吐量规则、关闭 BOLA 等其他规则”的配置：

player.updateSettings({ streaming: { abr: { rules: { throughputRule: { active: true }, bolaRule: { active: false }, insufficientBufferRule: { active: true }, switchHistoryRule: { active: false }, droppedFramesRule: { active: false }, abandonRequestsRule: { active: false } } } } });

注意示例页的提示：若同时启用throughputRule与bolaRule，dash.js 会进入动态模式（dynamic mode）——启动阶段先用 ThroughputRule，达到 buffer target 后切换为 BOLA。l2ARule与loLPRule是面向低延迟流的规则，官方建议作为独立规则使用（启用时应停用其他规则）。各规则还有专属参数（如insufficientBufferRule.parameters.throughputSafetyFactor、abandonRequestsRule.parameters.abandonDurationMultiplier等），默认值均可从 Settings.js 的 AbrRules JSDoc 查证。

3. 吞吐量计算与码率限制

streaming.abr.throughput控制吞吐量估计算法，关键参数包括：

• averageCalculationMode：默认Constants.THROUGHPUT_CALCULATION_MODES.EWMA（指数加权移动平均），可切换为算术/调和平均；
• bandwidthSafetyFactor：默认0.9，ABR 规则会将测得吞吐量乘以该安全系数，取值应在 0~1 之间，越小越不容易 rebuffer（但画质也更保守）；
• useResourceTimingApi：默认true，利用 ResourceTiming API 获取下载时间与字节数；
• sampleSettings/ewma：分别控制滑窗样本数与 EWMA 的半衰期等计算参数。

此外，streaming.abr.limitBitrateByPortal（默认false）设为true时，会用视频播放窗口尺寸限制可选最高分辨率，usePixelRatioInLimitBitrateByPortal可在此基础上计入设备像素比。

Buffer 缓冲设置

streaming.buffer控制缓冲目标与修剪策略（默认值见 Settings.js#L1282-L1306）：

官方示例 buffer-target.html 演示了典型调优：

player.updateSettings({ streaming: { buffer: { bufferTimeAtTopQuality: 30, bufferTimeAtTopQualityLongForm: 60, bufferTimeDefault: 12, longFormContentDurationThreshold: 600, } } });

从源码文档看，fastSwitchEnabled启用后，ABR 升档时会尽量在“当前时间 + 1.5 × 分片时长”内渲染更高画质；降档时仍把低画质追加到缓冲末尾以尽量维持高画质；当缓冲低于一个分片时长或处于 Abandonment 状态时则退化为尾部追加。

直播相关：delay 与 liveCatchup

直播延迟（streaming.delay）：核心参数为liveDelayFragmentCount（默认NaN，用分片数乘分片时长计算延迟秒数）与liveDelay（默认NaN，直接指定延迟秒数；一旦设置，优先于liveDelayFragmentCount和清单信息）。useSuggestedPresentationDelay（默认true）表示优先遵循清单中的SuggestedPresentationDelay属性。降低这些值会降低延迟，但也可能削弱稳定建缓冲的能力。

直播追赶（streaming.liveCatchup）：低延迟直播中当实测延迟偏离目标延迟时，通过调整播放速率或 seek 回到直播边缘。常用参数：

• maxDrift（默认NaN）：允许的最大延迟偏差（秒），超过后执行 seek 回直播边缘；设为-1禁用 seek 修复；
• playbackRate.min/max：追赶时允许的播放速率变化百分比（min 有效范围 -0.5~0，max 有效范围 0~1），设为NaN关闭追赶；
• mode：追赶模式，取liveCatchupModeDefault、liveCatchupModeLOLP或liveCatchupModeStep。

注意：追赶机制默认只对低延迟直播生效，enabled（默认null）可用来为非低延迟流开启。

字幕与文本（streaming.text）

• defaultEnabled（默认true）：是否默认渲染字幕；
• dispatchForManualRendering（默认false）：设为true时改派发CueEnter/CueExit事件而非渲染字幕，便于自实现渲染；
• imsc.displayForcedOnlyMode：IMSC 仅显示itts:forcedDisplay="true"的强制字幕；
• webvtt.customRenderingEnabled：开启 WebVTT 自定义渲染（需 contrib/videojs-vtt.js/vtt.js 外部库支持）。

示例 multi-track-captions.html 演示了运行时动态切换streaming.text.defaultEnabled的用法。

Gaps 与调度（streaming.gaps / scheduling）

streaming.gaps控制缓冲空洞处理：jumpGaps/jumpLargeGaps（是否跳过小/大空洞）、smallGapLimit（默认1.5秒，判定小空洞的阈值）、threshold（默认0.3秒，触发跳洞的判定阈值）、enableStallFix（在已缓冲区间内卡住时按stallSeek位移触发 seek）。

streaming.scheduling控制分片调度节奏：defaultTimeout（默认500ms，相邻两次调度尝试的间隔）、scheduleWhilePaused（默认true，暂停时是否继续后台下载分片，示例中关闭它以节省带宽）。

请求超时与重试（streaming 顶层）

streaming.fragmentRequestTimeout（默认20000ms）、manifestRequestTimeout（默认10000ms）分别控制媒体分片与清单的超时；retryAttempts/retryIntervals按请求类型（MPD、媒体分片、Init 分片、License 等）分别定义重试次数与重试间隔（毫秒），低延迟模式下retryIntervals会除以lowLatencyReductionFactor（默认 10）、retryAttempts会乘以lowLatencyMultiplyFactor（默认 5）。

DRM（streaming.protection）

• keepProtectionMediaKeys（默认false）：是否在播放器生命周期内保留 ProtectionController 与 MediaKeys/MediaKeySessions；
• keepProtectionMediaKeysMaximumOpenSessions（默认-1）：超出上限时关闭最旧会话，-1表示不限；
• ignoreEmeEncryptedEvent：忽略 EME 的encrypted/needkey事件；
• detectPlayreadyMessageFormat：使用 PlayReady CDM 的原始未包装消息；
• ignoreKeyStatuses：忽略密钥状态，无论密钥是否可用都尝试播放对应轨道。

CMCD / CMSD 与增强层

• streaming.cmcd.enabled（默认false）开启 Common Media Client Data 上报；mode可选query（查询参数）或header（HTTP 头），enabledKeys控制上报哪些 CMCD 键，includeInRequests控制哪些请求携带参数（默认['segment', 'mpd']）。示例见 cmcd.html 与 cmcd-v2.html。
• streaming.cmsd.enabled（默认false）开启 CMSD 响应头解析；abr.applyMb可将 CMSD 建议码率引入 ABR 逻辑。
• streaming.enhancement.enabled（默认false）开启可扩展增强层播放（如 LCEVC），codecs默认['lvc1']。

Errors 设置：解码错误自动恢复

errors.recoverAttempts.mediaErrorDecode（默认5）定义了针对特定媒体错误的恢复尝试次数。从 Settings.js JSDoc 可以看到机制：发生解码错误时，播放器会重置 MSE 并将导致解码错误的分片加入黑名单跳过，产生的空洞交由 GapController 处理。

完整设置对象与快速参考

如果需要查看或验证当前生效的完整配置，可直接调用：

const settings = player.getSettings(); console.log(settings.streaming.abr.maxBitrate.video);

完整的默认设置对象（约 160 个配置项）可直接阅读 Settings.js defaultSettings；需要恢复出厂状态时调用player.resetSettings()。仓库单元测试 refplayer.SettingsController.js 通过player.updateSettings(config)后断言player.getSettings()的方式验证了数十个配置路径（如streaming.buffer.fastSwitchEnabled、streaming.gaps.jumpGaps、streaming.abr.rules.l2ARule.active、streaming.delay.liveDelay等），既可作为配置路径正确性的对照表，也印证了 updateSettings 与 getSettings 的契约。

总结

dash.js 的配置体系遵循“分层命名空间 + 深合并更新 + 事件驱动热生效”的设计：以player.updateSettings()为唯一入口，按点路径增量覆盖；以Settings.js的defaultSettings为 schema 权威来源，未知路径会得到控制台告警；以DISPATCH_KEY_MAP为桥梁，关键配置（直播延迟、码率上下限、ABR 规则开关等）在更新后即时通知对应控制器与规则生效。无论是接入时关闭日志、限制码率区间、定制 ABR 规则组合，还是为低延迟直播调优延迟与追赶参数，都可以在这一套配置体系内完成，而官方示例页与单元测试则提供了可直接复用的参考实现。

• 音视频
• 前端