Class Core<TStream>

constructor

• new Core<TStream extends Stream = Stream>(
      config?: Partial<CoreConfig>,
  ): Core<TStream>

  Constructs a new Core instance with optional initial configuration.

  Type Parameters

  • TStream extends Stream = Stream

  Parameters

  • Optionalconfig: Partial<CoreConfig>

    Optional partial configuration to override default settings.

  Returns Core<TStream>

  Example

  // Create a Core instance with custom configuration for HTTP and P2P downloads.
  const core = new Core({
    simultaneousHttpDownloads: 5,
    simultaneousP2PDownloads: 5,
    httpErrorRetries: 5,
    p2pErrorRetries: 5
  });
  Copy

  Example

  // Create a Core instance using the default configuration.
  const core = new Core();
  Copy

Static ReadonlyDEFAULT_COMMON_CORE_CONFIG

Static ReadonlyDEFAULT_STREAM_CONFIG

getConfig

• getConfig(): DefinedCoreConfig

  Retrieves the current configuration for the core instance, ensuring immutability.

  Returns DefinedCoreConfig

  A deep readonly version of the core configuration.

applyDynamicConfig

• applyDynamicConfig(dynamicConfig: DynamicCoreConfig): void

  Applies a set of dynamic configuration updates to the core, merging with the existing configuration.

  Parameters

  • dynamicConfig: DynamicCoreConfig

    A set of configuration changes to apply.

  Returns void

  Example

  // Example of dynamically updating the download time windows and timeout settings.
  const dynamicConfig = {
    httpDownloadTimeWindow: 60,  // Set HTTP download time window to 60 seconds
    p2pDownloadTimeWindow: 60,   // Set P2P download time window to 60 seconds
    httpNotReceivingBytesTimeoutMs: 1500,  // Set HTTP timeout to 1500 milliseconds
    p2pNotReceivingBytesTimeoutMs: 1500    // Set P2P timeout to 1500 milliseconds
  };
  core.applyDynamicConfig(dynamicConfig);
  Copy

addEventListener

• addEventListener<K extends keyof CoreEventMap>(
      eventName: K,
      listener: CoreEventMap[K],
  ): void

  Adds an event listener for the specified event type on the core event target.

  Type Parameters

  • K extends keyof CoreEventMap

  Parameters

  • eventName: K

    The name of the event to listen for.

  • listener: CoreEventMap[K]

    The callback function to invoke when the event is fired.

  Returns void

removeEventListener

• removeEventListener<K extends keyof CoreEventMap>(
      eventName: K,
      listener: CoreEventMap[K],
  ): void

  Removes an event listener for the specified event type on the core event target.

  Type Parameters

  • K extends keyof CoreEventMap

  Parameters

  • eventName: K

    The name of the event to listen for.

  • listener: CoreEventMap[K]

    The callback function to be removed.

  Returns void

setManifestResponseUrl

• setManifestResponseUrl(url: string): void

  Sets the response URL for the manifest, stripping any query parameters.

  Parameters

  • url: string

    The full URL to the manifest response.

  Returns void

hasSegment

• hasSegment(segmentRuntimeId: string): boolean

  Checks if a segment is already stored within the core.

  Parameters

  • segmentRuntimeId: string

    The runtime identifier of the segment to check.

  Returns boolean

  true if the segment is present, otherwise false.

getStream

• getStream(streamRuntimeId: string): TStream | undefined

  Retrieves a specific stream by its runtime identifier, if it exists.

  Parameters

  • streamRuntimeId: string

    The runtime identifier of the stream to retrieve.

  Returns TStream | undefined

  A detached snapshot of the registered stream with its computed identity, or undefined if not found. The identity fields never change after registration, so the snapshot stays accurate for the stream's lifetime.

getStreamSegmentRuntimeIds

• getStreamSegmentRuntimeIds(
      streamRuntimeId: string,
  ): ReadonlySet<string> | undefined

  Retrieves the runtime identifiers of the segments currently registered for a stream. Player integrations use this to diff a refreshed manifest against the core's registry before calling updateStream.

  Parameters

  • streamRuntimeId: string

    The runtime identifier of the stream.

  Returns ReadonlySet<string> | undefined

  A snapshot set of the registered segment runtime IDs, or undefined if the stream is not registered.

getStreams

• getStreams(): TStream[]

  Retrieves all currently registered streams with their computed identities, including the infohashes announced to trackers. Unlike the onStreamAdded event, this reflects the full set at any moment, so late subscribers can catch up on streams registered before they attached.

  Returns TStream[]

  Detached snapshots of the registered streams, in registration order.

addStreamIfNoneExists

• addStreamIfNoneExists(stream: StreamRegistration<TStream>): void

  Ensures a stream exists in the map; adds it if it does not.

  Computes the stream's identity (swarmId, identityHash, streamSwarmId, infoHash) exactly once at registration and freezes it on the stream. Requires the swarm ID to be resolvable: either a swarmId is configured or setManifestResponseUrl() has been called.

  Never throws: a stream that fails to register (unresolvable swarm ID, or an invalid or colliding custom stream swarm ID) stays unknown to the core — its segments load through the player's default path without P2P — and the failure is reported via the onStreamRegistrationError event.

  Parameters

  • stream: StreamRegistration<TStream>

    The stream to potentially add to the map.

  Returns void

updateStream

• updateStream(
      streamRuntimeId: string,
      addSegments?: Iterable<Segment, any, any>,
      removeSegmentIds?: Iterable<string, any, any>,
  ): void

  Updates the segments associated with a specific stream.

  Parameters

  • streamRuntimeId: string

    The runtime identifier of the stream to update.

  • OptionaladdSegments: Iterable<Segment, any, any>

    Optional segments to add to the stream.

  • OptionalremoveSegmentIds: Iterable<string, any, any>

    Optional segment IDs to remove from the stream.

  Returns void

loadSegment

• loadSegment(segmentRuntimeId: string, callbacks: EngineCallbacks): Promise<void>

  Loads a segment given its runtime identifier and invokes the provided callbacks during the process. Initializes segment storage if it has not been initialized yet.

  Parameters

  • segmentRuntimeId: string

    The runtime identifier of the segment to load.

  • callbacks: EngineCallbacks

    The callbacks to be invoked during segment loading.

  Returns Promise<void>

  Throws

  • Throws if the segment is not registered in any stream.

abortSegmentLoading

• abortSegmentLoading(segmentRuntimeId: string): void

  Aborts the loading of a segment specified by its runtime identifier.

  Parameters

  • segmentRuntimeId: string

    The runtime identifier of the segment whose loading is to be aborted.

  Returns void

updatePlayback

• updatePlayback(position: number, rate: number): void

  Updates the playback parameters while play head moves, specifically position and playback rate, for stream loaders.

  Parameters

  • position: number

    The new position in the stream, in seconds.

  • rate: number

    The new playback rate.

  Returns void

setActiveLevelBitrate

• setActiveLevelBitrate(bitrate: number): void

  Sets the active level bitrate, used for adjusting quality levels in adaptive streaming. Notifies the stream loaders if a change occurs.

  Parameters

  • bitrate: number

    The new bitrate to set as active.

  Returns void

setIsLive

• setIsLive(isLive: boolean): void

  Updates the 'isLive' status of the stream

  Parameters

  • isLive: boolean

    Boolean indicating whether the stream is live.

  Returns void

isSegmentLoadable

• isSegmentLoadable(segmentRuntimeId: string): boolean

  Identify if a segment is loadable by the P2P core based on the segment's stream type and configuration.

  Parameters

  • segmentRuntimeId: string

    Segment runtime identifier to check.

  Returns boolean

  true if the segment is loadable by the P2P core, otherwise false.

destroy

• destroy(): void

  Cleans up resources used by the Core instance, including destroying any active stream loaders and clearing stored segments.

  Event listeners deliberately survive: the player integrations reuse one Core instance across media sources, destroying it between loads, and subscriptions (e.g. onStreamAdded, onPeerConnect) are expected to keep working after the next source loads. Use removeEventListener to unsubscribe explicitly.

  Returns void