Skip to content

Contributor Guide

Help grow the OpenSkip database by submitting timestamps for TV shows.

Getting Started

1. Create an Account

You'll need an invite code to register. Request one from:

  • An existing OpenSkip admin
  • The Discord community
  • GitHub discussions

Once you have a code:

curl -X POST "https://api.openskip.io/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "yourname",
    "email": "you@example.com",
    "password": "securepassword",
    "invite_code": "YOUR_INVITE_CODE"
  }'

2. Wait for Approval

New accounts require admin approval. This helps prevent spam and ensures quality contributions.

3. Get Your API Key

Once approved, create an API key for submitting:

# First, login to get a token
TOKEN=$(curl -s -X POST "https://api.openskip.io/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"username": "yourname", "password": "yourpassword"}' \
  | jq -r '.access_token')

# Create an API key
curl -X POST "https://api.openskip.io/api/v1/auth/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Submissions", "permissions": "submit"}'

Save the returned API key securely - it's only shown once!

Submitting Timestamps

Finding Timestamps

When watching an episode, note these moments:

Segment Start End
Intro When opening credits/theme begins When episode content resumes
Outro When end credits start End of video
Recap "Previously on..." begins When new content starts
Preview "Next time on..." begins End of video

Precision Matters

Use your media player's time display. Most players show time to the second - note that for both start and end.

Making a Submission

For Existing Shows

If the show already exists in OpenSkip:

curl -X POST "https://api.openskip.io/api/v1/submissions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "episode_id": 42,
    "duration_ms": 3550000,
    "intro_start": 0,
    "intro_end": 45.5,
    "outro_start": 3420,
    "outro_end": 3480
  }'

For New Shows

If the show doesn't exist yet, provide TVDB information:

curl -X POST "https://api.openskip.io/api/v1/submissions" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "proposed_tvdb_id": 81189,
    "proposed_show_title": "Breaking Bad",
    "proposed_season": 1,
    "proposed_episode": 1,
    "duration_ms": 3550000,
    "intro_start": 0,
    "intro_end": 45.5,
    "outro_start": 3420,
    "outro_end": 3480,
    "submitter_notes": "First episode, cold open before intro"
  }'

Finding TVDB IDs

  1. Go to TheTVDB.com
  2. Search for your show
  3. The ID is in the URL: thetvdb.com/series/breaking-bad → ID is in the page data

Or use the TVDB API if you have access.

Submission Guidelines

Quality Standards

Good Submissions

  • Accurate to within 1 second
  • Include all segments present (intro, outro, recap if applicable)
  • Correct TVDB ID for the show
  • Accurate file duration

Avoid

  • Guessing timestamps without watching
  • Submitting for trailers or bonus content
  • Duplicate submissions for existing data
  • Timestamps from clips or edited versions

Handling Special Cases

Cold Opens

Some shows start with content before the intro. Set intro_start to where the actual opening credits begin, not 0.

{
  "intro_start": 180,
  "intro_end": 225
}

No Intro/Outro

If an episode genuinely has no intro or outro (like series finales), submit what exists or add a note.

Mid-Credits Scenes

If there's content during credits:

  • Set outro_start at the very end of the content
  • Or note it for moderators

Variable Intros

Some shows (like The Simpsons) have variable-length intros. Submit for your specific version with accurate duration_ms.

Tracking Your Submissions

Check Status

curl -H "X-API-Key: your_api_key" \
  "https://api.openskip.io/api/v1/submissions"

Submission Statuses

Status Meaning
pending Awaiting review
approved Accepted and live
rejected Not accepted (check notes)
needs_info Moderator has questions

Best Practices

Batch Submissions

If submitting multiple episodes, space out your requests:

import time

for episode in episodes:
    submit_timestamp(episode)
    time.sleep(1)  # Be nice to the API

Keep Notes

For unusual cases, add notes:

{
  "submitter_notes": "Extended intro for season premiere"
}

Verify Before Submitting

Double-check timestamps by seeking to them in your player before submitting.

Tools & Tips

VLC Time Display

Enable View → Time to see precise timestamps. Use the time shown when you pause at intro/outro boundaries.

Plex

The timeline shows timestamps when you hover. Note the position where intros/outros begin and end.

mpv

Press o to show OSD with timestamp. Very precise for noting exact positions.

Recognition

Active contributors may be:

  • Listed on the contributors page
  • Given moderator access to help review submissions
  • Mentioned in release notes

Thank you for helping build OpenSkip!

Questions?