tmi-emote-parse

Load and parse Twitch, BTTV, FFZ and 7TV emotes and badges from messages for multiple channels.

⚠ This module is mainly designed to be integrated in a https://github.com/tmijs/tmi.js environment but can also be used as a standalone with limited features.

Table of Contents

• tmi-emote-parse
  • Table of Contents
  • Installation
  • Usage
    • Without tmi.js
    • With tmi.js
  • Documentation
    • Functions
      • emoteParser.setTwitchCredentials() 🆕
      • emoteParser.loadAssets()
      • emoteParser.getLoaded()
      • emoteParser.getLoadedDetailed() 🆕
      • emoteParser.getAllBadges()
      • emoteParser.getAllEmotes()
      • emoteParser.getEmotes()
      • emoteParser.getBadges()
      • emoteParser.replaceEmotes()
      • emoteParser.setDebug() 🆕
    • Events
      • Emotes
      • Badges
      • Loaded
      • Error 🔄
  • Community
  • Thanks for using the project! 💜

Installation

Install using npm:

npm install tmi-emote-parse

Usage

Without tmi.js

// 🟦 Require the Module
const emoteParser = require("tmi-emote-parse");


// 🟦 Set debug state and add event handlers (optional)
emoteParser.setDebug(true);
emoteParser.events.on("error", e => {
    console.log("Error:", e);
})


// 🟦 Register Twitch API credentials (ClientID and OAuth Token) needed for User-ID request
emoteParser.setTwitchCredentials("<ClientID>", "<OAuth>");


// 🟦 Now you can finally load emotes and badges for a specific channel to later parse/use
emoteParser.loadAssets("twitch");
emoteParser.loadAssets("twitchdev");

emoteParser.events.on("emotes", (event) => {

    // Get all BTTV & FFZ Emotes used on a channel
    console.log(emoteParser.getAllEmotes(event.channel));
    /* 
        [{
          name: 'KEKW',
          type: 'ffz',
          img: 'https://cdn.frankerfacez.com/emote/381875/4'
        }, ...] 
    */
})

emoteParser.events.on("badges", (event) => {

    // Get all Badges available on a channel
    console.log(emoteParser.getAllBadges(event.channel));
    /* 
        [{
          name: 'bits/1000',
          info: 'cheer 1000',
          img: 'https://static-cdn.jtvnw.net/badges/v1/0d85a29e-79ad-4c63-a285-3acd2c66f2ba/3'
        }, ...] 
    */
})

With tmi.js

// 🟦 Require the Module
const emoteParser = require("tmi-emote-parse");


// 🟦 Set debug state and add event handlers (optional)
emoteParser.setDebug(true);
emoteParser.events.on("error", e => {
    console.log("Error:", e);
})


// 🟦 Register Twitch API credentials (ClientID and OAuth Token) needed for User-ID request
emoteParser.setTwitchCredentials("<ClientID>", "<OAuth>");


// 🟦 Now you can finally load emotes and badges for a specific channel to later parse/use
emoteParser.loadAssets("twitch");
emoteParser.loadAssets("twitchdev");


// 🅾 The following part is the tmi.js integration
// (Documentation can be found here: https://github.com/tmijs/tmi.js)
const tmi = require("tmi.js");

client = new tmi.Client({
    options: {
        debug: false
    },
    connection: {
        reconnect: true,
        secure: true
    },
    identity: {
        username: /* Channel Bot Username */,
        password: /* Channel Bot OAuth */
    },
    channels: [ '#twitch', '#twitchdev' ] /* Channels to join with leading '#' */
});
client.connect().catch(console.error);


// 🅾 tmi.js message event handler (as of tmi.js v1.4.2)
client.on('message', (channel, userstate, message, self) => {

    // 🟦 Use the tmi-emote-parse module here
    // Replace Emotes with HTML in a given message for a specific channel
    console.log(emoteParser.replaceEmotes(message, userstate, channel, self));
    /* 
        -> message: 'I can see you ariW' 
        -> output:  'I can see you <img class="message-emote" src="https://cdn.betterttv.net/emote/56fa09f18eff3b595e93ac26/3x"/>'
    */
    
    // Return the badges the message author uses on a specific channel
    console.log(emoteParser.getBadges(userstate, channel));
    /* 
        [{
          name: 'premium/1',
          info: 'Prime Gaming',
          img: 'https://static-cdn.jtvnw.net/badges/v1/bbbe0db0-a598-423e-86d0-f9fb98ca1933/3'
        }, ...] 
    */
});

Documentation

Functions

emoteParser.setTwitchCredentials()

Set Twitch API credentials for User-ID requests on the Twitch Helix API endpoint. (Void)

Parameters:

• clientId: String - Twitch API clientId
• oauth: String - Twitch API OAuth token (matching the clientId)

emoteParser.setTwitchCredentials("<ClientID>", "<OAuth>");

emoteParser.loadAssets()

Load Emotes and Badges of a specific Twitch channel. (Void)

Parameters:

• channel: String - Channel name
• options: Object - Load only specific providers [Defaults to loading all] (optional)
  • options["bttv"]: Boolean - Load BetterTTV Emotes
  • options["ffz"]: Boolean - Load FrankerFaceZ Emotes
  • options["7tv"]: Boolean - Load 7TV Emotes

emoteParser.loadAssets("twitch");
emoteParser.loadAssets("twitchdev", { "bttv": true, "ffz": false, "7tv": false });

emoteParser.getLoaded()

Check the loaded status of all channels or one specific channel. (Object)

Parameters:

• channel: String - Channel name (optional)

console.log(emoteParser.getLoaded("twitch"));

Returns something like this:

{
  "twitch": { channel: 'twitch', emotes: true, badges: true }
}

emoteParser.getLoadedDetailed()

Check the loaded status of all channels or one specific channel. (Object)

Parameters:

• channel: String - Channel name (optional)

console.log(emoteParser.getLoadedDetailed("twitch"));

Returns something like this:

{
  "twitch": { channel: 'twitch', emotes: { "all": false, "bttv": { global: true, channel: true }, "ffz": { global: true, channel: true }, "7tv": { global: true, channel: false }}, badges: true }
}

emoteParser.getAllBadges()

Return all badges present in the chat for one specific channel. (Array)

Parameters:

• channel: String - Channel name

console.log(emoteParser.getAllBadges("twitch"));

Returns something like this:

[{
  name: 'bits/1000',
  info: 'cheer 1000',
  img: 'https://static-cdn.jtvnw.net/badges/v1/0d85a29e-79ad-4c63-a285-3acd2c66f2ba/3'
}, ...]

emoteParser.getAllEmotes()

Return all BTTV & FFZ emotes present in the chat for one specific channel. (Array)

Parameters:

• channel: String - Channel name

console.log(emoteParser.getAllEmotes("twitch"));

Returns something like this:

[{
  name: 'ariW',
  type: 'bttv',
  img: 'https://cdn.betterttv.net/emote/56fa09f18eff3b595e93ac26/3x'
}, ...]

emoteParser.getEmotes()

⚠ tmi.js only: Return all unique emotes in a single message. (Array)

Parameters:

• message: String - Chat message
• userstate: Object - Twitch userstate object (tmi.js)
  • userstate["badges-raw"]: String - User badges
  • ...
• channel: String - Channel name

console.log(emoteParser.getEmotes("LUL LUL", userstate, "twitch"));

Returns something like this:

[{
  code: 'LUL',
  img: 'https://static-cdn.jtvnw.net/emoticons/v2/425618/default/dark/3.0',
  type: 'twitch'
}]

emoteParser.getBadges()

⚠ tmi.js only: Return all badges a message author uses for one specific channel. (Array)

Parameters:

• userstate: Object - Twitch userstate object (tmi.js)
  • userstate["badges-raw"]: String - User badges
  • ...
• channel: String - Channel name

console.log(emoteParser.getBadges(userstate, "twitch"));

Returns something like this:

[{
  name: 'bits/1000',
  info: 'cheer 1000',
  img: 'https://static-cdn.jtvnw.net/badges/v1/0d85a29e-79ad-4c63-a285-3acd2c66f2ba/3'
}, ...]

emoteParser.replaceEmotes()

⚠ tmi.js only: Parses all legacy Twitch, BTTV and FFZ emotes to HTML in the message for one specific channel. (String)

Parameters:

• message: String - Chat message
• userstate: Object - Twitch userstate object (tmi.js)
  • userstate["emotes"]: Object - Used emotes in message
  • ...
• channel: String - Channel name

console.log(emoteParser.replaceEmotes("I can see you ariW", userstate, "twitch"));

Returns something like this:

'I can see you <img class="message-emote" src="https://cdn.betterttv.net/emote/56fa09f18eff3b595e93ac26/3x"/>'

emoteParser.setDebug()

Switch debug mode on/off - will impact error events (Debug mode default is off). (Void)

Parameters:

• active: Boolean - Debug mode state to set

emoteParser.setDebug(false);

Events

Emotes

Event fires after BTTV & FFZ emotes for any channel have finished loading. (Object)

Parameters:

• event: Object - Event
  • event.channel: String - Channel name

emoteParser.events.on("emotes", (event) => {
  console.log(event);
})

Returns something like this:

{ channel: 'twitchdev' }

Badges

Event fires after Twitch badges for any channel have finished loading. (Object)

Parameters:

• event: Object - Event
  • event.channel: String - Channel name

emoteParser.events.on("badges", (event) => {
  console.log(event);
})

Returns something like this:

{ channel: 'twitchdev' }

Loaded

Event fires after all badges and emotes for any channel have finished loading. (Object)

Parameters:

• event: Object - Event
  • event.channel: String - Channel name

emoteParser.events.on("loaded", (event) => {
  console.log(event);
})

Returns something like this:

{ channel: 'twitchdev' }

Error

Event fires iff debug mode is enabled and any error on load occurs for any channel. (Object)

Parameters:

• event: Object - Event
  • event.channel: String - Channel name
  • event.error: String - Error message

emoteParser.events.on("error", (event) => {
  console.log(event);
})

Returns something like this:

{ channel: 'twitchdev', error: 'Failed to load FFZ global emotes for twitchdev' }

Community

• Follow @SmileFXOfficial on Twitter, SmileFXOfficial on Twitch.
• Found a bug: Submit an issue.
• Support my work and buy me a coffee.
• Discussion and news about tmi-emote-parser: Join the Discord.

Thanks for using the project! 💜