JumpSkip

A powerful, lightweight Lua script for MPV that detects and skips media segments (intros, recaps, outros/credits, and previews) using crowdsourced timestamp data from TheIntroDB, IntroDB, and SkipDB.

OSC by ModernZ

Important

Colored Segments work only using a modified ModernZ or uosc

Guide

Intro

Recap

Outro/Credits

Preview/Post-Credits

All colors are changeable in modernz.conf or uosc.conf

---

✅ Works with ani-cli

Note

You can check quarried segments in Console.

If the movie/TV show is not found, open an Issue to help improve detection.

---

Checkout my MPV Config

---

Features

• Multi Provider Integration:
  • TheIntroDB TV and movies.
  • IntroDB TV and movies.
  • SkipDB TV and movies.
• Intelligent Fallback & Merging:
  • Configurable provider priority (theintrodb,introdb,skipdb or in any order).
  • Seamless fallback: if the primary provider has no match or encounters a network error, the script automatically queries the next provider.
  • Segment Merging: If the primary provider has an intro but lacks an outro or recap, the script queries subsequent providers to fill in missing segment types.
• Colored Segments:
  • Show skippable segments types directly in the seekbar with diffrent customizable colors script-opts/modernz.conf or script-opts/uosc.conf.
  • Requires modified ModernZ or uosc
• Interactive On-Screen Clickable Button:
  • Semi-transparent vector card (ASS overlay) (Skip Intro ▶, Skip Outro ▶, etc.).
• Interactive On-Screen Clickable Timestamps Submission Interface:
  • An interactive interface letting you submit timestamps directly from within mpv, eliminating the need for manual data entry (default: Ctrl+q). Preview
  • Requires a provider API key.
• Chapter-based skipping:
  • Automatically skips chapters based on title (eg. "OP" or "Outro", "Recap" etc.).
• Keyboard Shortcut:
  • Instant skipping via configurable keybind (default: Tab).
• Configurable Auto-Skip:
  • Option to automatically skip segments when playback enters them (enabled in jumpskip.conf).
  • Optional countdown timer before auto-skipping, with on-screen visual feedback.
• Smart Media Identification:
  • Title-to-ID fallback lookup via Cinemeta or optional TMDb API
  • Reads embedded file metadata tags and parses filenames and folder paths for IMDb IDs.
• Fully Configurable:
  • Fine-tune timing offsets, segment toggles, provider priorities, timeouts, colors, and button positions via script-opts/jumpskip.conf.

---

Media Identification

1. TMDB API — used first, if a key is configured (Recommended)

• If tmdb_api_key is set in user options, it searches api.themoviedb.org/3/search/movie or /search/tv by parsed title (+ year for movies).
• On a hit, it stores the TMDB ID, then makes a second call to /external_ids to resolve an IMDb ID.

2. Cinemeta — fallback when no TMDb key

• Queries v3-cinemeta.strem.io/catalog/movie|series/top/search=<title>.json (no API key needed).
• Scores every returned candidate, penalising lower-ranked results by −0.5 per rank position, the accepts the best match only if its score ≥ 300, storing its IMDb ID.

Dependencies

• mpv: v0.29.0 or newer (tested with mpv v0.41.0).
• curl: Used for asynchronous HTTP requests.
  • Windows 10/11: Built-in system tool (preinstalled in System32).
  • Linux / macOS: Standard package (sudo apt install curl or brew install curl).

---

Installation

1. Download jumpskip.lua and jumpskip.conf

2. Copy jumpskip.lua and jumpskip.conf into your mpv config directory

• For Portable mpv:

  mpv/portable_config/scripts/jumpskip.lua

  mpv/portable_config/script-opts/jumpskip.conf

• For Standard System mpv:

  • Windows: %APPDATA%\mpv\scripts\jumpskip.lua
  • Linux / macOS: ~/.config/mpv/scripts/jumpskip.lua

---

Configuration (jumpskip.conf)

Create or edit ~~/script-opts/jumpskip.conf:

# Master toggle for the script
enabled=yes
# Directory filter (inclusion & exclusion)
filter_directories=
# Auto-skip segments
auto_skip=no
# Countdown to auto-skip triggering
auto_skip_countdown=0
# Segment types to auto-skip(intro, outro, recap, preview, post_credits)
autoskip_types=
# Countdown to Skip button hiding
skip_button_timeout=3
# Keybinding to trigger skip:
keybind=Tab
# Minimum segment duration to consider valid:
min_segment_duration=3.0

# Segment types to detect and allow skipping:
skip_intro=yes
skip_recap=yes
skip_outro=yes
skip_preview=yes
skip_post_credits=yes

# Timestamps Submission (Provider API key required):
# Master toggle
enable_submission=yes
# Keybinding to open/close the submission overlay.
submission_keybind=Ctrl+q
# Per-provider submission toggles
theintrodb_submit_enabled=yes
introdb_submit_enabled=yes
skipdb_submit_enabled=yes

# Provider options:
# Per-media-type provider priority
provider_priority_tvshow=introdb,theintrodb,skipdb
provider_priority_movie=introdb,theintrodb,skipdb
# Per-provider, per-segment-type toggles
#TheIntroDB
theintrodb_intro_segment=yes
theintrodb_recap_segment=yes
theintrodb_outro_segment=yes
theintrodb_preview_segment=yes
#IntroDB
introdb_intro_segment=yes
introdb_recap_segment=yes
introdb_outro_segment=yes
introdb_preview_segment=yes
introdb_post_credits_segment=yes
#SkipDB
skipdb_intro_segment=yes
skipdb_recap_segment=yes
skipdb_outro_segment=yes
skipdb_preview_segment=yes

# Timing offsets (in seconds):
start_offset=0.0
end_offset=0.0
# Merge providers:
merge_providers=yes

# Optional API Keys:
# TheIntroDB API key
theintrodb_api_key=
# IntroDB API key
introdb_api_key=
# SkipDB API key 
skipdb_api_key=
# TMDb API key:
tmdb_api_key=

# OSD Button Settings:
# Button Position:
button_position=bottom-right
# Button Margins:
button_margin_x=60
button_margin_y=120
# Button Dimensions & Font:
button_width=220
button_height=56
button_font_size=24
button_font=mpv-osd
# Button Visual Colors:
accent_color=5ba3f0
bg_color=0A0A0A
text_color=FFFFFF
hint_color=AAAAAA

# OSD message upon skipping:
show_osd_message=yes
osd_message_duration=2.0

# Colored segments:
# Master toggle for coloured seekbar segment markers
show_colored_segments=yes
# Per-type marker toggles
show_colored_intro_segments=yes
show_colored_recap_segments=yes
show_colored_outro_segments=yes
show_colored_preview_segments=yes
show_colored_post_credits_segments=yes

# Insert segment type as a chapter:
mark_chapters=yes
# Name for chapter created:
default_chapter_title=Chapter

# Chapter-based skipping:
# Master toggle 
chapter_skip_enabled=yes
# Per-category toggles
chapter_skip_intro=yes
chapter_skip_outro=yes
chapter_skip_recap=yes
chapter_skip_preview=yes
# Keyword lists
chapter_skip_keywords_intro=intro,introduction,opening,op,theme,title sequence
chapter_skip_keywords_outro=ed,ending,outro,credits,end credits,closing
chapter_skip_keywords_recap=recap,previously
chapter_skip_keywords_preview=preview,next episode
# Sanity bounds for chapter duration
chapter_skip_min_duration=10.0
chapter_skip_max_duration=600.0
# Overlap threshold
chapter_skip_overlap_threshold=0.5

# HTTP network request timeout:
request_timeout=8
# Enable debug logging in mpv terminal:
debug_mode=no

---

TO-DO

• Add IntroDB movies.
• Add Per-media type, provider priority.
• Add Timestamps Submission.
• Add Colored segments support to other osc.
  • uosc
• Add ani-cli support.
• Add AniSkip.

Changelog

Click Here

Contributing

Suggestions and contributions are welcome. Feel free to open an issue or submit a pull request.