Integration of IntroDB.app for Skip Intro and Credits Support

[kingargyle]

Needed to support #448

1. Summary / Goal

Integrate the IntroDB.app API to provide "Skip Intro" and "Skip Credits" functionality during video playback. This feature will allow users to skip repetitive segments or jump straight to the next episode, aligning Serenity with modern streaming standards.

2. Technical Analysis & Requirements

A. Metadata Enhancement (Prerequisite)

IntroDB requires a common external identifier (IMDb, TMDB, or TVDB ID). Currently, the emby-lib module does not capture these IDs.

• Model Update: Modify us.nineworlds.serenity.emby.server.model.Item in ItemsModel.kt to include @Json(name = "ProviderIds") val providerIds: Map<String, String>?.
• API Update: Modify UsersService.kt to include ProviderIds in the Fields query parameter for fetchItemQuery, resumableItems, unwatchedItems, latestItems, and fetchSimilarItemById.
• Domain Mapping: Update MediaContainerAdaptor to propagate these IDs into the core VideoContentInfo object.

B. New Integration: introdb-api

Implement a client for IntroDB:

• Endpoints: GET /get_intros and GET /get_credits.
• Identification: Use the IMDb ID (e.g., tt15239678) or TMDB ID retrieved from Emby to query IntroDB.

C. Presenter Logic (ExoplayerPresenter)

• Asynchronous Fetching: When a video is selected for playback, trigger a background request to IntroDB via the VideoContentInfo provider IDs.
• Segment Management: Store a list of SkipSegment objects (Start/End timestamps).
• View Contract: Update ExoplayerContract.ExoplayerView with:
  • showSkipIntroButton(endTimeTicks: Long)
  • hideSkipIntroButton()

D. UI Implementation (ExoplayerVideoActivity)

• Layout: Add a "Skip Intro" button overlay to activity_exoplayer_video.xml.
• Playback Monitoring: Utilize the existing ProgressRunnable to check if player.currentPosition falls within a skip segment.
• Action: Clicking the button performs player.seekTo(skipEndPosition).
• Focus Management: Ensure the button is accessible via D-Pad for Android TV users.

3. Implementation Phases

• Phase 1: Refactor emby-lib models and UsersService to support ProviderIds.
• Phase 2: Create the IntroDB API service and data models.
• Phase 3: Update ExoplayerPresenter to fetch and evaluate skip segments.
• Phase 4: Implement the UI button and seek logic in ExoplayerVideoActivity.
• Phase 6: Heurstic Backup
• Phase 5: (Optional) Add an "Auto-Skip" toggle in Serenity Settings.

4. Files Affected

• emby-lib/src/main/kotlin/us/nineworlds/serenity/emby/server/model/ItemsModel.kt
• emby-lib/src/main/kotlin/us/nineworlds/serenity/emby/server/api/UsersService.kt
• serenity-app/src/main/kotlin/us/nineworlds/serenity/core/model/VideoContentInfo.kt
• serenity-app/src/main/kotlin/us/nineworlds/serenity/ui/video/player/ExoplayerVideoActivity.kt
• serenity-app/src/main/kotlin/us/nineworlds/serenity/ui/video/player/ExoplayerPresenter.kt
• serenity-app/src/main/res/layout/activity_exoplayer_video.xml

5. Verification Plan

• Mock Mode: Unit test the IntroDB API client with MockWebServer using sample JSON responses.
• Capture Mode: Verify metadata retrieval from a live Emby server includes valid IMDb/TMDB IDs.
• Manual UI Test: Verify the "Skip Intro" button appears at the correct time during a video known to have intro data.

Phase 6: Heuristic Backup (Phase 6): If no marker data is available from Emby or IntroDB, implement a duration-based fallback.

• Logic: Trigger "Skip Credits" at 95% completion for episodes > 20 mins.
• Adjustment: Adjust the threshold based on the year field (e.g., older shows get a tighter 30-second window, modern shows get 2-3 minutes).