Vega Matter Casting Integration

[offers.matter-casting]
vendor-id = <<App Specific VID granted by CSA, eg. 65521>>
product-id = <<App Specific PID granted by CSA, eg. 5678>>
vendor-name = "Your App Name"

{
  "dependencies": {
    // Content Launcher
    "@amazon-devices/kepler-media-content-launcher": "^2.0.0",

    // Media Controls
    "@amazon-devices/kepler-media-controls": "~1.0.0",
    "@amazon-devices/kepler-media-types": "~1.0.0",

    // Account Login
    "@amazon-devices/kepler-media-account-login": "^1.1.0",
    "@amazon-devices/headless-task-manager": "^1.1.0",

    "@amazon-devices/vega-target-navigator-provider": "*"
  }
}

export class ContentLauncherHandler {

  // --- Matter 0x00 LaunchContent (Optional, requires CS feature) and
  // 0x01 LaunchURL (Optional, requires UP feature) ---
  //
  // Content Launch is supported through the same handleLaunchContent interface.
  // Therefore, regardless of which command (LaunchURL or LaunchContent) the phone
  // sends, content app will handle in the same way.
  //
  // IMPORTANT — Response contract:
  //   The provider MUST resolve the returned Promise<ILauncherResponse>. The Matter Casting
  //   service enforces a 25-second command timeout, so the provider
  //   SHALL return the ILauncherResponse within 20 seconds to allow
  //   for transport and processing overhead. If no response is received
  //   within 25 seconds, the phone app will receive a timeout error.
  //
  async handleLaunchContent(
    contentSearch: IContentSearch,
    autoPlay: boolean,
    _optionalFields: ILaunchContentOptionalFields,
  ): Promise<ILauncherResponse> {

    if (autoPlay) {
      console.log('Content Launcher: autoPlay=true, starting playback');
    } else {
      console.log('Content Launcher: autoPlay=false, showing search results');
    }

    // Return SUCCESS — the Matter Casting service translates this into
    // a Matter LauncherResponse (0x02) with status SUCCESS
    return this.factory
      .makeLauncherResponseBuilder()
      .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
      .optionalData('Launch handled successfully')
      .build();

    // Other status options:
    //   ContentLauncherStatusType.AUTH_FAILED      — user not authorized
    //   ContentLauncherStatusType.URL_NOT_AVAILABLE — content not found / other error
  }
}

export class MediaControlHandlerAsync implements IMediaControlHandlerAsync {

  // --- Matter 0x00 Play (mandatory) ---
  async handlePlay(_sessionId?: IMediaSessionId): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.PLAYING;
    this.state.playbackSpeed = 1.0;
    this.pushState();
  }

  // --- Matter 0x01 Pause (mandatory) ---
  async handlePause(
    _sessionId?: IMediaSessionId,
    _context?: ICommandContext,
  ): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.PAUSED;
    this.pushState();
  }

  // --- Matter 0x02 Stop (mandatory) ---
  async handleStop(_sessionId?: IMediaSessionId): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.NOT_PLAYING;
    this.state.currentPosition = { seconds: 0, nanoseconds: 0 };
    this.pushState();
  }

  // --- Matter 0x03 StartOver (Optional) ---
  async handleStartOver(_sessionId?: IMediaSessionId): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.PLAYING;
    this.state.currentPosition = { seconds: 0, nanoseconds: 0 };
    this.state.playbackPosition.position = { seconds: 0, nanoseconds: 0 };
    this.pushState();
  }

  // --- Matter 0x04 Previous (optional) ---
  async handlePrevious(): Promise<void> {
    // Business logic to skip to the previous track
  }

  // --- Matter 0x05 Next (optional) ---
  async handleNext(_sessionId?: IMediaSessionId): Promise<void> {
    // Business logic to skip to the next track
  }

  // --- Matter 0x06 Rewind (optional, requires VariableSpeed feature) ---
  async handleRewind(_sessionId?: IMediaSessionId): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.PLAYING;
    if (this.state.playbackSpeed > -5.0) {
      this.state.playbackSpeed =
        this.state.playbackSpeed <= -1.0
          ? this.state.playbackSpeed - 1.0
          : -1.0;
    }
    this.pushState();
  }

  // --- Matter 0x07 FastForward (optional, requires VariableSpeed feature) ---
  async handleFastForward(_sessionId?: IMediaSessionId): Promise<void> {
    this.state.playbackStatus = PlaybackStatus.PLAYING;
    if (this.state.playbackSpeed < 5.0) {
      this.state.playbackSpeed =
        this.state.playbackSpeed >= 1.0
          ? this.state.playbackSpeed + 1.0
          : 1.0;
    }
    this.pushState();
  }

  // --- Matter 0x08 SkipForward (optional) ---
  async handleSkipForward(
    delta: ITimeValue,
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    this.state.currentPosition = {
      seconds: this.state.currentPosition.seconds + delta.seconds,
      nanoseconds: this.state.currentPosition.nanoseconds + delta.nanoseconds,
    };
    this.state.playbackPosition.position = this.state.currentPosition;
    this.pushState();
  }

  // --- Matter 0x09 SkipBackward (optional) ---
  async handleSkipBackward(
    delta: ITimeValue,
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    this.state.currentPosition = {
      seconds: Math.max(0, this.state.currentPosition.seconds - delta.seconds),
      nanoseconds: 0,
    };
    this.state.playbackPosition.position = this.state.currentPosition;
    this.pushState();
  }

  // --- Matter 0x0B Seek (optional, requires AdvancedSeek feature) ---
  async handleSeek(
    position: ITimeValue,
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    this.state.currentPosition = position;
    this.state.playbackPosition.position = position;
    this.pushState();
  }

  // --- Matter 0x0C ActivateAudioTrack (optional, requires AudioTracks feature) ---
  async handleSetAudioTrack(
    audioTrack: ITrack,
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    // Business logic to activate the selected audio track.
  }

  // --- Matter 0x0D ActivateTextTrack (optional, requires TextTracks feature) ---
  async handleEnableTextTrack(
    textTrack: ITrack,
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    // Business logic to enable the selected text track
  }

  // --- Matter 0x0E DeactivateTextTrack (optional, requires TextTracks feature) ---
  async handleDisableTextTrack(
    _sessionId?: IMediaSessionId,
  ): Promise<void> {
    // Business logic to disable the active text track.
  }
}

export class AccountLoginWrapper {

  createAccountLoginHandler(): IAccountLoginHandlerAsync {
    return {

      // --- Matter 0x00 GetSetupPIN ---
      // The content app generates a setup PIN for the given account.
      handleGetSetupPin: async (accountId: string): Promise<string> => {
        console.log(`[KCP] handleGetSetupPin, accountId=${accountId}`);
        const setupPin = '12345678';
        return setupPin;
      },

      // --- Matter 0x02 Login ---
      // The content app verifies the PIN and signs the user in.
      handleLogin: async (accountId: string, pin: string): Promise<void> => {
        console.log(`[KCP] handleLogin, accountId=${accountId}`);
        await AccountLoginWrapper.saveLoginStatus(true);
        const status = accountLoginServerComponent
          .makeStatusBuilder()
          .status(StatusType.SIGNED_IN)
          .build();
        this.accountLoginServer?.updateStatus(status);
      },

      // --- Matter 0x03 Logout ---
      // The player sends this to end the user's session.
      handleLogout: async (): Promise<void> => {
        console.log('[KCP] handleLogout');
        await AccountLoginWrapper.saveLoginStatus(false);
        const status = accountLoginServerComponent
          .makeStatusBuilder()
          .status(StatusType.SIGNED_OUT)
          .build();
        this.accountLoginServer?.updateStatus(status);
      },
    };
  }
}

const server: IMediaControlServerAsync =
  MediaControlServerComponentAsync.getOrMakeServer();

// After any playback state change, rebuild and push the session state.
const mediaPlayerState = new MediaPlayerState(); // from your MediaPlayerState class

// Example: user presses play.
mediaPlayerState.playbackStatus = PlaybackStatus.PLAYING;
mediaPlayerState.playbackSpeed = 1.0;
server.updateMediaSessionStates([mediaPlayerState.getServerState()]);

// Example: user seeks to 5 minutes.
mediaPlayerState.currentPosition = { seconds: 300, nanoseconds: 0 };
mediaPlayerState.playbackPosition.position = { seconds: 300, nanoseconds: 0 };
server.updateMediaSessionStates([mediaPlayerState.getServerState()]);

// Example: user pauses.
mediaPlayerState.playbackStatus = PlaybackStatus.PAUSED;
server.updateMediaSessionStates([mediaPlayerState.getServerState()]);

// Example: content changed (such as next episode or Content Launcher started
// a new movie).
mediaPlayerState.mediaId = {
  contentId: 'episode-002',
  catalogName: 'my-catalog-v1',
};
mediaPlayerState.playbackStatus = PlaybackStatus.PLAYING;
mediaPlayerState.currentPosition = { seconds: 0, nanoseconds: 0 };
mediaPlayerState.playbackPosition.position = { seconds: 0, nanoseconds: 0 };
server.updateMediaSessionStates([mediaPlayerState.getServerState()]);

const server: IAccountLoginServerAsync =
  new AccountLoginServerComponent().getOrMakeServer();

// Example: user signs in.
const signedInStatus = new AccountLoginServerComponent()
  .makeStatusBuilder()
  .status(StatusType.SIGNED_IN)
  .build();
server.updateStatus(signedInStatus);

// Example: user signs out.
const signedOutStatus = new AccountLoginServerComponent()
  .makeStatusBuilder()
  .status(StatusType.SIGNED_OUT)
  .build();
server.updateStatus(signedOutStatus);