simple-twitch

A lightweight shell script to browse and watch Twitch streams, VODs, and categories directly from your desktop using a dmenu-based interface.

Features

• 📺 Watch live streams from your followed channels or by searching categories
• 🎮 Browse by game/category: search and save favourite categories
• 📼 Watch VODs with resolution selection and automatic resume (saves last watched position)
• 🔔 Desktop notifications for new live streams via a systemd timer (checks every 5 minutes)
• 💬 Opens chat in a browser alongside the stream
• ➕ Manage channels and games: add/remove favourites from the menu

Dependencies

Package	Purpose
mpv	Stream/VOD playback
yt-dlp	Stream URL resolution
curl	Twitch API requests
jq	JSON parsing
dmenu	Interactive menu UI (configurable)
firefox	Chat window (configurable)
notify-send	Desktop notifications
sed, awk, grep	Text processing

Installation

Arch Linux (AUR / PKGBUILD)

makepkg -si

Manual

Copy the files to their appropriate locations:

install -Dm755 simple-twitch.sh /usr/bin/simple-twitch
install -Dm644 simple-twitch-lib.sh /usr/share/simple-twitch/simple-twitch-lib.sh
install -Dm600 simple-twitch.conf /etc/simple-twitch.conf
install -Dm644 simple-twitch.service /usr/lib/systemd/user/simple-twitch.service
install -Dm644 simple-twitch.timer /usr/lib/systemd/user/simple-twitch.timer
install -Dm644 twitch-stream-notif.sh /var/lib/simple-twitch/twitch-stream-notif.sh
install -Dm644 simple-twitch.desktop /usr/share/applications/simple-twitch.desktop

Configuration

Edit /etc/simple-twitch.conf and fill in your Twitch API credentials:

TWITCH_CLIENTID=your_client_id
TWITCH_SECRET=your_client_secret

You can obtain these by registering an application at dev.twitch.tv.

Optional settings

Variable	Default	Description
MENU_CMD	dmenu	Menu command to use (e.g. rofi -dmenu)
CHAT_CMD	firefox --new-window	Command to open Twitch chat
MAX_VID	100	Maximum number of VODs to fetch

Channel & game lists

After installation, two files are used to store your favourites:

• $XDG_CONFIG_HOME/simple-twitch/listchanneltwitch: one channel name per line
• $XDG_CONFIG_HOME/simple-twitch/listgamestwitch: saved game/category entries

These can be managed directly from the interactive menu.

Usage

simple-twitch [OPTION] [ARG]

Option	Description
(none)	Open the interactive dmenu interface
--live [channel]	Show live streams from your channel list (or a specific channel)
--game	Browse streams by game/category
--vod	Browse and watch VODs
--refresh-token	Manually refresh the Twitch OAuth token
--help	Show usage information

Stream Notifications

Enable the systemd user timer to receive desktop notifications when a channel in your list goes live:

systemctl --user enable --now simple-twitch.timer

The timer runs every 5 minutes and sends a notify-send notification for any newly live channels.