{"id":50896084,"url":"https://github.com/phenibut645/balkon-obs-agent","last_synced_at":"2026-06-16T00:01:58.138Z","repository":{"id":354649714,"uuid":"1224322257","full_name":"phenibut645/balkon-obs-agent","owner":"phenibut645","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-29T12:04:16.000Z","size":303,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T14:12:16.214Z","etag":null,"topics":["1000-7","balkon","electron","obs-websocket","typescript","zxc"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phenibut645.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T07:04:50.000Z","updated_at":"2026-04-29T12:13:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phenibut645/balkon-obs-agent","commit_stats":null,"previous_names":["phenibut645/balkon-obs-agent"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/phenibut645/balkon-obs-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenibut645%2Fbalkon-obs-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenibut645%2Fbalkon-obs-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenibut645%2Fbalkon-obs-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenibut645%2Fbalkon-obs-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phenibut645","download_url":"https://codeload.github.com/phenibut645/balkon-obs-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenibut645%2Fbalkon-obs-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34385031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["1000-7","balkon","electron","obs-websocket","typescript","zxc"],"created_at":"2026-06-16T00:01:57.770Z","updated_at":"2026-06-16T00:01:58.132Z","avatar_url":"https://github.com/phenibut645.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balkon OBS Agent\n\nBalkon OBS Agent is the local desktop bridge between the Balkon backend/relay and the streamer's local OBS Studio instance.\n\nIt is part of the Balkon ecosystem:\n\n- `phenibut645/balkon` — Discord bot, backend API, MySQL database, migrations and OBS relay\n- `phenibut645/balkon-website` — Next.js dashboard and Streamer Studio UI\n- `phenibut645/balkon-obs-agent` — this repository, local Windows desktop agent for OBS Studio\n\nThe agent is intended for streamers. They do **not** need to clone the main bot/backend repository or install database dependencies. They only run the packaged desktop app, connect it to the relay, and connect it to their local OBS Studio WebSocket server.\n\n---\n\n## Role in the System\n\nOBS Studio runs on the streamer's own PC. The backend and Discord bot usually run on a remote server. Directly exposing a local OBS WebSocket port to the internet would be unsafe and unreliable.\n\nBalkon therefore uses an outbound relay model:\n\n```text\nBalkon Website / Discord bot\n      ↓\nBalkon backend API / command queue\n      ↓\nBalkon OBS relay\n      ↓ outbound WebSocket\nBalkon OBS Agent on streamer PC\n      ↓ local WebSocket\nOBS Studio ws://127.0.0.1:4455\n```\n\nThe agent connects outward to the relay and then controls OBS locally. This avoids router/NAT problems and prevents the public exposure of the OBS WebSocket port.\n\n---\n\n## Main Features\n\n- Connects to the Balkon OBS relay with Agent ID and Agent Token\n- Connects to local OBS Studio through obs-websocket\n- Executes OBS commands sent by the backend/relay\n- Reports relay and OBS connection status\n- Shows recent events/logs in the UI\n- Supports English, Russian and Estonian UI languages\n- Runs in the Windows system tray\n- Supports auto-connect and OBS auto-retry behavior\n- Supports packaged Windows releases and GitHub Release auto-updates\n- Masks token/password inputs and avoids printing full secrets in logs\n\n---\n\n## Install for Development\n\n```powershell\nnpm install\n```\n\n---\n\n## Run in Development\n\n```powershell\nnpm run dev\n```\n\nAuto-update behavior is not active in development mode. It is intended for packaged builds.\n\n---\n\n## Build\n\n```powershell\nnpm run build\n```\n\n---\n\n## Package Windows App\n\n```powershell\nnpm run dist\n```\n\nThe packaged installer is written to:\n\n```text\nrelease/\n```\n\nDo not commit generated release artifacts into Git.\n\nIgnored/generated artifacts include:\n\n```text\nrelease/\ndist/\nwin-unpacked/\n*.exe\n```\n\n---\n\n## Enable OBS WebSocket\n\nBefore using the agent, OBS Studio must have the WebSocket server enabled.\n\n1. Open OBS Studio.\n2. Go to:\n\n```text\nTools -\u003e WebSocket Server Settings\n```\n\n3. Enable the WebSocket server.\n4. Use the default port:\n\n```text\n4455\n```\n\n5. Set a password if desired, or leave it empty for local testing.\n6. Keep OBS Studio open while testing agent commands.\n\nDefault local OBS WebSocket URL:\n\n```text\nws://127.0.0.1:4455\n```\n\n---\n\n## Get Agent Credentials\n\nCredentials are generated from the Balkon system, normally through the website Streamer Studio or Discord streamer commands.\n\nLegacy Discord command flow:\n\n```text\n/streamer register nickname:\u003cnickname\u003e primary:true\n/streamer agent_pair nickname:\u003cnickname\u003e\n```\n\nThe website Streamer Studio can also show/generate the Agent ID and token through OBS Agent setup screens, depending on the current backend/dashboard configuration.\n\nImportant:\n\n- Agent Token is sensitive.\n- Do not share real Agent Tokens in screenshots or commits.\n- In streamer/demo mode, token-like values should be hidden or masked.\n\n---\n\n## App Configuration\n\nEnter these values in Balkon OBS Agent:\n\n| Field | Description |\n|---|---|\n| Relay URL | WebSocket URL of the Balkon OBS relay |\n| Agent ID | Agent identifier generated by Balkon |\n| Agent Token | Secret pairing token generated by Balkon |\n| OBS WebSocket URL | Local OBS WebSocket URL, usually `ws://127.0.0.1:4455` |\n| OBS WebSocket Password | Optional OBS WebSocket password |\n\nProduction relay example:\n\n```text\nwss://venomancer.aleksandermilisenko23.thkit.ee/\n```\n\nLocal OBS example:\n\n```text\nws://127.0.0.1:4455\n```\n\nAfter filling values:\n\n1. Click **Save**.\n2. Click **Connect**.\n3. Use **Test OBS** to check local OBS connectivity.\n\n---\n\n## Runtime Flow\n\n### Agent connection\n\n```text\nagent starts\n→ loads saved config\n→ connects to Balkon relay\n→ sends hello with agentId and agentToken\n→ relay validates credentials\n→ relay accepts connection\n→ agent status becomes online\n```\n\n### OBS command execution\n\n```text\nbackend queues/sends OBS command\n→ relay forwards command to connected agent\n→ agent executes command against local OBS WebSocket\n→ agent returns command result\n→ backend/dashboard can display success or failure\n```\n\nCommon command categories:\n\n- get OBS status\n- list scenes\n- switch scene\n- list scene items/sources\n- set source visibility\n- update text source\n- trigger media input action\n- show configured OBS media/effects\n\n---\n\n## UI Tabs and Localization\n\nThe agent has a tabbed UI.\n\n### Tabs\n\n| Tab | Purpose |\n|---|---|\n| Main | Connection settings, relay/OBS status and recent event log |\n| Settings | Behavior options, language selection and update controls |\n| Changelog | Release history and notable changes |\n\n### Supported languages\n\n- English\n- Русский\n- Eesti\n\nLanguage selection is saved locally and applied without requiring an app restart.\n\n---\n\n## Background / Tray Mode\n\nBalkon OBS Agent is designed to run as a tray application.\n\n### Close vs Quit\n\n| Action | Result |\n|---|---|\n| Close window | Hide to tray, agent keeps running |\n| Quit from tray | Fully exit and disconnect |\n\n### Tray context menu\n\n| Item | Action |\n|---|---|\n| Open | Show the main window |\n| Connect | Connect to the relay using saved config |\n| Disconnect | Disconnect from relay |\n| Check for Updates | Check GitHub Releases for a new version |\n| Quit | Disconnect and exit |\n\n### Behavior settings\n\n| Setting | Description |\n|---|---|\n| Start with Windows | Register app as a login item so it starts with Windows |\n| Start minimized to tray | Start hidden in the system tray |\n| Auto-connect on launch | Connect to relay automatically if credentials are saved |\n| Auto-retry OBS connection | Retry local OBS connection every few seconds when OBS is not available |\n\nAuto-retry logs only the first retry attempt to avoid log spam.\n\n---\n\n## Testing Checklist\n\nUse this checklist after changing relay, OBS or packaging behavior.\n\n```text\n[ ] npm install completed\n[ ] npm run build passes\n[ ] npm run dev starts the app\n[ ] OBS WebSocket is enabled in OBS Studio\n[ ] Relay URL is saved\n[ ] Agent ID and Agent Token are saved\n[ ] OBS WebSocket URL is saved\n[ ] Connect succeeds\n[ ] Test OBS succeeds\n[ ] Agent appears online in Balkon/Streamer Studio\n[ ] OBS scenes can be listed from website or bot\n[ ] OBS scene switching works\n[ ] OBS source visibility update works\n[ ] Media/effect command works if configured\n[ ] Closing window hides to tray\n[ ] Quit fully exits the app\n```\n\n---\n\n## Publish a Release\n\nBalkon OBS Agent uses GitHub Releases for auto-updates.\n\n### Patch release flow\n\n```powershell\nnpm version patch --no-git-tag-version\nnpm run dist\ngit add .\ngit commit -m \"chore: release v0.1.X\"\ngit push\n```\n\nThen create a GitHub Release:\n\n```text\nTag:   v0.1.X\nTitle: Balkon OBS Agent v0.1.X\n```\n\nUpload these files from `release/`:\n\n```text\nBalkon-OBS-Agent-Setup-0.1.X.exe\nBalkon-OBS-Agent-Setup-0.1.X.exe.blockmap\nlatest.yml\n```\n\nThe filename must be exactly:\n\n```text\nlatest.yml\n```\n\nAuto-updates will fail with a 404 if `latest.yml` is missing from the latest release.\n\nIf using Electron Builder direct publishing, set `GH_TOKEN` with release permissions and run:\n\n```powershell\nnpm run dist:publish\n```\n\n---\n\n## Troubleshooting\n\n### Previous build is stuck during installation\n\nClose the app first:\n\n```powershell\ntaskkill /IM \"Balkon OBS Agent.exe\" /F\n```\n\n### Agent connects to relay but OBS is unavailable\n\nCheck:\n\n- OBS Studio is open\n- OBS WebSocket server is enabled\n- port is `4455`\n- password matches the app configuration\n- local URL is `ws://127.0.0.1:4455`\n\n### Agent does not connect to relay\n\nCheck:\n\n- Relay URL is correct\n- Agent ID is correct\n- Agent Token is correct\n- token was not rotated/revoked\n- backend/relay is running\n- firewall/proxy does not block outbound WebSocket connections\n\n---\n\n## Security Notes\n\n- Never commit real Agent Tokens.\n- Never print full Agent Tokens in logs.\n- Do not expose OBS WebSocket directly to the public internet.\n- Prefer the relay + local agent model for production.\n- Store secrets only in local app configuration or backend-managed secure storage.\n\n---\n\n## Diploma / Demo Flow\n\nRecommended demonstration flow:\n\n1. Open OBS Studio and enable WebSocket.\n2. Start Balkon OBS Agent.\n3. Save Relay URL, Agent ID, Agent Token and OBS WebSocket URL.\n4. Connect the agent.\n5. Confirm agent online status in Balkon Website Streamer Studio.\n6. Open OBS control in the website.\n7. Refresh scenes and switch scenes.\n8. Trigger a source visibility or media action.\n9. Show OBS history in the website.\n\nThis demonstrates the complete chain:\n\n```text\nwebsite → backend → relay → OBS Agent → OBS Studio\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenibut645%2Fbalkon-obs-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphenibut645%2Fbalkon-obs-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenibut645%2Fbalkon-obs-agent/lists"}