@amazon-devices/kepler-player-server 2.2.3

package/dist/turbo-modules/IPlayerServer.d.ts

@@ -0,0 +1,393 @@
+import { IPlayerServerHandler } from './PlayerServerHandler';
+import { IPlayerSessionError, IPlayerSessionStatus, IPlayerSessionId, ITimeRange, ITrackInfo } from './PlayerServerDataTypes/PlayerServerDataTypes';
+/**
+ * Represent Kepler player server operations.
+ * This interface provides methods for managing Kepler player server handlers and updating
+ * Kepler player session status.
+ *
+ * For runtime errors, apps are expected to reject the promise with `Error` object, and if
+ * possible send the error code and message received from media player using `IPlayerSessionError`
+ */
+export interface IPlayerServer {
+    /**
+     * Assigns a handler to process requests for Kepler player actions associated with the given component ID.
+     *
+     * @details Assigning a handler is essential for processing Kepler player requests and
+     * implementing custom Kepler player logic.
+     * This call allows one handler per component. The active handler is the one set by the last invocation to setHandler.
+     *
+     * @example
+     * ```typescript
+     * import { PackageInfo, PackageManager } from '@amazon-devices/package-manager-lib';
+     *
+     * const parseClientPackageManifest = async (): Promise<string> => {
+     *   try {
+     *     const selfPackageInfo: PackageInfo = await PackageManager.getSelfPackageInfo();
+     *     for (const component of selfPackageInfo.components) {
+     *       if(component.type === 'service') {
+     *         return component.id;
+     *       }
+     *     }
+     *     return '';
+     *   } catch (error) {
+     *     console.warn(`Interactive: Unable to retrieve info from Package manager, ${error.message}`);
+     *     return '';
+     *   }
+     * }
+     *
+     * let serviceComponentId: string | undefined = await this.parseClientPackageManifest();
+     * playerServerRef.current?.setHandler(handler, serviceComponentId);
+     * ```
+     */
+    setHandler: (
+    /**
+     * An instance of the `IPlayerServerHandler` interface to invoke
+     * when Kepler player requests arrive.
+     */
+    handler: IPlayerServerHandler, 
+    /**
+     * An id of the `service component` interface representing the component for which the handler is being set.
+     * This MUST match the service ID declared in the application manifest.
+     */
+    componentId: string) => void;
+    /**
+     * Notifies interested clients about Kepler player buffered ranges.
+     *
+     * @details Updating the server session playback buffered ranges is crucial for reflecting changes in media playback
+     * status, currently selected media, and other related information.
+     * ```typescript
+     * let sessionId1: IPlayerSessionId = { id: 1 };
+     * let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 1.
+     * let sessionId2: IPlayerSessionId = { id: 2 };
+     * let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 2.
+     *
+     * private getBufferedRanges(mediaPlayer: HtmlMediaElement | VideoPlayer | AudioPlayer): Array<ITimeRange> {
+     *   const result: Array<ITimeRange> = [];
+     *   const bufferedTimeRanges = mediaPlayer.buffered;
+     *   for (let i = 0; i < bufferedTimeRanges.length; ++i) {
+     *     result.push({
+     *       start: bufferedTimeRanges.start(i),
+     *       end: bufferedTimeRanges.end(i)
+     *     });
+     *   }
+     *   return result;
+     * }
+     *
+     * playerServerRef.current?.updateBufferedRanges(getBufferedRanges(mediaPlayer1), sessionId1);
+     * playerServerRef.current?.updateBufferedRanges(getBufferedRanges(mediaPlayer2), sessionId2);
+     * ```
+     *
+     * @returns Promise that resolves when the update is complete.
+     */
+    updateBufferedRanges: (
+    /**
+     * Updated buffered ranges for player session.
+     */
+    bufferedRanges: Array<ITimeRange>, 
+    /**
+     * session id for which the buffered ranges are being updated.
+     */
+    sessionId?: IPlayerSessionId) => Promise<void>;
+    /**
+     * Notifies interested clients about Kepler player session status updates.
+     *
+     * @details Updating the kepler player server session status is crucial for reflecting changes in media playback
+     * status, currently selected media, and other related information.
+     * For instance, apps will register media related EventListener on `AudioPlayer` or `VideoPlayer`
+     * (https://html.spec.whatwg.org/#event-handlers-on-elements,-document-objects,-and-window-objects)
+     * and then update the parameters of `IPlayerSessionStatus` accordingly and call
+     * updateStatus.
+     * When applicable, a Kepler player server is expected to issue session status updates upon acting on a
+     * Kepler player request received through the installed `IPlayerServerHandler` instance.
+     *
+     * @example
+     * ```typescript
+     * let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 1.
+     * let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 2.
+     *
+     * let sampleData_1: IPlayerSessionStatus = {
+     *     sessionID: { id: 1 },
+     *     playbackSpeed: 1.0,
+     *     playbackStatus: IPlaybackStatus.PAUSED,
+     *     isMuted: true,
+     *     volume: 0.0,
+     *     seekable: false,
+     *     duration: mediaPlayer1.duration || 0
+     * };
+     *
+     * let sampleData_2: IPlayerSessionStatus = {
+     *     sessionID: { id: 2 },
+     *     playbackSpeed: 2.0,
+     *     playbackStatus: IPlaybackStatus.PLAYING,
+     *     isMuted: false,
+     *     volume: 0.75,
+     *     seekable: true,
+     *     duration: mediaPlayer2.duration || 0
+     * };
+     *
+     * playerServerRef.current?.updateStatus(
+     *     [sampleData_1, sampleData_2]
+     * );
+     * ```
+     *
+     * @returns Promise that resolves when the update is complete.
+     */
+    updateStatus: (
+    /**
+     * Array of IPlayerSessionStatus containing updated session status.
+     */
+    status: Array<IPlayerSessionStatus>) => Promise<void>;
+    /**
+     * Notifies interested clients about Kepler player new track.
+     * {Audio,Video}Player must register to "addtrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList,
+     * and then call this API.
+     *
+     * @details Updating the server session new track is crucial for reflecting changes in media playback
+     * status, currently selected media, and other related information.
+     * Apps can register to "addtrack" EventListener on HtmlMediaElement.{audioTracks,videoTracks,textTracks}
+     * attributes and then call `IPlayerServer.addTrack` if the event is emitted.
+     *
+     * Example:
+     * ```typescript
+     * let media = useRef<VideoPlayer | AudioPlayer | null>(...);
+     * let sessionId = useRef<IPlayerSessionId | undefined>(...);
+     *
+     * const onAudioTrackAdded = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.addTrack({
+     *         id: track.id,
+     *         type: "AUDIO",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         enabled: (track as AudioTrack).enabled
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined audio track.");
+     *     }
+     *   }
+     * }
+     *
+     * const onVideoTrackAdded = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.addTrack({
+     *         id: track.id,
+     *         type: "VIDEO",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         enabled: (track as VideoTrack).selected
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined video track.");
+     *     }
+     *   }
+     * }
+     *
+     * const onTextTrackAdded = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.addTrack({
+     *         id: track.id,
+     *         type: "TEXT",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         mode: (track as TextTrack).mode
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined text track.");
+     *     }
+     *   }
+     * }
+     *
+     * media.current?.audioTracks.addEventListener("addtrack", onAudioTrackAdded);
+     * media.current?.videoTracks.addEventListener("addtrack", onVideoTrackAdded);
+     * media.current?.textTracks.addEventListener("addtrack", onTextTrackAdded);
+     * ```
+     *
+     * @returns Promise that resolves when the update is complete.
+     */
+    addTrack: (
+    /**
+     * Read-only details of new track added.
+     */
+    newTrack: ITrackInfo, 
+    /**
+     * Optional. The session ID of the session whose new track has been added.
+     * If not provided, treat as a request for data on all sessions.
+     */
+    sessionId?: IPlayerSessionId) => Promise<void>;
+    /**
+     * Notifies interested clients about Kepler player existing track removed.
+     * {Audio,Video}Player must register to "removetrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList,
+     * and then call this API.
+     *
+     * @details Updating the server session removed track is crucial for reflecting changes in media playback
+     * status, currently selected media, and other related information.
+     * Apps can register to "removetrack" EventListener on HtmlMediaElement.{audioTracks,videoTracks,textTracks}
+     * attributes and then call `IPlayerServer.removeTrack` if the event is emitted.
+     *
+     * Example:
+     * ```typescript
+     * let media = useRef<VideoPlayer | AudioPlayer | null>(...);
+     * let sessionId = useRef<IPlayerSessionId | undefined>(...);
+     *
+     * const onAudioTrackRemoved = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.removeTrack({
+     *         id: track.id,
+     *         type: "AUDIO",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         enabled: (track as AudioTrack).enabled
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined audio track.");
+     *     }
+     *   }
+     * }
+     *
+     * const onVideoTrackRemoved = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.removeTrack({
+     *         id: track.id,
+     *         type: "VIDEO",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         enabled: (track as VideoTrack).selected
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined video track.");
+     *     }
+     *   }
+     * }
+     *
+     * const onTextTrackRemoved = (event: Event): void => {
+     *   if (event instanceof TrackEvent) {
+     *     let track = (event as TrackEvent).track;
+     *     if (track !== undefined) {
+     *       playerServerRef.current?.removeTrack({
+     *         id: track.id,
+     *         type: "TEXT",
+     *         kind: track.kind,
+     *         label: track.label,
+     *         language: track.language,
+     *         mode: (track as TextTrack).mode
+     *       }, sessionId.current);
+     *       // Do other operations if needed.
+     *     } else {
+     *       console.error("Undefined text track.");
+     *     }
+     *   }
+     * }
+     *
+     * media.current?.audioTracks.addEventListener("removetrack", onAudioTrackRemoved);
+     * media.current?.videoTracks.addEventListener("removetrack", onVideoTrackRemoved);
+     * media.current?.textTracks.addEventListener("removetrack", onTextTrackRemoved);
+     * ```
+     *
+     * @returns Promise that resolves when the update is complete.
+     */
+    removeTrack: (
+    /**
+     * Readonly details of existing track removed.
+     */
+    removedTrack: ITrackInfo, 
+    /**
+     * Optional. The session ID of the session whose existing track has been removed.
+     * If not provided, treat as a request for data on all sessions.
+     */
+    sessionId?: IPlayerSessionId) => Promise<void>;
+    /**
+     * Provides a way to send custom message to interactive component.
+     * Any JSON type can be sent as a message (except `undefined`).
+     *
+     * @details This is particularly useful in providing custom messages which can be used to by client to update UI.
+     *
+     * @example
+     * ```typescript
+     * // Create any object.
+     * const customMessage = {
+     *   video: {
+     *     title: "Video 1",
+     *     myVideoId: 34
+     *   }
+     * };
+     * let sessionId = useRef<IPlayerSessionId | undefined>(...);
+     *
+     * try {
+     *   playerServerRef.current?.sendMessage(customMessage, sessionId);
+     * } catch (error) {
+     *   console.error('Error while calling sendMessage: ', error);
+     * }
+     * ```
+     *
+     * @returns Promise that resolves when the message is sent or rejects with an error
+     * if the request fails, or `message` is undefined.
+     */
+    sendMessage: (
+    /**
+     * Custom message to be sent. send JSON value (except `undefined`) as message.
+     */
+    message: any, 
+    /**
+     * Optional. The session ID of the session for which custom message needs to be handled.
+     */
+    sessionId?: IPlayerSessionId) => Promise<void>;
+    /**
+     * Provides the way to send the error from service component to interactive component.
+     *
+     * Apps can register to "error" EventListener on HtmlMediaElement instance
+     * and then call `IPlayerServer.addTrack` if the event is emitted.
+     *
+     * @example
+     * ```typescript
+     * let media = useRef<VideoPlayer | AudioPlayer | null>(...);
+     * let sessionId = useRef<IPlayerSessionId | undefined>(...);
+     *
+     * const onError = (error: MediaError) => {
+     *   let errorObj: IPlayerSessionError = {
+     *     code: error.code,
+     *     message: error.message
+     *   }
+     *
+     *   try {
+     *     playerServerRef.current?.sendError(errorObj, sessionId);
+     *   } catch (error) {
+     *     console.error('Error while calling sendError: ', error);
+     *   }
+     * };
+     *
+     *
+     * media.current?.addEventListener("error", onError);
+     * ```
+     *
+     * @returns Promise that resolves when the error is sent.
+     */
+    sendError: (
+    /**
+     * Error object to be sent.
+     */
+    error: IPlayerSessionError, 
+    /**
+     * Optional. The session ID of the session for which custom message needs to be handled.
+     */
+    sessionId?: IPlayerSessionId) => Promise<void>;
+}

package/dist/turbo-modules/IPlayerServer.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2025 Amazon.com, Inc. or its affiliates. All rights reserved.
+ *
+ * AMAZON PROPRIETARY/CONFIDENTIAL
+ *
+ * You may not use this file except in compliance with the terms and
+ * conditions set forth in the accompanying LICENSE.TXT file.
+ *
+ * THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY
+ * DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS,
+ * IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+ */
+export {};

package/dist/turbo-modules/KeplerPlayerServerTurboModule.d.ts

@@ -0,0 +1,18 @@
+import type { KeplerTurboModule } from '@amazon-devices/keplerscript-turbomodule-api';
+import { IPlayerSessionError, IPlayerSessionPosition, IPlayerSessionStatus, IPlayerSessionId, ITimeRange, ITrackInfo } from './PlayerServerDataTypes/PlayerServerDataTypes';
+import { PlayerEventHandlerParams } from './PlayerServerDataTypes/PlayerServerDataTypesInternal';
+export interface KeplerPlayerServerTurboModule extends KeplerTurboModule {
+    setHandler: (handleCall: (result: PlayerEventHandlerParams, transactionId: number) => void, componentId: string) => void;
+    updateBufferedRanges: (bufferedRanges: Array<ITimeRange>, sessionId: IPlayerSessionId) => void;
+    updateStatus: (statusArray: Array<IPlayerSessionStatus>) => void;
+    addTrack: (newTrack: ITrackInfo, sessionId: IPlayerSessionId) => void;
+    removeTrack: (removedTrack: ITrackInfo, sessionId: IPlayerSessionId) => void;
+    sendMessage: (message: string, sessionId: IPlayerSessionId) => void;
+    sendError: (error: IPlayerSessionError, sessionId: IPlayerSessionId) => void;
+    updatePlaybackPosition: (listenerId: number, sessionPositions: Array<IPlayerSessionPosition>) => void;
+    transactionSuccess: (transactionId: number) => void;
+    transactionSuccessWithValue: (transactionId: number, returnValue: any) => void;
+    transactionError: (transactionId: number, error: string) => void;
+}
+declare const _default: KeplerPlayerServerTurboModule;
+export default _default;

package/dist/turbo-modules/KeplerPlayerServerTurboModule.js

@@ -0,0 +1,3 @@
+import { TurboModuleRegistry } from '@amazon-devices/keplerscript-turbomodule-api';
+// prettier-ignore
+export default TurboModuleRegistry.getEnforcing('KeplerPlayerServerTurboModule');

package/dist/turbo-modules/PlayerServer.d.ts

@@ -0,0 +1,42 @@
+import { IPlayerServer } from './IPlayerServer';
+import { IPlayerServerHandler } from './PlayerServerHandler';
+import { IPlayerSessionError, IPlayerSessionStatus, IPlayerSessionId, ITimeRange, ITrackInfo } from './PlayerServerDataTypes/PlayerServerDataTypes';
+import { PlayerEventHandlerParams } from './PlayerServerDataTypes/PlayerServerDataTypesInternal';
+/**
+ * @ignore
+ * The implementation of IPlayerServer.
+ */
+export declare class PlayerServer implements IPlayerServer {
+    private mServerHandler;
+    private mPositionListenerMap;
+    clearPositionListeners(sessionId?: IPlayerSessionId, listenerId?: number): boolean;
+    handleEvent(result: PlayerEventHandlerParams, transactionId: number): void;
+    /**
+     * {@inheritDoc}
+     */
+    setHandler(_handler: IPlayerServerHandler, _componentId: string): void;
+    /**
+     * {@inheritDoc}
+     */
+    updateBufferedRanges(_bufferedRanges: Array<ITimeRange>, _sessionId?: IPlayerSessionId): Promise<void>;
+    /**
+     * {@inheritDoc}
+     */
+    updateStatus(_states: Array<IPlayerSessionStatus>): Promise<void>;
+    /**
+     * {@inheritDoc}
+     */
+    addTrack(_newTrack: ITrackInfo, _sessionId?: IPlayerSessionId): Promise<void>;
+    /**
+     * {@inheritDoc}
+     */
+    removeTrack(_removedTrack: ITrackInfo, _sessionId?: IPlayerSessionId): Promise<void>;
+    /**
+     * {@inheritDoc}
+     */
+    sendMessage(_message: any, _sessionId?: IPlayerSessionId): Promise<void>;
+    /**
+     * {@inheritDoc}
+     */
+    sendError(_error: IPlayerSessionError, _sessionId?: IPlayerSessionId): Promise<void>;
+}