How to Display Viewer Count in OBS Using Python

This guide provides a step-by-step walkthrough on how to configure a custom Python script inside OBS Studio to fetch and display live stream viewer counts using an external API. You will learn how to set up the Python environment in OBS, write a lightweight script to query an API, and configure the script settings to update a text source automatically on your stream overlay.

Step 1: Install and Link Python to OBS Studio

OBS Studio requires a local installation of Python to run custom scripts.

Install Python: Download and install Python from the official Python website. Ensure you install a 64-bit version of Python that matches your OBS installation (typically Python 3.10 or 3.11, as newer versions may occasionally have compatibility issues depending on your OBS release). During installation, check the box that says “Add Python to PATH”.
Link Python in OBS:
- Open OBS Studio.
- Navigate to Tools in the top menu and select Scripts.
- Go to the Python Settings tab.
- Click Browse and select your Python installation folder (e.g., C:/Users/YourUsername/AppData/Local/Programs/Python/Python310 on Windows).

Step 2: Create the Python Script

Create a new file on your computer named viewer_count.py and open it in a text editor. Paste the following code into the file:

import obspython as obs
import urllib.request
import json

# Global variables to hold user settings
api_url = ""
source_name = ""
update_interval = 30

def fetch_viewer_count():
    global api_url, source_name
    if not api_url or not source_name:
        return

    try:
        # Fetch data from the API
        req = urllib.request.Request(api_url, headers={'User-Agent': 'OBS-Script/1.0'})
        with urllib.request.urlopen(req, timeout=5) as response:
            data = json.loads(response.read().decode())
            
            # Extract viewer count (adjust 'viewers' based on your API's JSON structure)
            viewer_count = data.get('viewers', '0')
            
            # Update the OBS Text source
            update_obs_text(source_name, f"Viewers: {viewer_count}")
    except Exception as e:
        print(f"Error fetching viewer count: {e}")

def update_obs_text(source_name, text):
    source = obs.obs_get_source_by_name(source_name)
    if source is not None:
        settings = obs.obs_data_create()
        obs.obs_data_set_string(settings, "text", text)
        obs.obs_source_update(source, settings)
        obs.obs_data_release(settings)
        obs.obs_source_release(source)

# Define script description shown in OBS
def script_description():
    return "Fetches viewer counts from an external JSON API and displays them in a Text source."

# Define user-configurable settings in OBS GUI
def script_properties():
    props = obs.obs_properties_create()
    obs.obs_properties_add_text(props, "api_url", "API URL", obs.OBS_TEXT_DEFAULT)
    obs.obs_properties_add_text(props, "source_name", "Text Source Name", obs.OBS_TEXT_DEFAULT)
    obs.obs_properties_add_int(props, "interval", "Update Interval (seconds)", 5, 3600, 1)
    return props

# Apply settings when changed by the user
def script_update(settings):
    global api_url, source_name, update_interval
    api_url = obs.obs_data_get_string(settings, "api_url")
    source_name = obs.obs_data_get_string(settings, "source_name")
    new_interval = obs.obs_data_get_int(settings, "interval")

    if new_interval != update_interval:
        update_interval = new_interval
        obs.timer_remove(fetch_viewer_count)
        obs.timer_add(fetch_viewer_count, update_interval * 1000)

# Initialize script behavior on load
def script_load(settings):
    global update_interval
    obs.timer_add(fetch_viewer_count, update_interval * 1000)

Note: The script uses Python’s built-in urllib library to avoid external library dependencies like requests, which can fail to load inside the OBS environment.

Step 3: Prepare Your OBS Scene

Before loading the script, you must create a text element for the script to modify:

Under the Sources dock in OBS, click the + icon.
Select Text (GDI+) (Windows) or Text (FreeType 2) (Mac/Linux).
Name this source exactly what you plan to target (for example: Viewer_Count_Text).

Step 4: Load and Configure the Script in OBS

In OBS, go to Tools > Scripts.
On the Scripts tab, click the + icon in the bottom left.
Browse and select your viewer_count.py file.
Once loaded, the script properties will appear on the right side of the window:
- API URL: Enter the endpoint of your external API (e.g., https://api.yourstreamingservice.com/user/stats). Ensure this API returns a JSON format containing a "viewers" key.
- Text Source Name: Type the exact name of the text source you created in Step 3 (e.g., Viewer_Count_Text).
- Update Interval: Set how often you want the script to ping the API (30 seconds is standard to avoid API rate limiting).
Close the Scripts window. Your text source will now dynamically update with the live viewer count fetched from the API.