IntroDB Service To Skip Intro/Outro For Movies/TV Shows

[itsmechinmoy]

Describe your suggested feature:

Integrate TheIntroDB API (https://theintrodb.org/) into Animiru to provide automatic skip detection for intros, recaps, credits, and previews for TV shows and movies. This feature would allow users to automatically skip repetitive segments while watching episodes or films, significantly improving the viewing experience.

Key functionality:

• Fetch skip timestamps (intro, recap, credits, preview) from TheIntroDB API
• Support both TV episodes and movies
• Use Simkl's returned IDs (TMDB, IMDB, TVDB) to query TheIntroDB
• Display skip buttons in the video player when timestamps are available
• Allow users to choose skip behavior (auto-skip or manual skip button)

---

Other details:

API Reference:

• Endpoint: GET https://api.theintrodb.org/v3/media
• Parameters: tmdb_id, imdb_id, or tvdb_id (one required)
• TV episodes also need: season and episode
• Returns: JSON with intro, recap, credits, preview arrays containing start_ms and end_ms

Response Example:

{
  "tmdb_id": 12345,
  "type": "movie",
  "intro": [
    {
      "start_ms": null,
      "end_ms": 23000
    }
  ],
  "recap": [
    {
      "start_ms": 25000,
      "end_ms": 134000
    }
  ],
  "credits": [
    {
      "start_ms": 5801777,
      "end_ms": 6371111
    }
  ],
  "preview": [
    {
      "start_ms": 1680000,
      "end_ms": 1740000
    }
  ]
}

How Animiru can get the required IDs:

Animiru already has Simkl tracking implemented. Simkl's API returns comprehensive IDs in its responses for both TV shows and movies:

Simkl API Response (Movies/TV):

{
  "title": "Inception",
  "year": 2010,
  "ids": {
    "simkl": 472214,
    "tmdb": "27205",
    "imdb": "tt1375666",
    "tvdbm": "113"
  },
  "ratings": {
    "simkl": { "rating": 8.6, "votes": 11454 },
    "imdb": { "rating": 8.8, "votes": 2816410 }
  }
}

IDs available from Simkl:

• tmdb - The Movie Database ID
• imdb - IMDb ID (format: tt#######)
• tvdbm - TVDB ID
• tvdbmslug - TVDB slug

Implementation Approach:

Since Animiru has Simkl tracking, we can use the tmdb_id, imdb_id, or tvdb_id from Simkl's data to query TheIntroDB API. When a user is watching a tracked TV show or movie, the app can:

1. Get the media's IDs from Simkl's data
2. Use tmdb_id (or fallback to imdb_id/tvdb_id) to query TheIntroDB
3. For TV episodes, also pass season and episode numbers
4. Display skip buttons in the player when timestamps are found

Implementation Reference (from NyanTV):

// NyanTV's existing (unfinished) implementation
object IntroDbService {
    private const val API_URL = "https://api.introdb.app/segments"
    
    suspend fun getSkipTimes(
        imdbId: String,
        season: String,
        episode: String
    ): EpisodeSkipTimes? {
        // Fetches and parses skip times
    }
}

// SimklService already returns tmdb_id
private fun JsonObject.toSimklMedia(isMovie: Boolean): Media? {
    val tmdbId = ids?.get("tmdb_id")?.jsonPrimitive?.contentOrNull
        ?: ids?.get("tmdb")?.jsonPrimitive?.contentOrNull
    // ...
}

Expected Integration Points:

1. Enhance IntroDbService to support tmdb_id and tvdb_id alongside imdb_id
2. In the video player, check if the TV show or movie has TheIntroDB timestamps
3. Display skip buttons (or auto-skip based on user preference)
4. Add a settings option for skip behavior (auto-skip / manual / disabled)

Benefits:

• Automated skip of repetitive content (intros, recaps, credits, previews)
• Better viewing experience, especially for binge-watching TV shows
• Uses community-sourced timestamps from TheIntroDB
• No additional auth required for reading timestamps
• Works for both movies and TV content

Potential Implementation Challenges:

• Some TV shows or movies might not have timestamps in TheIntroDB yet
• Different releases/versions of episodes might have different timings
• Need to handle episodes where only some segments have data
• Timestamps might need to account for localized versions
• Different video sources may have varying start times

Attachments:

• TheIntroDB API Docs: https://theintrodb.org/docs
• TheIntroDB OpenAPI: https://theintrodb.org/swagger
• NyanTV reference: https://github.com/NyanTV/NyanTV/blob/main/app/src/main/java/com/nyantv/data/IntrodbService.kt
• Simkl IDs reference: https://simkl.docs.apiary.io/#reference/movies/movie/get-movie-details