@amazon-devices/kepler-player-server

The Vega Player Server API provides server-side headless JavaScript media playback functionality for media app developers on Vega This runs media playback on a separate JavaScript thread from the UI, providing up to 30% improvement in Time to First Video Frame (TTFVF) for apps with complex UIs.

Get started

Setup

1. Add the following library dependency to the dependencies section of your package.json file.

   Copy code Copied to clipboard.

    "@amazon-devices/headless-task-manager": "~1.2.4",
    "@amazon-devices/kepler-player-server": "~2.2.14",
    "@amazon-devices/kepler-player-client": "~2.2.14",
   

2. Add following components and privileges in your manifest.toml.

   Copy code Copied to clipboard.

    [[components.interactive]]
    id = "<your-app-package-name>.main"
    runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0" 
    launch-type = "singleton"
    categories = ["com.amazon.category.main"]
   
    [[components.service]]
    id = "<your-app-package-name>.service"
    runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
    launch-type = "singleton"
    .
    .
    .
   
    [processes]
    # Ensure that the player UI and headless JS player components are in the same process group
    [[processes.group]]
    component-ids = ["<your-app-package-name>.main", "<your-app-package-name>.service"]
   
    .
    .
    .
   
    [wants]
   
    [[wants.service]]
    id = "<your-app-package-name>.service"
   
    .
    .
    .
   
    [offers]
   
    [[offers.service]]
    id = "<your-app-package-name>.service"
   

API Reference

Classes

• InvalidArgumentError — Error occurs when the given argument is invalid.
• PlayerServerFactory
• PlayerSessionError — All media elements have an associated error status,

Interfaces

• IHttpHeader — Defines a HTTP header. Apps can send the headers required for
• IMediaLocator — Defines a media URL with optional HTTP headers.
• IOobTextTrackInfo — Defines out-of-band (OOB) text track information.
• IPlayerServer — Represent Kepler player server operations.
• IPlayerServerFactory — Component that provides a kepler player server instance.
• IPlayerServerHandler — An interface for a handler that provides the service logic of the PlayerServer.
• IPlayerSessionError — Represents an error in the Kepler player session.
• IPlayerSessionId — An interface describes media session ID.
• IPlayerSessionLoadParams — Defines parameters for loading media content by URL
• IPlayerSessionMediaInfo — Represents URLs and HTTP headers required for fetching media content.
• IPlayerSessionPosition — Describes media playback position and timing information
• IPlayerSessionStatus — Represents the current status of media playback.
• ISubscription — Represents a subscription that can be used to subscribe to various things.
• ITimeRange — Defines a time range for buffered content in media playback.
• ITrackInfo — Represents detailed information about a media track
• IViewHandle — An interface describes surface handle returned by KeplerVideoSurfaceView or KeplerCaptionsView.

Enumerations

• IPlayerSessionState — Represents the possible states of media playback.
• IUnloadSyncStatus — Represents the possible status values of synchronous unload of media playback.

Type Aliases

• ITextTrackKind — Defines the type of text track and how it should be handled.
• ITextTrackMode — Represents the display mode of the text track.
• ITrackType — Defines the available types of media tracks:

---

Last updated: Jul 22, 2026