TwitchLatencyGuard

TwitchLatencyGuard is a Chrome extension designed to help manage and reduce latency on Twitch streams. It detects high latency and automatically applies a user-defined method for fast-forwarding to the live edge—ensuring you stay as close to real-time as possible.

Important: Due to recent changes Twitch made to the channel metadata layout, FrankerFaceZ (FFZ) users must manually revert to an older layout variant for Playback Statistics to function in certain circumstances. See FrankerFaceZ Requirements below.

Features

• Real-Time Latency Detection: Monitors Twitch’s built-in latency metrics (exposed by FrankerFaceZ).
• User-Configurable Threshold: Automatically triggers fast-forward actions if latency exceeds your chosen threshold.
• Fast-Forward Methods:
  1. Seek to Live Edge (Default & Currently Recommended)
  2. Change Video Quality
  3. Reload Video Element
  4. Adjust Playback Rate
  5. Reinitialize Player

Table of Contents

1. Prerequisites
2. Installation
3. FrankerFaceZ Requirements
4. Usage
5. Configuration
6. Technical Overview
7. Contributing
8. License

---

Prerequisites

1. Google Chrome (or another Chromium-based browser supporting Manifest V3).
2. FrankerFaceZ (FFZ) extension installed.
   • Within FFZ, you must enable the Playback Statistics feature.

Installation

1. Clone or download this repository.
2. Open the Chrome Extensions page:
   • Navigate to chrome://extensions/ (or via More Tools → Extensions).
   • Enable Developer Mode (toggle in the top-right corner).
3. Click Load unpacked and select the folder containing manifest.json.

The extension will now appear in your extensions list as Twitch Latency Guard.

FrankerFaceZ Requirements

1. Make sure FrankerFaceZ is installed and Playback Statistics is enabled:

   • Go to FrankerFaceZ Control Center → Add-Ons → Playback Statistics → ensure it is On.
   • This ensures the extension can read the “Latency To Broadcaster” information from Twitch.

2. Switch the channel metadata layout if needed:

   • Open FrankerFaceZ Control Center → Experiments → find web_channel_metadata_layout.
   • Change the dropdown from variant 1 to control 1.
   • Twitch’s new default layout (variant 1) sometimes hides the Playback Statistics field. By forcing control 1, you restore the older layout where the extension can see the latency value.

Usage

• Seek to Live Edge is the only currently working or reliable method. Other methods may require additional testing or may be prone to breakage with future Twitch updates.
• If your latency crosses the threshold (default 1.5 seconds), the extension will attempt to bring you back to near real-time:
  1. Seek to Live Edge: Instantly jumps the video time to the latest available buffer.
  2. [Other methods may become stable or remain experimental in the future.]

Quick Start

1. Go to a Twitch channel with a live stream.
2. Ensure Playback Statistics is visible (see above instructions).
3. Access the extension’s popup by clicking the TwitchLatencyGuard icon in your browser toolbar.
4. Set your Latency Threshold (seconds).
5. Select your Fast Forward Method (we recommend Seek to Live Edge).
6. Click Save.

Now, when your latency climbs above the set threshold, TwitchLatencyGuard will automatically correct it.

Configuration

In the extension’s popup.html:

• Latency Threshold: The number of seconds of delay at which you consider your stream to be too far behind live.
• Fast Forward Method:
  • seek: Seeks the video to the live edge (recommended).
  • quality: Changes the video quality (and reverts it) to force a rebuffer.
  • reload: Reloads the video element.
  • speedup: Temporarily speeds up the video playback rate.
  • reinit: Reinitializes the entire Twitch player.

These settings are stored via Chrome’s chrome.storage.sync API so they remain consistent across your devices (if synced).

Technical Overview

• content.js:

  • Injected into every *.twitch.tv page.
  • Listens for Twitch’s built-in timeupdate events to measure latency (via FrankerFaceZ’s “Latency To Broadcaster” metric).
  • If latency exceeds the user’s threshold, triggers the selected fast-forward method.

• popup.js & popup.html:

  • Provide the user interface to configure the extension’s settings.
  • Persist settings via chrome.storage.sync.

• background.js:

  • Handles messages from content scripts requesting stored configuration.

• manifest.json:

  • Chrome Extension Manifest V3 specification.
  • Declares permissions, content scripts, and the extension’s metadata.

File-by-File

• content.js: Core logic, injection points, event handlers, fast-forward methods.
• popup.html: Simple HTML settings page (Latency threshold, method dropdown, etc.).
• popup.js: Manages the saving and loading of settings from chrome.storage.
• background.js: Service worker for handling asynchronous Chrome messages.
• styles.css: (Optional) Provide UI styling for the popup.

Contributing

1. Fork this repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

I welcome any improvements or bug fixes!

License

see Copyright-Disclaimer

---

Thank you for using TwitchLatencyGuard! I hope it helps keep your viewing experience smooth and latency-free.