MovieBot / StreamCinema Vote Bot

01 / Summary

Chat votes become OBS playback.

Streamer-run movie nights need reliable voting and playback handoff without constant operator control. I built the bot as a Python/TwitchIO remote-control layer: viewers vote in chat, the process tracks the local public-domain catalog and vote state, tie and changed-vote logic selects a winner, and OBS WebSocket receives the media-source update with token refresh, IRC recovery, OBS reconnection, media-load retries, and setup checks around the main flow.

Why this matters

It turns live-stream chores into reliable automation.

Production readiness

The bot flow works; real stream ops need stronger controls.

02 / What I built

The bot logic, OBS handoff, reliability paths, and viewer-facing support pages.

• Implemented Twitch chat commands for voting, results, current movie, time remaining, movie lists, and help output.
• Built movie-folder scanning with supported video extensions, one-level subfolder support, periodic rescans, and local public-domain media validation.
• Built vote-state logic for changed votes, duplicate prevention, partial title matching, tie resolution, and fallback selection.
• Connected OBS WebSocket playback automation by verifying scene/source names, updating the media source, switching scenes, and restarting playback.
• Added Twitch OAuth token refresh, IRC health checks, reconnect behavior, startup validation, logging, pytest coverage for config/bot logic, and Movie Night/Movie Library showcase pages.

External pieces include TwitchIO, Twitch OAuth/chat, OBS WebSocket, IMDb links, poster URLs, and the local public-domain movie files the bot scans.

03 / Problem

Manual stream control does not scale well during a live watch party.

A hosted movie stream needs viewers to pick what plays next, but manual tallying is distracting and error-prone. The streamer has to watch chat, count votes, resolve ambiguous titles, pick a winner, update OBS with the correct local file, and keep the stream running through token or connection issues.

MovieBot reduces that operator burden by turning chat into a controlled input surface and turning OBS into an automated output target. Viewers get predictable commands, while the streamer gets repeatable playback handoff and logs when something goes wrong.

04 / Viewer flow

The viewer experience stays inside Twitch chat.

1. Browse options Viewers use the Movie Library page or the !movies command to see available public-domain titles.
2. Vote by title During an active poll, viewers use !vote <movie name>. The bot accepts exact matches or unambiguous partial matches.
3. Check the room state Commands like !currentmovie, !time, and !results let viewers see what is playing, what is leading, and how much time remains.
4. Change a vote If a viewer picks a different title, the bot removes their previous vote and adds the new one instead of double-counting them.
5. Watch the winner When the current movie ends, the winning title is selected and OBS starts the next local media file after a short reaction delay.

05 / Streamer/operator flow

The streamer configures the environment, then lets the bot run the loop.

1. Prepare Twitch credentials Create a Twitch developer app, use a bot account, and provide client ID, client secret, access token, refresh token, and channel name through local environment settings.
2. Prepare OBS Enable OBS WebSocket, configure the movie scene, and name the media source exactly as the bot expects.
3. Point at local media Set the movie directory to the local folder containing the public-domain video files.
4. Start the bot Run python bot.py. Startup validates required settings, refreshes or validates Twitch tokens, scans movies, connects to OBS, and schedules the first movie.
5. Monitor logs Runtime information is written to the console and bot.log, including OBS errors, token refresh failures, chat recovery, and playback fallback behavior.

06 / Tech stack

Python automation around Twitch, OBS, and local media.

• Python 3.8+
• TwitchIO
• OBS WebSocket
• pytest
• OAuth refresh
• MoviePy / ffprobe

The bot is intentionally small: Python handles async chat commands and background routines, TwitchIO connects to chat, OBS WebSocket controls local playback, ffprobe/MoviePy inspect movie duration, and environment variables keep local credentials out of source control.

07 / Twitch command flow

Commands are validated before they change state.

08 / OBS playback flow

The OBS handoff updates the configured media source.

Text fallback: a viewer sends a chat command, TwitchIO routes it to the bot command parser, and the bot validates the command before changing vote state. When the poll ends, the bot resolves the winner or tie, selects a local movie path from the scanned folder, and sends OBS WebSocket commands to update the media source, switch scenes, restart playback, and produce the stream output. Separate background routines keep Twitch tokens fresh, recover chat/OBS connections, and rescan the local movie folder.

1. Verify OBS connection The bot connects to OBS WebSocket, checks that the configured scene exists, and verifies the configured media source through scene item lookup.
2. Set the local file The selected movie path is normalized and sent to OBS with SetInputSettings against the configured media source.
3. Refresh the source The source is hidden, updated, shown again, the program scene is switched, and the media input is restarted so playback begins immediately.
4. Retry before giving up Media loading uses configurable retry attempts and delays; failures trigger fallback movie selection when possible.

normalized_path = os.path.normpath(path)
settings = {"local_file": normalized_path}

set_settings_request = obs_requests.SetInputSettings(
    inputName=MEDIA_SOURCE_NAME,
    inputSettings=settings,
    overlay=True
)

set_response = await self.safe_obs_call(set_settings_request)
if set_response is not None and await self._set_program_scene(SCENE_NAME):
    if await self._restart_media_input(MEDIA_SOURCE_NAME):
        return True

09 / Movie folder scanning

Local media is discovered from disk and refreshed during the session.

The bot scans the configured movie directory for supported video extensions, including common formats like .mp4, .mkv, .avi, .mov, .webm, .wmv, .mpeg, .mpg, .m4v, and .ts. It also scans one level of subdirectories without following symlinks.

• If the movie directory is missing, the scanner logs the problem and returns an empty list instead of crashing mid-command.
• A periodic movie rescan refreshes the in-memory list every 10 minutes while keeping the previous list if a rescan finds no files.
• Movie duration is read with ffprobe when available, falls back to MoviePy, and finally uses a default duration if both duration checks fail.

10 / Vote changes and ties

The voting model handles real chat behavior.

previous_vote_path = self.voter_data.get(user)
if previous_vote_path:
    if previous_vote_path == selected_movie_path:
        await ctx.send(f"@{user}, you already voted for '{selected_basename}'.")
        return
    if previous_vote_path in self.votes:
        self.votes[previous_vote_path] -= 1
        if self.votes[previous_vote_path] <= 0:
            del self.votes[previous_vote_path]

self.votes[selected_movie_path] = self.votes.get(selected_movie_path, 0) + 1
self.voter_data[user] = selected_movie_path

11 / Token refresh and reconnect behavior

Long-running stream sessions need recovery paths.

12 / Setup and security notes

Credentials stay local, and setup failures should stop early.

• The repo uses .env.example with placeholders for Twitch client ID, client secret, access token, refresh token, channel name, movie directory, OBS host/port/password, scene name, media source name, and optional movie-list URL.
• The README explicitly warns not to commit .env, Twitch tokens, Twitch client secrets, OBS passwords, or generated logs.
• Startup checks required Twitch settings and verifies that MOVIE_DIRECTORY exists before running.
• OBS setup requires WebSocket to be enabled and the scene/source names to match the environment configuration exactly.
• If credentials were ever committed, the documented response is to rotate them before publishing from secret-free history.

13 / Deployment and run notes

The bot runs locally beside OBS; GitHub Pages documents it.

14 / Testing and QA notes

Tests focus on risky Twitch/OBS failure modes.

The public repo includes pytest checks for config/bot logic: defaults, scanning, token refresh, OBS connection behavior, commands, playback scheduling, fallback paths, startup, and cleanup. GitHub Actions runs the suite on push and pull request.

15 / Screenshots and capture placeholders

Screenshots now, motion captures still pending.

Capture pending Chat vote confirmation

Capture pending OBS playback handoff

16 / Next improvements

What I would improve next

• Add a local operator dashboard that shows current movie, active votes, OBS connection health, Twitch token status, and upcoming playback timing.
• Add a dry-run mode that exercises chat commands and OBS calls against mocks without touching a live stream setup.
• Add structured JSON logs or metrics so long sessions can be reviewed without scanning free-form console output.
• Add a short GIF/screenshot capture set for the README and this case study to show the chat-to-OBS loop visually.