Skip to content

Quick Start

Below are simple examples to help you get started with the ONVIF Python library. These demonstrate how to discover and connect to ONVIF-compliant devices and retrieve basic device information.

For beginners

If you're new to ONVIF and want to learn more, we highly recommend taking the official free online course provided by ONVIF at Introduction to ONVIF Course.

Please note that we are not endorsed or sponsored by ONVIF, see Legal Notice for details.

Discover ONVIF Devices

Use ONVIFDiscovery (applied at >=v0.1.6) to automatically find ONVIF devices on your local network:

from onvif import ONVIFDiscovery

# Create discovery instance
discovery = ONVIFDiscovery(timeout=5)

# or with a custom interface
discovery = ONVIFDiscovery(timeout=5, interface="192.168.1.69")

# Discover devices
devices = discovery.discover()

# or discover with search filter by types or scopes
# (case-insensitive substring match)
devices = discovery.discover(search="Profile/Streaming")

# Display discovered devices
for device in devices:
    print(f"Found device at {device['host']}:{device['port']}")
    print(f"  Scopes: {device.get('scopes', [])}")
    print(f"  XAddrs: {device['xaddrs']}")

This operation is optional; it is only performed if you do not know the host and port information for the device you wish to connect to.

Initialize the ONVIFClient

Create an instance of ONVIFClient by providing your device's IP address, port, username, and password:

from onvif import ONVIFClient

# Basic connection
client = ONVIFClient(
    host="192.168.1.17", 
    port=80, 
    username="admin", 
    password="password"
)

# With custom WSDL directory (optional)
client = ONVIFClient(
    host="192.168.1.17", 
    port=80, 
    username="admin", 
    password="password",
    wsdl_dir="/path/to/custom/wsdl"  # Use custom WSDL files in this path
)

Create Service Instance

ONVIFClient provides several main services that can be accessed via the following methods:

  • client.devicemgmt() — Device Management
  • client.events() — Events
  • client.imaging() — Imaging
  • client.media() — Media
  • client.ptz() — PTZ (Pan-Tilt-Zoom)
  • client.analytics() — Analytics

and so on, check ONVIFClient for more details

Example usage: 

device = client.devicemgmt()      # Device Management (Core)
media = client.media()            # Media

Get Device Information

Retrieve basic information about the device, such as manufacturer, model, firmware version, and serial number using devicemgmt() service:

info = device.GetDeviceInformation()
print(info)
# Example output:
# {'Manufacturer': '..', 'Model': '..', 'FirmwareVersion': '..', 'SerialNumber': '..'}

Get RTSP URL

Retrieve the RTSP stream URL for live video streaming from the device using media() service:

profile = media.GetProfiles()[0]  # use the first profile
stream = media.GetStreamUri(
    ProfileToken=profile.token, 
    StreamSetup={"Stream": "RTP-Unicast", "Transport": {"Protocol": "RTSP"}}
)
print(stream)
# Example output:
# {'Uri': 'rtsp://192.168.1.17:8554/Streaming/Channels/101', ...}

Explore more advanced usage and service-specific operations in the examples/ folder.