Skip to main content

Python library for grabbing images from webcams

Project description

Python library to download images from network accessible webcams.


  • Out of the box, handles any webcam which provides a publically accessible URL to a JPG snapshot of their current image.

  • Easily swap in different downloaders to handle cams which expose their snapshots in a more complex way.

  • Highly configurable.

  • Provides a simple base for more advanced functionality, such as motion detection, CCTV systems, image analysis, etc.


pip install camgrab

Quick start

To simply grabbing images from a webcam every 2 seconds and start saving them to the default grabbed_images directory:

from camgrab import Grabber

grabber = Grabber('')


Quickly add a custom result handler

Here we create a custom result handler which will simply print the dimensions of the grabbed image.

The default result handlers (e.g. do_save_image()) will still be used.

from camgrab import Grabber

url = ''

def print_dimensions(result, grabber):
    if not result.get('image', None):

    width, height = result['image'].size
        '{width} pixels wide, {height} pixels high!'.
        format(width=width, height=height)

grabber = Grabber(url, every=5, extra_result_handlers=(print_dimensions, ))

More complex result handling

In this example, we’ll take full control of the result handling, creating a chain of result handlers to:

  • resize the image to 320x200

  • rotate the image by 90 degrees

  • save the image

  • print the final result dictionary to the terminal

from camgrab import Grabber
from camgrab.camgrab import do_save_image

url = ''

def resize_image(result, grabber):
    if not result.get('image', None):

    result['image'] = result['image'].resize((320, 200))

def rotate_image(result, grabber):
    if not result.get('image', None):

    result['image'] = result['image'].rotate(90)

def print_result(result, grabber):

# Setting result_handlers attribute completely overrides any default result
# handlers previously set. Hence making sure `do_save_image` (which is normally
# a default handler) is in this tuple:
result_handlers = (resize_image, rotate_image, do_save_image, print_result)

grabber = Grabber(url, every=5)
grabber.result_handlers = result_handlers

Take control of the main loop

If the the main loop created by the begin() method is too simple for your needs, then either override the begin() method or simply call tick() from your own consumer.

In this example, we consume a Grabber but define our own (not terribly useful) main loop which waits a random amount of time between ticks:

from random import random
from time import sleep

from camgrab import Grabber

url = ''
grabber = Grabber(url)

while True:

    # Wait somewhere between 0 and 10 seconds
    sleep(random() * 10)

Error handling

Grabbing images from webcams is a messy business… They go offline loads, send corrupted images, sometimes they randomly start sending Server 500 errors, etc.

Because of all this, camgrab’s default settings make it pretty tolerant of common errors which occur when grabbing an image. But this can be configured easily enough.

When an unhandled exception is raised during a tick() which causes a crash, the exception which caused the crash can be found in the failed_exception attribute.

HTTP errors

HTTP errors can be ignored or raised by setting ignore_xxx attributes. For example…

By default HTTP 404 errors are not ignored by default. So when a 404 error occurs the grabber will crash and you can handle the exception in whatever way you want.

from urllib.error import HTTPError

from camgrab import Grabber

grabber = Grabber('')

except HTTPError as e:
    if e.code == 404:
        print('Was it something I said?')

If you’d rather HTTP 404 errors didn’t cause a crash, then set the ignore_404 attribute:

from camgrab import Grabber

grabber = Grabber('')
grabber.ignore_404 = True


Now when a 404 error occurs, the Grabber will:

  • add the exception to the result dictionary

  • set the image in the result dictionary to None

And then continue its normal routine.

By default, the following HTTP status codes are ignored:

  • 307, 400, 408, 409, 429, 444, 451, 499, 500, 502, 503, 504, 507, 599

Network errors

camgrab ignores network errors by default. If you’d rather network timeouts caused a crash, then just set the ignore_timeout attribute:

from socket import timeout
from urllib.error import URLError

from camgrab import Grabber

grabber = Grabber('')
grabber.ignore_timeout = False

except URLError as e:
    if isinstance(e.reason, timeout):
        print("It's me, not you")


camgrab is free software, distributed under the MIT license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

camgrab-0.9.1.tar.gz (206.7 kB view hashes)

Uploaded source

Built Distribution

camgrab-0.9.1-py3-none-any.whl (11.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page