Skip to main content

A Quick Example: Live Stream Alert

A quick example to get used to setting up detectors and asking good questions: set up a monitor on a live stream.


  • Groundlight SDK with Python 3.7 or higher
  • The video ID of a YouTube live stream you'd like to monitor


Ensure you have Python 3.7 or higher installed, and then install the Groundlight SDK and OpenCV library:

pip install groundlight pillow ffmpeg yt-dlp typer

Creating the Application

  1. Save this command as a shell script

ffmpeg -i "$(yt-dlp -g $1 | head -n 1)" -vframes 1 last.jpg -y

This will download the most recent frame from a YouTube live stream and save it to a local file last.jpg.

  1. Log in to the Groundlight application and get an API Token.

  2. Next, we'll write the Python script for the application.

import os
import subprocess
import typer
from groundlight import Groundlight
from PIL import Image

def main(*, video_id: str = None, detector_name: str = None, query: str = None, confidence: float = 0.75, wait: int = 60):
Run the script to get the stream's last frame as a subprocess, and submit result as an image query to a Groundlight detector
:param video_id: Video ID of the YouTube live stream (the URLs have the form<VIDEO_ID>)
:param detector_name: Name for your Groundlight detector
:param query: Question you want to ask of the stream (we will alert on the answer of NO)
gl = Groundlight()
detector = gl.create_detector(name=detector_name, query=query, confidence_threshold=confidence)

while True:
p =["./", video_id])
if p.returncode != 0:
raise RuntimeError(f"Could not get image from video ID: {video_id}. Process exited with return code {p.returncode}.")

image ="last.jpg").convert("RGB")
response = gl.submit_image_query(detector=detector, image=image, wait=wait)

if response.result.label == "NO":
os.system("say 'Alert!'") # this may not work on all operating systems

if __name__ == "__main__":

  1. Save the script as in the same directory as above and run it:
python <VIDEO_ID> --detector_name <DETECTOR_NAME> --query <QUERY IN QUOTATION MARKS>