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.