{"id":29543956,"url":"https://github.com/hpcbot/twitch-overlay","last_synced_at":"2025-07-17T14:09:28.507Z","repository":{"id":83141356,"uuid":"88114561","full_name":"hpcbot/twitch-overlay","owner":"hpcbot","description":"Animated overlay for Twitch streamers that can be loaded into OBS or XSplit","archived":false,"fork":false,"pushed_at":"2018-03-05T05:52:38.000Z","size":1135,"stargazers_count":26,"open_issues_count":5,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-11T20:48:44.835Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/hpcbot.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":"2017-04-13T02:05:02.000Z","updated_at":"2024-06-26T01:01:45.000Z","dependencies_parsed_at":"2023-03-20T02:36:46.821Z","dependency_job_id":null,"html_url":"https://github.com/hpcbot/twitch-overlay","commit_stats":null,"previous_names":["bdickason/twitch-overlay"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hpcbot/twitch-overlay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpcbot%2Ftwitch-overlay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpcbot%2Ftwitch-overlay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpcbot%2Ftwitch-overlay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpcbot%2Ftwitch-overlay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hpcbot","download_url":"https://codeload.github.com/hpcbot/twitch-overlay/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpcbot%2Ftwitch-overlay/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265614374,"owners_count":23798431,"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":[],"created_at":"2025-07-17T14:09:24.019Z","updated_at":"2025-07-17T14:09:28.501Z","avatar_url":"https://github.com/hpcbot.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# twitch-overlay\nAnimated overlays for Twitch streamers that can be loaded into OBS or XSplit\n\nThis library will add an express-based server that listens for events (via a simple EventEmitter) and plays overlays when it receives an event. You can load the default URL '/' into your OBS/Xsplit client which will render overlays with a transparent background.\n\nYou can pair this with lots of other modules such as [hpc-bot](https://github.com/bdickason/hpc-bot) to integrate with a chat bot or [twitch-soundboard]() to play overlays manually via your browser.\n\n# Installation\n\n1. Include the module in your codebase: `var Overlays = require('twitch-overlay');`\n1. Define any optional settings `var options = {};` (see **Config** below)\n1. Start the overlay server: `overlays = new Overlays(options);`\n\n## Config\n\nThe `constructor()` function accepts the following optional parameters via a single json object:\n````\n    var options = {\n        hostname: 'localhost',                      // Binds server to this host (optional)\n        port: 3000,                                 // Binds server to this port\n        directory: '/',                             // URL you want to point OBS/Xsplit at (optional, default: '/')\n        events: new Events.EventEmitter()           // Listens to events to trigger overlays\n    };\n````\n\n# Usage\n\n## Types of Overlays\n\nFirst, you should decide what type of overlay you want to display on your stream. The basic types are `text`, `video`, or `html` (see 'Modules' below for more details). The easier overlay to get started with is video which just takes a single mp4 file and a name as a parameter.\n\n## Adding Overlays `add(overlay)` or event: `overlays:add`\n\nTo add an overlay, you need to pass a json object (or array of objects) with the following parameters:\n\n**Example video overlay:**\n````\nvar overlay = {\n  name: 'butterbeer',\n  type: 'video',\n  file: 'events/beer.mp4''\n}\noverlays.add(overlay);\n\nevents.emit('overlay:butterbeer:show');\n````\n\n**Example text overlay**\n````\nvar overlay = {\n  name: 'text',\n  type: 'text'\n}\noverlays.add(overlay);\n\nevents.emit('overlay:text:show', 'text to say goes here!');\n````\n\n**Example html overlay:**\n````\nvar overlay = {\n  name: 'quidditch',\n  type: 'html',\n  view: './views/quidditch.html',\n  static: './js/'\n}\noverlays.add(overlay);\n\nevents.emit('overlay:quidditch:show');\n````\n\nOverlays will be added to an array and stored with a set of event listeners (See below: Firing Overlays). Each type has an associated React client-side template that is rendered when you want to display the overlay. The overlay server maintains a persistent state variable that is passed to react which keeps track of what is on screen and off screen at any given time.\n\nSee a fully functional example here: https://github.com/bdickason/dumbledore\n\n## Firing Overlays `show()` or `overlays:name:show`\n\nWhen an overlay is added to the server, it automatically has an event listener created in the format: `overlay:(name):show` where (name) is the name of the overlay that you passed in.\n\nTo trigger an overlay, just emit this event to the EventEmitter you passed in and the overlay will play on the server. Most overlays end automatically when they complete (i.e. video) but some such as html events do not have a fixed endpoint and listen for custom events from the client. If you have a custom event, use `io.socket.emit('endOverlay', null, (name), (payload))` where (name) is the name of your overlay and (payload) is any additional data you want to pass along. When the server retrieves this, it will relay the event to your EventEmitter in the format: `overlay:(name):end(payload)` so you can listen for this and act accordinly.\n\n## Removing Overlays `remove(overlay)` or `overlays:name:remove`\n\nIf you want to remove an existing overlay entirely, you can issue the remove() command.\n\nTo add an overlay, you need to pass a json object (or array of objects) with the `name` parameter. This allows you to pass in an existing overlay object (like you would with `add()`) or create a new object that specifies the name.\n\n*Note: This does not remove the overlay from state in case one is currently playing*\n\n## Hiding Overlays `hide()` or `overlays:name:hide`\n\nIf you want to manually hide an overlay rather than waiting for it to complete, you can issue the hide() command.\n\n\n## Displaying Overlays on your Stream (Adding to OBS/Xsplit)\n\nIn order for overlays to display in your OBS or Xsplit client, you need to do the following:\n\n**OBS**\n1. Click the '+' under Sources\n2. Add a BrowserSource\n3. Point it at http://(yourhostname):(yourport)/(yourdirectory). The default is http://localhost:3000\n4. Adjust the width/height to be 16:9\n5. Click 'Ok' to Save\n\nAfter you've added the source (and made sure it's visible and on top of your stream), you should start seeing overlays show up. They show up with a transparent background so you won't see anything visible until you start triggering overlays.\n\n## Running Tests\n\nYou can run tests to verify that everything is working with the command `npm test`. This requires **mocha** to be installed with `npm install -g mocha`.\n\nIf you plan to submit pull requests, please ensure that the request includes proper test coverage of your feature.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpcbot%2Ftwitch-overlay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhpcbot%2Ftwitch-overlay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpcbot%2Ftwitch-overlay/lists"}