Skip to main content

A Quick Example: Live Stream Monitor

A quick example to help you get started with monitoring live streams using the groundlight/stream container.

In this example, we will set up a monitor on a live stream of a bird feeder and have Groundlight continuously answer whether a bird is present at the feeder.

Requirements​

Installation​

Pull the Groundlight Stream container:

docker pull groundlight/stream

Creating the Monitor​

The Groundlight Stream container makes it easy to monitor video streams. Here's how to use it:

  1. First, get (or create) your API token from the Groundlight dashboard. Set your Groundlight API token as an environment variable:
export GROUNDLIGHT_API_TOKEN="<your-api-token>"
  1. Create a Binary-mode detector in the dashboard. Set the question to "Is there a bird at the feeder?" and the confidence threshold to 0.75. Note the detector ID for later use.
tip

We use a relatively low confidence threshold in this example because birdwatching is a fun and casual activity. For more critical applications, you may want to set a higher confidence threshold.

  1. Now, run the Groundlight Stream container to process the live stream. For example, to monitor the Cornell Lab of Ornithology's bird feeder live stream, you could use the following command:
docker run groundlight/stream \
    -t "$GROUNDLIGHT_API_TOKEN" \
    -d "<YOUR_DETECTOR_ID>" \
    -s "https://www.youtube.com/watch?v=WtoxxHADnGk" \
    -f 0.25 \   # 1 frame every 4 seconds
    -m \        # enable motion detection to only process frames when movement occurs
    -v          # enable verbose logging

You should see Image Queries being submitted to Groundlight as the container processes the live stream. Once you have confirmed that the container is working as expected, you can remove the -v flag to reduce the amount of logging, and you can also run the container in the background by adding the --detach flag.

docker run --detach groundlight/stream \
    -t "$GROUNDLIGHT_API_TOKEN" \
    -d "<YOUR_DETECTOR_ID>" \
    -s "https://www.youtube.com/watch?v=WtoxxHADnGk" \
    -f 0.25 \   # 1 frame every 4 seconds
    -m          # enable motion detection to only process frames when movement occurs
  1. Now, sit back and relax! The container will begin submitting frames from the live stream to Groundlight. You can watch the answers arrive on the Groundlight dashboard, or retrieve them with the Python SDK (see asynchronous queries).

Additional Options​

You can also use groundlight/stream to process local video files, RTSP streams, and more. Here are some examples:

  • Process local video files by mounting them:
docker run -v /path/to/video:/videos groundlight/stream \
    -t "$GROUNDLIGHT_API_TOKEN" \
    -d <YOUR_DETECTOR_ID> \
    -s /videos/video.mp4
  • Connect to RTSP cameras:
docker run groundlight/stream \
    -t "$GROUNDLIGHT_API_TOKEN" \
    -d <YOUR_DETECTOR_ID> \
    -s "rtsp://username:password@camera_ip:554/stream"

See the complete documentation at https://github.com/groundlight/stream