Twitch Clips Player Overlay

obs_capture_clipsreel.webm

What is this?

This is a Twitch Clips Player, browser source overlay for OBS. It grabs your Twitch clips and plays them one after the other in a loop. Keep your viewers entertained on your BRB or starting soon scenes.

NOTE: This project relies on a custom Twitch API Gateway server/service. You can host this service using Docker. Check out the project for more details. https://github.com/teklynk/twitch_api_public

Try it here:

• https://twitchclipsplayer.com
• https://twitch-clips-player.teklynk.com
• https://twitch-clips-player.teklynk.dev
• https://twitch-clips-player.pages.dev

Features

• Chat Control: Control the clips from Twitch chat using !clipskip, !clippause, !clipplay, !clipreload. (Limited to Mods and Streamer).
• Following Feed: Show clips from channels that you follow. Grabs the most recent 700 channels.
• Custom Commands: Use a custom command to start the clips reel and restrict it to Mods only. Type !mycommand stop in chat to stop the clips player.
• Smart Filtering:
  • Date Range: Grab clips from within the last 5, 10, 30 days, etc.
  • Fallback: If no clips match the filters (Date range/Featured), it falls back to the top most popular clips to ensure content plays.
• Details Panel: Display a panel in the lower third of the overlay with clip details. Supports variables: {channel}, {title}, {game}, {creator_name}, {created_at}.

Notes

If you set Date Range AND Prefer featured clips, it will try to pull clips that are featured within the specified date range.

Setup Guide

OBS Settings

1. Add a Browser Source in OBS.
2. Enter the URL with your desired parameters.
3. Important: Check "Shutdown source when not visible" and "Refresh browser when scene becomes active".
   • This prevents the player from running in the background and ensures it reloads fresh when you switch to the scene.
   • Set browser source window size to "1920x1080" and then resize/scale the browser source window. If using the "Outside the box" theme, you will need to set the browser source height to "1440".

Authentication

Twitch authentication is required if you want to:

• Show clips from channels you follow.
• Show messages in chat.

Configuration (URL Parameters)

Add these parameters to your URL query string (e.g., ?channel=mychannel&limit=20).

Parameter	Type	Description
channel	string	Your channel name or a comma-separated list of channels (e.g., user1,user2).
mainAccount	string	The main channel to monitor for chat commands.
ref	base64	Access token for authentication.
limit	integer	Max number of clips to retrieve (max 100).
dateRange	integer	Number of days to look back for clips.
preferFeatured	true/false	If true, tries to pull featured clips first.
showFollowing	true/false	Pulls clips from the latest 100 channels you follow.
showText	true/false	Displays the channel name on top of the video.
showDetails	true/false	Enables the clip details panel on the overlay.
detailsText	string	Custom text for the details panel. Variables: {channel}, {title}, {game}, {creator_name}, {created_at}.
customText	string	Custom message on top of clips. Variables: {channel}.
command	string	Custom chat command to start the player. If not set, plays automatically on load.
themeOption	integer	Select a pre-made CSS theme.
showPoster	true/false	Show or hide the video poster thumbnail image
progressBar	true/false	Show or hide the video progress bar
profileBadge	true/false	Show or hide the channel profile badge/image
videoSize	string	This will force the video player to a specific size: eg: 1920x1080, 1280x720
apiServer	string	Point the clips player to specific API gateway server

Custom CSS

Moving the clip details panel in OBS is quite straightforward. Since the overlay uses absolute positioning, you can easily override its location by adding a few lines of CSS to your browser source's Custom CSS field.

How to change the position of the Details Panel

• In OBS, right-click your Twitch Clips Player browser source and select Properties.
• Scroll down to the Custom CSS text box.
• Paste one of the following snippets at the bottom of that box.

To move the panel to the Top-Right corner:

#details-container {
    top: 2vw !important;
    left: auto !important;
    right: 2vw !important;
}

To move the panel to the Bottom-Right corner:

#details-container {
    top: auto !important;
    bottom: 5vw !important;
    left: auto !important;
    right: 2vw !important;
}

To move the panel to the Bottom-Left corner:

#details-container {
    top: auto !important;
    bottom: 5vw !important;
    left: 2vw !important;
}

Pro-Tips for Users:

• The !important rule: Always include !important after your values. This ensures your custom settings override the built-in theme styles.
• Units (vw vs px): I recommend using vw (viewport width) units. This keeps the panel's position relative to the size of the video, so it stays in the same spot even if you resize the browser source in OBS.
• Fine-tuning: You can use decimal points (e.g., 42.5vw) for pixel-perfect placement!

Self Host / Local Development

You can run this project locally using Docker. A docker-compose.yml file is included.

docker-compose up -d --build

The project will be available at: http://localhost:5001

Stop and remove the container with:

docker-compose down