START HERE
Set ENABLE_OBS to False for a browser-only test, then follow the last console message: browser launch, playlist discovery, eligible-playlist selection, or playback. If Chrome plays correctly but OBS is silent or blank, troubleshoot capture rather than the playlist selector.
Preserve the failure and isolate the browser
Write down the last console message, the player revision, and whether Chrome remains open. Close duplicate player copies before retrying. The checks below follow source revision d7c72fe; older copies may not have all these messages or configuration options.
Stop the helper, save config.py, set ENABLE_OBS = False, and start it again with uv run main.py. This isolates browser behavior from OBS connection retries and restart automation. If you are broadcasting, move to a holding scene first and confirm OBS's state separately; closing the helper is not a command to end the broadcast.
When Chrome does not reach a usable page
Confirm Google Chrome is installed and can open normally. If the console explicitly reports a Chrome/driver version mismatch, update Chrome through its normal updater, close the player-controlled browser, and try once more. Do not download a random replacement driver from a search result.
Run from the extracted project directory so you are editing and launching the same copy. Keep its profile folder writable. With PAUSE_FOR_BROWSER_LOGIN = True, a stationary terminal can simply be waiting for you to finish setup and press Enter. Inspect the opened browser for a consent or sign-in screen before treating that pause as a crash.
Keep screenshots of the failure free of account details. Do not delete the profile as a first step: that changes saved login state and can turn one failure into two.
When no eligible playlist is selected
| Last stage | What to inspect |
|---|---|
| Opening the playlists page | Confirm PLAYLISTS_LOCATION points to a page that this browser session can actually view. |
| Scrolling the playlists page | Check for consent, sign-in, an offline page, or a visible load failure before assuming there are no playlists. |
| Zero playlists discovered | Open the configured page manually in the same controlled Chrome window and confirm playlist links exist. |
| No different eligible playlist available | Compare the discovered set with PLAYLIST_BLACKLIST and the playlist just played. |
The selector avoids consecutive repeats. With one remaining eligible playlist, waiting after it finishes is expected. Blacklisting a URL containing a playlist's list= ID excludes that playlist even if the URL also points to an individual video. For a small reproducible test, use two visible, accessible playlists and an empty blacklist, then restore your exclusions.
When a playlist opens but does not progress
Watch the selected page itself. Distinguish an unavailable video, sign-in requirement, buffering indicator, paused player, and a page that has not produced its playback controls. These are different failures and should not all be treated by changing OBS.
The current player waits for playback metadata, monitors actual completion, and attempts bounded recovery when playback cannot start or advance. A manual pause after playback has started is intentionally left alone. Resume it yourself for the test. A timeout followed by another attempt is different from the program exiting.
If the selected playlist contains an inaccessible item, test a different playlist you can play normally in the same browser. Keep the failing URL and console stage for a report, but do not publish private playlist links or browser-profile data. YouTube page changes can break automation; reproducing the specific stage is more useful than repeatedly clearing every setting.
When Chrome works and OBS does not
A successful browser-only run narrows the problem. Re-enable OBS integration only after verifying OBS_HOST, OBS_PORT, and the authenticated server password. A connection message confirms control access; it does not prove a scene captures Chrome video or sound.
If the stream restarts when you meant to stop, inspect both restart policies. Disable RESTART_ON_UNEXPECTED_END for manual shutdown control; RESTART_INTERVAL = -1 only disables scheduled restarts. Restart the helper after changing configuration. The reviewed OBS monitor eventually stops automatic retrying after repeated transition failures and waits for a manual restart; inspect OBS rather than launching a second helper.
Use one repeatable acceptance test
Run the same two short playlists through a complete transition. Make an OBS recording with one clear audio route, confirm no unrelated browser window appears, then stop the helper and inspect the final OBS state. Restore the intended blacklist and restart policies only after this test works.
A useful issue report includes the revision, operating system, Chrome version, last stage, whether browser-only mode works, and one sanitized example URL if it is public. This gives the maintainer a concrete playback case without exposing saved credentials or requiring a paid live-stream experiment.
Sources & version notes
Documentation checked November 18, 2026. Use the platform and version notes in this guide when comparing settings. The troubleshooting checks are intended for your own setup; this review date does not represent hardware testing.