{"id":24558127,"url":"https://github.com/rse/huds","last_synced_at":"2025-04-19T09:58:52.666Z","repository":{"id":44095327,"uuid":"248982371","full_name":"rse/huds","owner":"rse","description":"Head-Up-Display Server (HUDS)","archived":false,"fork":false,"pushed_at":"2024-12-20T21:56:49.000Z","size":2341,"stargazers_count":21,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T21:55:47.568Z","etag":null,"topics":["head-up-display","hud","obs-studio","overlay","rest","stream-deck","websocket"],"latest_commit_sha":null,"homepage":"http://npmjs.com/huds","language":"JavaScript","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/rse.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}},"created_at":"2020-03-21T13:32:25.000Z","updated_at":"2024-12-20T21:56:51.000Z","dependencies_parsed_at":"2024-06-19T20:02:41.767Z","dependency_job_id":"755a57b9-ef0b-4161-9070-056a04cc3e5a","html_url":"https://github.com/rse/huds","commit_stats":{"total_commits":185,"total_committers":1,"mean_commits":185.0,"dds":0.0,"last_synced_commit":"58e660e3ca56451b2040bfa632c419e4d8103987"},"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fhuds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fhuds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fhuds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fhuds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/huds/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249670023,"owners_count":21308669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["head-up-display","hud","obs-studio","overlay","rest","stream-deck","websocket"],"created_at":"2025-01-23T05:47:26.896Z","updated_at":"2025-04-19T09:58:52.647Z","avatar_url":"https://github.com/rse.png","language":"JavaScript","readme":"\nHUDS\n====\n\n**Head-Up-Display Server (HUDS)**\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/huds.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/rse/huds.png\" alt=\"\"/\u003e\n\nAbstract\n--------\n\nHUDS is a small server providing a\nWeb service for serving one or more HTML Single-Page Applications (SPA)\nwhich act as \"Head-Up-Displays (HUD)\" or \"Overlays\" in video\nproduction scenarios. It is specially intended to be used with [OBS Studio](https://obsproject.com/)'s\n[CEF](https://en.wikipedia.org/wiki/Chromium_Embedded_Framework)-based\n[Browser Source](https://obsproject.com/wiki/Sources-Guide#browsersource)\nand optionally the [Elgato Stream Deck](https://www.elgato.com/en/gaming/stream-deck)\nremote control device and its [System:Website](https://help.elgato.com/hc/en-us/articles/360028234471-Elgato-Stream-Deck-System-Actions) function.\n\nHUDS serves the static files of one or more HUD HTML5 SPAs, which\nrender the actual HUD display in OBS. It also provides a HUDS client API to\neach HUD HTML5 SPA for establishing a WebSocket connection back to HUDS.\nOver this WebSocket connection HUDS pushes events to each HUD which were\nreceived by HUDS either via WebSocket connections or REST endpoints.\nThe REST endpoint is intended to be used by arbitrary Web clients to\nsend events to any HUD. Usually, this is used with the Stream Deck\nSystem:Website plugin or with curl(1) on the command-line.\n\nHUDS itself is usually run ad-hoc and side-by-side to [OBS\nStudio](https://obsproject.com/) (under `localhost`) but also can be\ndeployed to a dedicated server by optionally requiring authentication\nand delivering one or more HUDs in parallel.\n\nInstallation\n------------\n\nInstall Node.js and then install HUDS globally into your system with:\n\n```\n$ npm install -g huds\n```\n\nUsage\n-----\n\nThe Unix manual pages\n[huds(8)](https://github.com/rse/huds/blob/master/src/huds-server.md)\n(for the server CLI) and\n[huds(3)](https://github.com/rse/huds/blob/master/src/huds-client.md)\n(for the client API) provide detailed usage information.\n\nExample\n-------\n\nRun a minimalistic [Hello World HUD](https://github.com/rse/huds-hud-hello/) with:\n\n```\n$ npx -p huds -p huds-hud-hello \\\n  huds -a 127.0.0.1 -p 9999 -d hello:@huds-hud-hello\n```\n\nFor a more elaborated HUD check out the [Training\nHUD](https://github.com/rse/huds-hud-training/). It supports performing\ntrainings as webinars and looks like this in practice:\n\n![screenshot](screenshot.jpg)\n\nArchitecture\n------------\n\nHUDS is based on a Client/Server architecture as illustrated in the\nfollowing diagram:\n\n![architecture](architecture.png)\n\nThe individual communication steps in the diagram are:\n\n1.  [HUDS](src/huds-server.js) reads the HUD configuration and converts its content from\n    YAML to JSON format for embedding into the HUDS (Client) Library.\n    See [training.yaml](https://github.com/rse/huds-hud-training/blob/master/training.yaml)\n    for an example of a HUD configuration.\n\n2.  OBS Studio's CEF-based Browser Source open the URL\n    `http://127.0.0.1:9999/\u003chud-id\u003e/[#\u003ckey\u003e=\u003cvalue\u003e,[...]]`\n\n3.  [HUDS](src/huds-server.js) delivers the HUD SPA with all its HTML/CSS/JS files.\n    The individual assets are served via\n    the HUDS URLs `http://127.0.0.1:9999/\u003chud-id\u003e/\u003casset\u003e`.\n    See [Hello World HUD](https://github.com/rse/huds-hud-hello/)\n    for an example of a simple HUD and\n    [Training HUD](https://github.com/rse/huds-hud-training/)\n    for an example of a more elaborated HUD.\n\n4.  The HUD SPA (in its `index.html`) references the [HUDS (Client) Library](src/huds-client.js) with:\n    `\u003cscript type=\"text/javascript\" src=\"huds\"\u003e\u003c/script\u003e`.\n\n5.  [HUDS](src/huds-server.js) delivers the [HUDS (Client) Library](src/huds-client.js) (and its embedded HUD configuration)\n    under virtual HUDS URL `http://127.0.0.1:9999/\u003chud-id\u003e/huds`.\n\n6.  The [HUDS (Client) Library](src/huds-client.js) opens a WebSocket connection back to [HUDS](src/huds-server.js)\n    under the HUDS URL `http://127.0.0.1:9999/\u003chud-id\u003e/events`.\n\n7.  An external program (like Elgato Stream Deck's System:Website\n    function or Node-RED's HTTP-Request or just cURL) triggers an event\n    with a HTTP GET request under the HUDS URL `http://127.0.0.1:9999/\u003chud-id\u003e/event/\u003cevent-name\u003e[?data=\u003cevent-data\u003e]`.\n    and with a HTTP POST request under the HUDS URL `http://127.0.0.1:9999/\u003chud-id\u003e/event/\u003cevent-name\u003e` and\n    with `\u003cevent-data\u003e` as the payload. In both cases, `\u003cevent-data\u003e` has to be a JSON string.\n\n8.  [HUDS](src/huds-server.js) forwards the received event to all instances of the HUD by\n    sending out the event to all HUD SPAs over their WebSocket\n    connections. Notice: a single HUD can be opened multiple times and\n    then all opened instances receive the event. This is useful to run a\n    HUD both in OBS Studio and in parallel in the browser on a control\n    notebook in case no dedicated Elgato Streak Deck remote control device is used.\n\n9.  Similary, even HUD SPAs are allowed to send events (to theirself or other\n    HUDs) over their WebSocket connection. This is useful to have a central\n    dashboard HUD which controls one or more actual video HUDs.\n\nLicense\n-------\n\nCopyright \u0026copy; 2020-2022 Dr. Ralf S. Engelschall (http://engelschall.com/)\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fhuds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Fhuds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fhuds/lists"}