Capacitor Bridge Skill

This skill handles the communication between the React Frontend and the Native Android layer (TVPlayer.java). Primary Goal: Launch external players (VLC, MX Player, Vimu) correctly and handle their return results (resume position).

桥 API Contract

TVPlayer.play(options)

Launches a single video file. Must return a Promise that resolves only after the player closes.

Options:

• •url (string, required): Direct link to the video stream.
• •package (string, optional): Specific player package name (e.g., net.gtvbox.videoplayer). If null, opens system chooser.
• •title (string): Title to display in the player.
• •position (number): Resume position in milliseconds.

Java Extras (What actually gets sent):

• •Intent.ACTION_VIEW
• •return_result: true
• •Flags: FLAG_ACTIVITY_CLEAR_TOP, FLAG_ACTIVITY_SINGLE_TOP (Crucial for preventing double rendering).

TVPlayer.playList(options)

Launches a playlist (Season/Series).

Options:

• •urls (string[]): Array of video URLs.
• •names (string[]): Array of episode titles.
• •startIndex (number): Which index to start playing.
• •position (number): Resume position for the started episode.

📱 Supported Players & Extras

Vimu Player (net.gtvbox.videoplayer)

• •Single: forcename (Title), forcedirect (No buffer), startfrom (Position).
• •Playlist: Uses application/vnd.gtvbox.filelist MIME type.
  • •asusfilelist (URLs)
  • •asusnamelist (Names)

MX Player (com.mxtech.videoplayer.ad / .pro)

• •Single: title, position.
• •Playlist: Uses standard video/* with extras.
  • •video_list (Parcelable Uri[])
  • •video_list.name (String[])

VLC (org.videolan.vlc)

• •Single: title, from_start (false).
• •Playlist: Not fully supported via Intent extras, falls back to acting as single file player currently.

⚠️ Critical Rules

1. •Do NOT change FLAG_ACTIVITY_SINGLE_TOP. This prevents the app from restarting or opening a second instance of the intent chooser.
2. •RESTRICTED: FLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_CLEAR_TOP. These flags are essential for correct stack manipulation between PWA and Native Player. Removing them breaks the return journey.
3. •Lifecycle: The promise resolves when onActivityResult fires (i.e., user closes the player).
   • •Requirement: play() method MUST return a Promise resolving with { position, duration }.
4. •Resume Logic: The result object contains { position: number, duration: number, finished: boolean }. You MUST save this to localStorage immediately.