Settings reference
Tune every dash.js setting the Dodge module adds, with defaults and recommended production values.
Just want to use Dodge? See install. New to video fingerprinting? Start with learn.
Overview
Dodge settings live under settings.dodge and are applied through dash.js's normal settings API: player.updateSettings({ dodge: { ... } }). We strongly recommend reviewing every setting in context before going live.
List of settings
| Setting | Default | Meaning |
|---|---|---|
strictMode | 'representation' | What to do when content is not covered by an active defense. See below. |
scheduleWaitBase | 100 | Base wait (ms) between segment requests under random-walk scheduling. |
scheduleWaitRandom | 50 | Max additional random wait (ms) between requests. Uniform random sampling. |
maxIdLength | 32 | Expected representation ID length, used to normalize segment URL lengths. |
queryParam | 'padding' | Query parameter appended to segment URLs to equalize request length. |
paddingLengthBase | 0 | Base target request wire size in bytes (HTTP/1.1 request padding). |
paddingLengthRandom | 0 | Max additional random bytes per request. |
Strict mode levels
strictMode prevents accidental undefended playback. The levels trade safety for flexibility, from least to most restrictive:
| Level | Behavior |
|---|---|
false | Falls back to normal dash.js behavior on a per-representation basis. Use for testing only! Representations present in the embedded MPD but not covered by the extended manifest's streams array play undefended, with no warning at playback time. |
'representation' (default) | Blocks undefended representations when an extended manifest is active; plain DASH (no extended manifest) still plays normally. |
'manifest' | Everything 'representation' does, and also refuses to play sources that are not valid extended manifests (no vanilla MPDs). |
'max' | Everything 'manifest' does, and also rejects manifests with features that can easily bypass the defense: thumbnails, non-fragmented text tracks, and XLink references. |
Any value other than the four above is treated as 'max' and logged as an error. strictMode fails closed rather than silently accepting an unrecognized setting.
Safe integration guidance
If you haven't, see threat model & security to understand the importance of the following settings and for more information that will help you choose properly.
For most deployments, leave the scheduling settings (scheduleWaitBase, scheduleWaitRandom) at their defaults. If they are set too low, request storms may result, especially on slow connections. If set too high, user experience may be affected negatively. After changing this setting, run experiments to confirm your defenses still work.
Set maxIdLength to the maximum representation ID length among the videos you host. If set too low, request sizes will not be normalized correctly. There is no danger in overestimating the maximum length, but further increasing maxIdLength provides no additional protection. You should set queryParam to something that isn't used to transmit actual data in requests to your video server. The default is almost certainly fine in most scenarios.
We strongly recommend setting both paddingLengthBase and paddingLengthRandom. The latter is especially important if you're using HTTP/2 or above, or QUIC. Dodge's request size normalization only applies to URL lengths, and differences in the number of characters in HTTP headers (such as the Range header) can undermine defenses. Choose a value that's larger than the largest request you expect clients to send. You can estimate a good base size by taking the sum of the number of characters in the longest video segment URL you have and the maximum representation ID length, then adding a couple hundred bytes. A small value (between 16 and 64) is sufficient for the random component.
We also recommend changing strictMode. The Dodge browser extension's hardened profile sets strictMode: 'max', because a safe player should refuse to play anything that isn't verifiably defended. Content providers integrating the module into their own player can reasonably use 'representation' or 'manifest' if they control the manifest pipeline and are confident it always produces a full-coverage extended manifest. However, these levels are mostly useful if you want to fall back to vanilla DASH, for example during a transitional period when first deploying defenses. Prefer stricter levels.
Do not set strictMode: false in production. It can degrade protection: any representation the extended manifest doesn't cover plays through the undefended dash.js pipeline, with no defense and no error. It exists for testing purposes only.