MovieBot / StreamCinema Vote Bot

01 / Summary

Chat votes become OBS playback.

MovieBot is a Python/TwitchIO control layer: chat updates vote state, local files provide the winner, and OBS WebSocket updates playback.

Why this matters

It turns stream chores into automation.

Production readiness

Bot flow works; stream ops need controls.

02 / What I built

Bot logic, OBS handoff, reliability, and support pages.

• Implemented Twitch commands for votes, results, current movie, time, movie lists, and help.
• Built movie scanning with extension filters, one-level subfolders, rescans, and local media validation.
• Built vote-state logic for changed votes, duplicates, partial matches, ties, and fallback selection.
• Connected OBS by verifying scenes/sources, updating media, switching scenes, and restarting playback.
• Added OAuth refresh, IRC health checks, reconnects, startup validation, logs, pytest, and support pages.

External pieces: TwitchIO, Twitch OAuth/chat, OBS WebSocket, IMDb links, posters, and local public-domain files.

03 / Problem

Manual stream control does not scale.

Manual voting distracts the streamer: count votes, resolve titles, pick a winner, update OBS, and recover when services drop.

MovieBot turns chat into input and OBS into output. Viewers get predictable commands; the streamer gets repeatable handoff and logs.

04 / Viewer flow

Viewer flow stays in Twitch chat.

1. Browse options Use Movie Library or !movies to see titles.
2. Vote by title Use !vote <movie name>; exact or clear partial matches work.
3. Check the room state !currentmovie, !time, and !results show state.
4. Change a vote Changing a title replaces the previous vote.
5. Watch the winner At poll end, OBS starts the winning local file.

05 / Streamer/operator flow

Operator sets config, then runs the loop.

1. Prepare Twitch credentials Set client ID/secret, tokens, and channel in local env settings.
2. Prepare OBS Enable OBS WebSocket and configure scene/source names.
3. Point at local media Set the folder containing public-domain video files.
4. Start the bot Run python bot.py. Startup validates settings, tokens, movies, OBS, and schedule.
5. Monitor logs Console and bot.log show OBS errors, token issues, chat recovery, and fallbacks.

06 / Tech stack

Python around Twitch, OBS, and local media.

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

Python handles commands, background routines, chat, OBS playback, duration checks, and private env config.

07 / Twitch command flow

Commands are validated before they change state.

08 / OBS playback flow

OBS handoff updates the media source.

Text fallback: TwitchIO routes chat to Python. The bot validates input, picks a local movie, updates OBS, and runs refresh/reconnect routines.

1. Verify OBS connection Connect to OBS, check scene, and verify media source.
2. Set the local file Normalize the selected path and send it to OBS.
3. Refresh the source Hide, update, show, switch scene, and restart the media input.
4. Retry before giving up Retry media loading; fall back to another movie 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 scanned and refreshed.

The bot scans configured movie folders for common video formats and one level of subdirectories, without following symlinks.

• Missing directories log an error and return an empty list.
• A 10-minute rescan refreshes the list and keeps the prior list if no files appear.
• Duration uses ffprobe, then MoviePy, then a default.

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 sessions need recovery paths.

12 / Setup and security notes

Credentials stay local.

• .env.example covers Twitch, movie directory, OBS, scene/source, and optional movie-list URL.
• README warns not to commit .env, tokens, secrets, passwords, or logs.
• Startup checks required Twitch settings and MOVIE_DIRECTORY.
• OBS WebSocket and scene/source names must match config.
• Committed credentials should be rotated before publishing clean history.

13 / Deployment and run notes

Runs locally beside OBS.

14 / Testing and QA notes

Tests target Twitch/OBS risks.

Public pytest checks cover config, scanning, token refresh, OBS calls, commands, scheduling, fallbacks, startup, and cleanup. GitHub Actions runs the suite.

15 / Screenshots

Browser surfaces around the bot.

16 / Next improvements

Next improvements

• Add an operator dashboard for movie, votes, OBS health, token status, and playback timing.
• Add dry-run mode for chat commands and OBS calls against mocks.
• Add structured logs or metrics for long sessions.