{"id":16060878,"url":"https://github.com/geerlingguy/obs-task-list-overlay","last_synced_at":"2025-03-16T08:32:05.423Z","repository":{"id":37608214,"uuid":"343204738","full_name":"geerlingguy/obs-task-list-overlay","owner":"geerlingguy","description":"An HTML and Node.js-based task list overlay for OBS.","archived":false,"fork":false,"pushed_at":"2023-07-10T23:08:40.000Z","size":144,"stargazers_count":129,"open_issues_count":1,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-27T05:51:24.538Z","etag":null,"topics":["checklist","css","html","nodejs","obs","open-broadcaster-software","overlay","streamlabs","task-list","todo-list"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geerlingguy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"geerlingguy","patreon":"geerlingguy"}},"created_at":"2021-02-28T20:14:06.000Z","updated_at":"2025-01-27T21:06:16.000Z","dependencies_parsed_at":"2022-07-20T12:32:34.820Z","dependency_job_id":null,"html_url":"https://github.com/geerlingguy/obs-task-list-overlay","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fobs-task-list-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fobs-task-list-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fobs-task-list-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geerlingguy%2Fobs-task-list-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geerlingguy","download_url":"https://codeload.github.com/geerlingguy/obs-task-list-overlay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806070,"owners_count":20350775,"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":["checklist","css","html","nodejs","obs","open-broadcaster-software","overlay","streamlabs","task-list","todo-list"],"created_at":"2024-10-09T04:06:56.202Z","updated_at":"2025-03-16T08:32:05.098Z","avatar_url":"https://github.com/geerlingguy.png","language":"JavaScript","funding_links":["https://github.com/sponsors/geerlingguy","https://patreon.com/geerlingguy"],"categories":[],"sub_categories":[],"readme":"# OBS Task List / Checklist Overlay\n\n[![CI](https://github.com/geerlingguy/obs-task-list-overlay/actions/workflows/ci.yml/badge.svg?branch=master\u0026event=push)](https://github.com/geerlingguy/obs-task-list-overlay/actions/workflows/ci.yml)\n\nAn HTML and Node.js-based task list overlay for OBS.\n\n\u003cimg src=\"https://raw.githubusercontent.com/geerlingguy/obs-task-list-overlay/master/example.jpg\" width=\"700\" height=\"394\" alt=\"OBS Task List Overlay Example with Jeff Geerling\" /\u003e\n\nI was frustrated with the lack of plugins that added a simple task list (with current task highlighted) to OBS, so I built this solution, which relies on OBS' 'Browser' source.\n\nThere are three components to this project:\n\n  1. An HTML file (`index.html`), which lays out a stream title and task list/current status overlay.\n  2. A Node.js HTTP server (`server.js`), which serves the HTML file to OBS, and allows you to control which step is highlighted in the display.\n  3. A config file (`config.json`), which provides the server settings, title settings, and task list content.\n\nI'm using this for a technical live stream, where I have a set list of milestones, and I want to indicate to viewers which task is currently being worked on.\n\nTo see it in practice, check out my [16 Drives, 1 Pi](https://www.youtube.com/watch?v=afnszOuWt74) livestream.\n\nThe design is inspired by the [NASASpaceflight](https://www.youtube.com/c/NASASpaceflightVideos) live stream status overlay, which I enjoy for it's simplicity and elegance.\n\n## Customizing the overlay\n\nAll the styling for the overlay is embedded in the `index.html` file. If you want to tweak the appearance, it should be easy enough if you know basic CSS + JS.\n\nTo set a title and set up the list of tasks, copy the `example.config.json` file to `config.json`, and then edit the file to add in the settings you would like.\n\nIf you change the length of the stream title (`task_list_title`), you may also need to adjust the `task_list_title_width` to match the new width of the title text.\n\n## Node.js App setup\n\nAfter you add your own task list and title, you need to get the Node.js server app running.\n\nFirst, [install Node.js](https://nodejs.org/en/download/) on your computer.\n\nNext, run the following command in this directory to install the app's dependencies:\n\n```\nnpm install\n```\n\nThen start the local server:\n\n```\nnode server.js\n```\n\nYou can open the overlay in a regular web browser by visiting `http://localhost:8080/`, but note that the element sizes and spacing will differ from what is output in OBS.\n\nAlways use OBS as the final reference for how things will look during a stream!\n\n## Using Docker Compose\n\nTo use the Docker images configured with compose, you need [docker-compose](https://docs.docker.com/compose/install/). Once it's up a running, you simply do\n\n```\ndocker-compose up --detach\n```\n\nTo stop the server\n\n```\ndocker-compose down\n```\n\nThe config maps container's `8080` port to `localhost:8080`. If you need to use another localhost port, you need to change it in `docker-compose.yml` under the `ports` section. For example, to use the port `3000` you need to set the section as:\n\n```yaml\n    ports:\n      - \"3000:8080\"\n```\n\nThe port number after the colon would be the port configured in `config.json`.\n\n## Adding the browser source in OBS\n\n  1. In an OBS Scene, add a new 'Browser' Source.\n  2. For the URL, enter `http://localhost:8080/` (use the port you have configured in `config.json`).\n  3. Set the width to `1920` and height to `1080`.\n  4. Check the 'Refresh browser when scene becomes active' option.\n  5. Click 'OK', and the overlay should appear.\n\n## Advancing to the next step\n\nTo control which task is highlighted, there are two paths the Node.js app responds to:\n\n```\n/up - Increase the current step by 1\n/down - Decrease the current step by 1\n```\n\nYou can also check what the current step is by requesting `/current`.\n\nWhen you have the browser source open, OBS will change the highlighted step within one second of you requesting `localhost/up` or `localhost/down`.\n\nThe count can increase above the maximum number of items in your list, or below `1`, so you are responsible for making sure you don't go crazy calling `/up` or `/down` too many times :)\n\n### Using an Elgato Stream Deck to advance steps\n\nI use a Stream Deck to help with my live streaming, and I've created two buttons for this overlay, a 'back' (`/down`) and 'forward' (`/up`) key.\n\nWhen I press the back button, the task list goes back one step.\n\nWhen I press the forward button, the task list goes forward one step.\n\nTo add a hotkey in the 'Configure Stream Deck' app, drag a 'Website' button from the 'System' section into one of the slots on your Stream Deck.\n\nThen set the URL to `http://localhost/up` (or `/down`), and check 'Access in background'.\n\nNow, when you press that key, the appropriate URL is called silently and the on-screen task list should advance or go back a step depending on the button you pressed. Magic!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeerlingguy%2Fobs-task-list-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeerlingguy%2Fobs-task-list-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeerlingguy%2Fobs-task-list-overlay/lists"}