# twitch-chat-emotes

> Read twitch and BTTV emojis used in twitch chat

Latest version **0.4.3** (published 2023-12-05) · ISC license · 0 weekly downloads

## Install

```sh
npm install twitch-chat-emotes
pnpm add twitch-chat-emotes
yarn add twitch-chat-emotes
bun add twitch-chat-emotes
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.3 |
| Published | 2023-12-05 |
| First published | 2020-07-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 23.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Maintainers | calebbabin |
| Keywords | twitch, bttv, better twitch tv, emotes, canvas |

## Links

- npm: https://www.npmjs.com/package/twitch-chat-emotes
- Repository: https://github.com/CalebBabin/twitch-chat-emotes
- Homepage: https://github.com/CalebBabin/twitch-chat-emotes#readme
- Issues: https://github.com/CalebBabin/twitch-chat-emotes/issues
- npm.io page: https://npm.io/package/twitch-chat-emotes

## Dependencies (1)

- [tmi.js](https://npm.io/package/tmi.js.md) ^1.8.5

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 0.4.3 (latest) — 2023-12-05
- 0.4.2 — 2023-01-30
- 0.4.1 — 2023-01-30
- 0.4.0 — 2023-01-30
- 0.3.3 — 2022-10-29
- 0.3.2 — 2022-10-29
- 0.3.1 — 2022-10-29
- 0.3.0 — 2022-10-29
- 0.2.6 — 2022-08-10
- 0.2.5 — 2022-07-12
- 0.2.4 — 2022-07-07
- 0.2.3 — 2022-07-03
- 0.2.2 — 2021-09-20
- 0.2.1 — 2021-06-27
- 0.1.34 — 2021-03-13
- … 27 more at https://npm.io/package/twitch-chat-emotes/versions

## README

# twitch-chat-emotes

Connects to twitch chat and emits emotes as they're typed in twitch chat.

Supports all twitch emotes, animated twitch emotes are now operational!

Supported third party emotes:

- BTTV (channel and global)
- 7TV (channel, all emotes are static/not animated)
- FFZ (channel)

> This is a library created specifically for projects that run in the browser and require BTTV GIF emote support for Canvas and WebGL instances.
>
> If you're looking for a more standard library to interact with twitch chat, you should look into [tmi.js](https://github.com/tmijs/tmi.js), which this library is based off of.

 

## Example implementation

```
yarn add twitch-chat-emotes
```

```js
import Chat from "twitch-chat-emotes";

// a default array of twitch channels to join
let channels = ["moonmoon"];

// the following few lines of code will allow you to add ?channels=channel1,channel2,channel3 to the URL in order to override the default array of channels
const query_vars = {};
const query_parts = window.location.href.replace(/[?&]+([^=&]+)=([^&]*)/gi, function (m, key, value) {
	query_vars[key] = value;
});
if (query_vars.channels) {
	channels = query_vars.channels.split(",");
}

// create our chat instance
const ChatInstance = new Chat({
	channels,
	duplicateEmoteLimit: 5,
});

// add the word "TEST" as a custom emote
ChatInstance.addCustomEmote("TEST", "https://example.com/image.png");

// add a callback function for when a new message with emotes is sent
ChatInstance.on("emotes", (emotes) => {
	console.log(emotes);
});
```

 

# External server dependency

An external API runs at `https://gif-emotes.opl.io/v2/`. Emotes are passed through this server in order to offload GIF processing from the client in an attempt to improve performance in an OBS browser source to avoid frame drops. _The server source code will be released at a later date so that users of the library can run it themselves if needed._

The API is heavily cached behind CloudFlare, and should withstand an unreasonable amount of traffic.

---

# Documentation

```js
const ChatInstance = new Chat({config...})
```

| Property                   | Description                                                                    |
| -------------------------- | ------------------------------------------------------------------------------ |
| `channels`                 | An array of twitch chat channels to connect to                                 |
| `maximumEmoteLimit`        | The limit of emotes per message                                                |
| `maximumEmoteLimit_pleb`   | `maximumEmoteLimit`, but for users who are not subscribed, mods, or VIPs       |
| `duplicateEmoteLimit`      | The maximum amount of times the same emote can be repeated in the same message |
| `duplicateEmoteLimit_pleb` | Similar to `maximumEmoteLimit_pleb`                                            |
| `gifAPI`                   | Define the location of your own self-hosted emote API                          |

 

## Events

```js
ChatInstance.on(event, callback)

...

ChatInstance.on("Emotes", (emotes, data) => {
	console.log(data.user.username + ': ' + data.message, emotes);
})
```

| Event | Description |
| - | - |
| `emotes` | Returns an array of emote objects every time a message is sent in twitch chat that contains matched emotes, an optional second argument contains message and user data |

## Objects

**Emote** | Property | Description | | - | - | | `url` | The "unique ID" of the emote, either it's name or a URL | | `name` | The name of the emote (Example: `Kappa`, `FeelsGoodMan`, `KomodoHype`) | | `canvas` | The emotes canvas, there is only one unique canvas element for each emote _(adding it multiple times in the DOM will just move it between elements)_ |

---
_Source: https://npm.io/package/twitch-chat-emotes · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._