tmi-clip-shoutout

README

TMI Clip Shoutout

---

Installation with Go

Download and install Go 1.20 or higher. Then install the latest version of the application using go install:

go install git.tblflip.de/root/tmi-clip-shoutout/v4@latest

Installing the precompiled Binaries

If you do not want to install Go and compile the application from source, you can also download precompiled binaries for a variety of platforms from the project page. Binaries are currently built for:

• Linux (amd64, arm64, 386)
• Windows (amd64, arm64, 386)
• Darwin (amd64, arm64)

The latest release version of these binaries can be found here. Other, older versions can be found on the releases page.

Installation using Podman / Docker

If you prefer to run applications inside a docker container, you can also find prebuilt docker containers in the container registry of the project:

podman run --rm -itp 8000:8000 git.tblflip.de/root/tmi-clip-shoutout:latest [OPTIONS]

This will download the latest container version and expose the web interface on localhost:8000. All available [OPTIONS] can be found in the configuration section.

Configuration

The entire application can either be configured using command line flags, environment variables, or a mix of both. To configure the application properly, a Twitch client ID and secret from the Twitch dev portal are required.

Required Parameters

CLI Flag	Env Var	Description
--client-id	CLIENT_ID	The client ID of your twitch application.
--client-secret	CLIENT_SECRET	The client secret of your twitch application.

Optional Parameters

CLI Flag	Env Var	Default	Description
--bind-address	BIND_ADDRESS	:8000	Default address and port for the application to listen on.
--log-level	LOG_LEVEL	info	Log level of the application.
--redis-address	REDIS_ADDRESS	<none>	Address of the Redis cache server. Setting this will enable caching for the application.
--redis-db	REDIS_DB	0	Redis database index for the application cache.

Usage

To actually use this application for your streams, first, generate an overlay URL. You can either do this by using the configurator, or by generating the URL yourself. The resulting URL can then be pasted as a browser source into OBS.

Out of all overly parameters, only the channel is required. Everything else may be left blank. Keep in mind that the configuration tool works after the "garbage in, garbage out" philosophy.

Overlay Parameters

Parameter Name	Query Parameter	Default	Description
Channel	channel	<none>	The Twitch channel to listen for shoutouts on.
Commands	commands	!so	A space separated list of chat commands to listen for.
Target Blacklist	blacklist	<none>	A space separated list of channels that should not receive shoutouts.
Use /shoutout	useShoutout	false	Will listen and react to Twitch's /shoutout command if set to true

Example overlay URL for the channel tblflip with default commands, no blacklist and without listening for /shoutout:

https://tmi-clip-shoutout.paradiso.tblflip.de/overlay?channel=tblflip

Another example overlay URL for the channel ofmiceandclyde with !so and !shoutout commands, which also listens for /shoutout:

https://tmi-clip-shoutout.paradiso.tblflip.de/overlay?channel=ofmiceandclyde&commands=%21so+%21shoutout&useShoutout=true

Alternative Frontends

In case you want to integrate events from tmi-clip-shoutout into another application, or want to provide your own frontend, replace the path with /stream and keep the query parameters as is. The /stream endpoint provides an SSE stream of all configured shoutout events as clip events.

CURL Example to listen for events on the 'tblflip' channel with /shoutout enabled:

curl -N https://tmi-clip-shoutout.paradiso.tblflip.de/stream?channel=tblflip&useShoutout=true

Stream Events

The application currently has four different event types: version, registration, clip and ping. registration is sent back with all relevant registration information after the SSE connection has been established. clip events are generated whenever a shoutout that matches the registration is generated.

In addition to that, the server will send a ping event if no other events have been sent to the client within the past 5 minutes.

version Event

Field	Type	Example	Description
timestamp	string	2023-08-15T15:06:07Z	The RFC3339 timestamp of the event.
version	string	1.0.0	Version of the backend server.
commit	string	11f6b96f[...]	Commit SHA of the current version.
date	string	2023-08-15T15:06:07Z	Build date of the backend server.

registration Event

Field	Type	Example	Description
timestamp	string	2023-08-15T15:06:07Z	The RFC3339 timestamp of the event.
channel	string	#tblflip	The Twitch channel the registration is listening on.
use_pub_sub_shoutout	bool	true	Whether the registration is listening for /shoutout events.
commands	map[string]bool	{"!so": true}	A map of all chat commands the registration is listening for.
blacklist	map[string]bool	{}	A map of all channel names this registration will not receive clip events for.

clip Event

Field	Type	Example	Description
timestamp	string	2023-08-15T15:06:07Z	The RFC3339 timestamp of the event.
channel	string	#tblflip	The Twitch channel the shoutout was generated for.
command	string | null	!so	The chat command used for the shoutout. Null if /shoutout was used.
is_pub_sub_shoutout	bool	false	Whether the event was generated due to a /shoutout.
target	string	Ofmiceandclyde	The display name of the shoutout target.
target_image	url	https://[...]	The profile picture URL of the shoutout target.
target_color	string | null	#88007F	The channel accent color of the shoutout target. Null if no accent color was set by the target.
text_color	string	#FFFFFF	The recommended text color to use on top of target_color. White if no target_color exists.
clip_url	url	https://[...]	The playback URL of the shoutout clip.

ping Event

Field	Type	Example	Description
timestamp	string	2023-08-15T15:06:07Z	The RFC3339 timestamp of the event.