DOCSEARCHbyAlgolia
Submit Docs

BetterTTV Documentation

repository·master·Indexed 21 days ago

https://github.com/night/betterttv

BetterTTV is a browser extension that enhances Twitch and YouTube with additional features, emotes, and UI improvements. This documentation covers the development environment setup using Vite and Node.js, ESLint configuration, and internal API actions for managing account subscription badges, username effects, and OAuth2 authentication. It also includes details on UI components such as LoaderIcon and the Scrollbar system for managing scrollbar dimensions via CSS variables.

Tokens
15.4K
Snippets
16
Records
99
Agent score
80%

What's inside BetterTTV

  1. Enable debug messages in the browser console

    master

    By default, BetterTTV does not output debug messages to the browser console. To enable them, you must set the consoleLog setting to true using the BetterTTV.settings.set method in your browser's JavaScript console.

    BetterTTV.settings.set('consoleLog', true);

  2. Use the BetterTTV development version on Twitch

    master

    To test your local changes on Twitch, you must use a userscript manager (like Tampermonkey) to load the local development build instead of the production extension.

    Important: You must disable the official BetterTTV extension in your browser to prevent conflicts and ensure only your local version is loaded.

    // ==UserScript==
// @name         BetterTTV Development
// @description  Enhances Twitch with new features, emotes, and more.
// @namespace    http://betterttv.com/
// @copyright    NightDev, LLC
// @icon         https://cdn.betterttv.net/assets/logos/bttv_logo.png
// @version      0.0.1
// @match        https://*.twitch.tv/*
// @match        https://*.youtube.com/*
// @grant        none
// ==/UserScript==

(function betterttv() {
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.src = 'http://127.0.0.1:2888/betterttv.js';
    const head = document.getElementsByTagName('head')[0];
    if (!head) return;
    head.appendChild(script);
})()

  3. Set up the BetterTTV development environment

    master

    To build and run BetterTTV locally, ensure you have Node.js installed. Follow these steps:

    1. Install Node.js.
    2. Navigate to the BetterTTV directory and run npm install to install dependencies.
    3. Start the development server by running npm start.

    Running npm start uses Vite to bundle files and templates into betterttv.js, which is served on port 2888. The server automatically rebuilds on file changes and reloads the page.

    npm install
npm start

  4. How the message sending patch works

    master

    The send_message module patches the Twitch chatConnectionAPI.sendMessage method to inject BetterTTV functionality.

    When a message is sent:

    1. It broadcasts the event via socketClient.broadcastMe for the current channel.
    2. It iterates through a list of registered handlers (chatTabCompletion, anonChat, and emojis) passing a SendState object.
    3. If any handler calls sendState.preventDefault(), the sending process is halted.
    4. If not prevented, the (potentially modified) message is passed to the original twitchSendMessage function.

    The SendMessagePatcher class ensures this patch is applied when the chat loads by watching for the load.chat event and using chatController.forceUpdate() to apply the changes to the Twitch UI.

  5. Emote Modifiers in BetterTTV chat

    master

    BetterTTV supports emote modifiers using specific prefixes or suffixes. These modifiers change the visual appearance of an emote (e.g., rotating, flipping, or adding space).

    Prefix Modifiers (e.g., w!):

    • w!: wide
    • h!: flip horizontal
    • v!: flip vertical
    • z!: zero space
    • c!: cursed
    • l!: rotate left
    • r!: rotate right
    • p!: party
    • s!: shake

    Suffix Modifiers (e.g., ffzW):

    • ffzW: wide
    • ffzX: flip horizontal
    • ffzY: flip vertical
    • ffzCursed: cursed

    Modifiers are enabled if the EMOTE_MODIFIERS flag is set in the EMOTES settings.

  6. Chat Tab Completion Module

    master

    The ChatTabcompletionModule provides enhanced chat input functionality for supported platforms (specifically Twitch). It enables:

    • Tab Completion: Pressing Tab while typing allows users to cycle through suggestions for emotes and usernames based on the current prefix.
    • Emote/User Prioritization: Suggestions can be ordered to prioritize emotes over users or vice versa via settings.
    • Message History: If the CHAT_MESSAGE_HISTORY flag is enabled, users can use ArrowUp and ArrowDown to navigate through previously sent or drafted messages in the chat input.
    • Escape to Cancel: Pressing Escape while cycling through tab completions reverts the input to its state before the completion attempt started.

    This module is automatically loaded for supported platforms using loadModuleForPlatforms.

  7. How ConversationsModule manages message parsing and styling

    master

    When a new message is detected via the watcher (event conversation.message), the ConversationsModule performs the following steps:

    1. User Color Application: It finds the username element using the .thread-message__message--user-name selector and applies a color calculated by chat.calculateColor(userColor).
    2. Message Replacement: It calls chat.messageReplacer on all elements matching the span[data-a-target="chat-message-text"] selector to process emotes or other text replacements.
    3. Emote Scroll Handling: It attaches load event listeners to images within the message. When an image (emote) finishes loading, it finds the nearest .simplebar-scroll-content container and scrolls it to the bottom (scrollHeight).

  8. Hide sidebar elements via SidebarFlags

    master

    The hide_sidebar_elements module allows users to hide specific sections and elements within the Twitch sidebar using the SettingIds.SIDEBAR setting. The visibility of these elements is controlled by specific flags within the sidebar settings object.

    Supported flags include:

    • SidebarFlags.RECENTLY_WATCHED_CHANNELS: Controls visibility of the 'Recently Visited' section.
    • SidebarFlags.RECOMMENDED_CHANNELS: Controls visibility of recommended channels.
    • SidebarFlags.SIMILAR_CHANNELS: Controls visibility of similar streamers.
    • SidebarFlags.RECOMMENDED_CATEGORIES: Controls visibility of recommended categories.
    • SidebarFlags.STORIES: Controls visibility of stories (applied via styles.hideStories on document.body).
    • SidebarFlags.OFFLINE_FOLLOWED_CHANNELS: When disabled, hides channel cards containing offline avatars (applied via styles.hideOfflineChannel).
    • SidebarFlags.AUTO_EXPAND_CHANNELS: When enabled, automatically clicks the 'Show More' button in the sidebar after a 1000ms delay.

  9. Access scrollbar dimensions via CSS variables

    master

    The Scrollbar component (and the useScrollbarSize hook) exposes the calculated scrollbar dimensions as CSS custom properties on the element itself. You can use these variables in your CSS to create responsive layouts that account for the scrollbar space.

    Available CSS variables:

    • --scrollbar-width: The width of the vertical scrollbar (e.g., 16px).
    • --scrollbar-height: The height of the horizontal scrollbar (e.g., 16px).

    If you use the ScrollbarSizeTargetContext, these variables are also propagated to the target element defined in the context.

  10. Configure AutoClaim settings

    master

    The AutoClaimModule behavior is controlled by the SettingIds.AUTO_CLAIM setting. To enable automatic claiming of drops, the setting must contain the AutoClaimFlags.DROPS flag.

    If the DROPS flag is removed from the AUTO_CLAIM setting, the module will stop listening for notification events.

  11. Configure Deleted Messages behavior

    master

    The chat_deleted_messages module allows users to control how deleted messages appear in the chat interface. The behavior is controlled via the SettingIds.DELETED_MESSAGES setting.

    Available modes defined by DeletedMessageTypes:

    • DeletedMessageTypes.HIDE: Completely hides the deleted message from the chat (display: none).
    • DeletedMessageTypes.SHOW: Shows the message but marks it with the bttv-chat-line-deleted CSS class, removes links (a.link-fragment), and removes clip cards (.chat-card).
    • DeletedMessageTypes.HIGHLIGHT: Shows the message with the bttv-chat-line-deleted class and applies highlighting via the ChatHighlightBlacklistKeywords module.

  12. Configure Anon Chat via settings

    master

    The Anon Chat module's behavior is controlled by the following settings keys:

    • SettingIds.ANON_CHAT: A boolean flag to enable or disable the anonymous chat feature.
    • SettingIds.ANON_CHAT_WHITELISTED_CHANNELS: A list of channels where Anon Chat should be active when ANON_CHAT is enabled.
    • SettingIds.ANON_CHAT_BLACKLISTED_CHANNELS: A list of channels where Anon Chat should be active when ANON_CHAT is disabled.

    The module calculates whether to part() (go anonymous) or join() (use current user) based on whether the current channel is present in the relevant channel list.