PlayerConfig¶

createDefaultConfig builds a complete PlayerConfig from a source. Only source is required in the overrides; required sub-configurations are filled with known defaults.

import { createDefaultConfig } from "@ngxsp/core";

export const config = createDefaultConfig({
  source: {
    type: "url",
    url: "https://cdn.example.com/trailer.mp4",
    contentId: "trailer-2026"
  }
});

Documented Defaults¶

Block	Default	Explanation	Avoid
`progress`	`{ mode: "local", intervalSec: 5 }`	Local progress saving by default.	Choosing `server` or `hybrid` without an endpoint or HTTP port.
`ui`	`{ ratios: ["16:9"], defaultRatio: "16:9", keyboardShortcuts: true }`	Skin, ratios, titles, shortcuts, chapters, thumbnails, skip segments, next episode.	Putting heavy business data in `ui`.
`resilience`	`{ retries: 2, backoffMs: { min: 300, max: 1500 } }`	Baseline recovery after transient errors.	Raising retries on DRM/live without telemetry.
`subtitles`	`{ enabled: false, providers: ["local"] }`	Subtitle search and loading.	Enabling an internet provider without API key, cache, quotas, and legal frame.
`metadata`	`{ enabled: false, providers: ["local"], localSidecar: false }`	Catalog or sidecar enrichment.	Enabling an external provider without cache or secrets management.
`ads`	`{ enabled: false, mode: "csai" }`	Advertising strategy: CSAI, SSAI, or mixed.	Enabling ads without providerConfig and content rights.

Advanced Fields¶

Field	Meaning	Use when
`profile`	Global `default`, `tv`, `mobile`, or `low-latency` profile.	An application targets a dominant playback context.
`drm`	Top-level DRM that overrides or completes `source.drm`.	Rights are separate from the catalog source.
`playlist` / `playlistStartIndex`	List of `PlayerSource` items and start index.	Audio queue, continuous playback, courses, video gallery.
`autoNext`	Automatically moves to the next item.	Series, playlists, chaptered courses.
`series`	Episode mode with title, current index, preload, and UI overrides.	TV series, training, episodic podcasts.
`offline`	Offline intent through `enabled` and `key`.	Explicitly downloadable content.
`remoteConfig`	Loads remote JSON with TTL, merge mode, and allow-list.	Adjust resilience, ads, UI, subtitles, or metadata without rebuild.

createDefaultConfig merge

Merges are shallow except for resilience.backoffMs, which keeps default min and max when only one field is provided. Do not assume a deep merge for every nested object.