### Install onvif-python

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Install the library from PyPI or build from source after cloning the repository.

```bash
pip install --upgrade onvif-python
```

```bash
git clone https://github.com/nirsimetri/onvif-python
cd onvif-python
pip install .
```

--------------------------------

### ONVIF CLI: Discovery and Interactive Shell

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Demonstrates using the 'onvif' CLI for WS-Discovery to find devices and entering an interactive shell mode for command execution and exploration. Includes examples of discovery with credentials and starting an interactive session.

```bash
# WS-Discovery: find devices, then enter interactive shell
onvif --discover --username admin --password admin123 --interactive
onvif -d -f "Profile/Streaming" -u admin -p admin123 -i

# Interactive shell
onvif -H 192.168.1.17 -P 8000 -u admin -p admin123 -i
# Interactive shell commands:
#   caps                      — show device capabilities
#   cd devicemgmt             — enter Device Management service context
#   GetDeviceInformation      — call method (no params needed)
#   GetServices IncludeCapability=True
#   store services_info       — save last result as variable
#   show services_info        — display stored variable
#   up                        — exit service context
```

--------------------------------

### ONVIF CLI Examples: Interactive Mode

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Shows how to start the ONVIF CLI in interactive mode for a more conversational command-line experience. Requires connection details.

```bash
onvif --host 192.168.1.17 --port 8000 --username admin --password admin123 --interactive
```

```bash
# Prompting for username and password
# (if not provided)
onvif -H 192.168.1.17 -P 8000 -i
```

--------------------------------

### Get ONVIF Profiles Example

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Demonstrates a sequence of commands to retrieve ONVIF profiles, store the result, and then display a specific attribute of the first profile.

```bash
GetProfiles
```

```bash
store profiles
```

```bash
show profiles[0].token
```

--------------------------------

### ONVIF CLI Examples: Direct Command Execution

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Provides examples of executing specific ONVIF service methods directly, including device management and PTZ control. Requires host, port, and authentication details.

```bash
onvif devicemgmt GetCapabilities Category=All --host 192.168.1.17 --port 8000 --username admin --password admin123
```

```bash
onvif ptz ContinuousMove ProfileToken=Profile_1 Velocity={'PanTilt': {'x': -0.1, 'y': 0}} -H 192.168.1.17 -P 8000 -u admin -p admin123
```

--------------------------------

### Install onvif-python from Source

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Clone the repository and install the onvif-python library locally. This is useful for development or testing.

```bash
git clone https://github.com/nirsimetri/onvif-python
cd onvif-python
pip install .
```

--------------------------------

### ONVIF CLI Examples: Device Discovery with Filtering

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Illustrates how to discover ONVIF devices and filter them by type or scope. Supports interactive mode and authentication.

```bash
onvif --discover --filter ptz --interactive
```

```bash
onvif -d -f "C210" -i
```

```bash
onvif -d -f "audio_encoder" -u admin -p admin123 -i
```

--------------------------------

### Install onvif-python Package

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Install the onvif-python library using pip. Upgrade to the latest version if already installed.

```bash
pip install --upgrade onvif-python
```

--------------------------------

### Configure Hostname with ONVIFClient

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Example of setting the device's hostname using the ONVIFClient. Requires a device management client instance.

```python
hostname_req = device.type("SetHostname")
hostname_req.Name = "MyCameraNode"
device.SetHostname(hostname_req)
```

--------------------------------

### ONVIF CLI Examples: Device Discovery

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Shows how to discover ONVIF devices on the network using WS-Discovery. Includes options for specifying credentials, enabling interactive mode, and filtering results.

```bash
onvif --discover --username admin --password admin123 --interactive
```

```bash
onvif media GetProfiles --discover --username admin
```

```bash
onvif -d -i
```

--------------------------------

### ONVIF CLI Examples: Product Search

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Demonstrates how to search for ONVIF products using keywords, specify page numbers, and set the number of results per page.

```bash
onvif --search c210
```

```bash
onvif -s "axis camera"
```

```bash
onvif --search hikvision --page 2 --per-page 5
```

--------------------------------

### Install Package and Dependencies

Source: https://github.com/nirsimetri/onvif-python/blob/main/CONTRIBUTING.md

Install the ONVIF Python package in development mode and its development dependencies, including testing and linting tools.

```bash
# Install the package in development mode
pip install -e .

# Install development dependencies (pytest, black, flake8)
pip install -e ".[dev]"

```

--------------------------------

### Discover ONVIF Devices on Network

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

This example shows the output of the device discovery process, listing discovered devices with their details and prompting the user to select one.

```text
Discovering ONVIF devices on network...
Network interface: 192.168.1.100
Timeout: 4s

Found 2 ONVIF device(s):

[1] 192.168.1.14:2020
    [id] 3fa1fe68-b915-4053-a3e1-a8294833fe3c
    [xaddrs] [http://192.168.1.14:2020/onvif/device_service]
    [types] [tdn:NetworkVideoTransmitter]
    [scopes] [name/C210] [hardware/C210] [Profile/Streaming] [location/Hong Kong]

[2] 192.168.1.17:8000
    [id] 7d04ff31-61e6-11f0-a00c-6056eef47207
    [xaddrs] [http://192.168.1.17:8000/onvif/device_service]
    [types] [dn:NetworkVideoTransmitter] [tds:Device]
    [scopes] [type/NetworkVideoTransmitter] [location/unknown] [name/IPC_123465959]

Select device number 1-2 or q to quit: 1

Selected: 192.168.1.14:2020
```

--------------------------------

### ONVIF CLI Examples: Using HTTPS

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Demonstrates how to connect to an ONVIF device using HTTPS instead of the default HTTP. Specify the --https flag for secure connections.

```bash
onvif media GetProfiles --host camera.example.com --port 443 --username admin --password admin123 --https
```

--------------------------------

### Start Interactive ONVIF Shell

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Launches the interactive shell for exploring ONVIF devices. Provides connection details directly or be prompted for credentials.

```bash
onvif --host 192.168.1.17 --port 8000 --username admin --password admin123 -i
```

--------------------------------

### Adjust Imaging Settings and Focus

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Demonstrates how to set brightness, contrast, sharpness, and color saturation. Includes an example of attempting to move focus, with error handling for unsupported features.

```python
from onvif import ONVIFClient

# Assuming source_token is already defined and obtained
# client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
# imaging = client.imaging()
# source_token = client.media().GetProfiles()[0].token

# Adjust brightness and contrast
imaging.SetImagingSettings(
    VideoSourceToken=source_token,
    ImagingSettings={
        "Brightness": 60,
        "Contrast": 55,
        "Sharpness": 50,
        "ColorSaturation": 50,
    },
)

# Move focus (if supported)
try:
    imaging.Move(
        VideoSourceToken=source_token,
        Focus={"AutoFocusMode": "AUTO"},
    )
    status = imaging.GetMoveOptions(VideoSourceToken=source_token)
    print("Focus options:", status)
except Exception as e:
    print("Focus not supported:", e)
```

--------------------------------

### Get Device Capabilities

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Executes the GetCapabilities command for the 'devicemgmt' service to retrieve all device capabilities. Requires host, port, username, and password.

```bash
onvif devicemgmt GetCapabilities Category=All -H 192.168.1.17 -P 8000 -u admin -p admin123
```

--------------------------------

### Access ONVIF Services

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Instantiate specific ONVIF service clients from the main ONVIFClient object. Examples include Device Management and Media services.

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

--------------------------------

### ONVIF CLI Examples: Saving Output to File

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Demonstrates how to save the output of ONVIF CLI commands to files in JSON, XML, or plain text formats. XML output automatically enables debug mode.

```bash
onvif devicemgmt GetDeviceInformation --host 192.168.1.17 --port 8000 --username admin --password admin123 --output device_info.json
```

```bash
onvif media GetProfiles --host 192.168.1.17 --port 8000 --username admin --password admin123 --output profiles.xml
```

```bash
onvif ptz GetConfigurations --host 192.168.1.17 --port 8000 --username admin --password admin123 --output ptz_config.txt --debug
```

--------------------------------

### ONVIF CLI: Direct Command Execution

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Examples of using the 'onvif' CLI for direct ONVIF operation calls, including specifying host, port, username, password, and parameters. Shows saving output to JSON/XML.

```bash
# Show help
onvif --help

# Direct command execution
onvif devicemgmt GetDeviceInformation -H 192.168.1.17 -P 8000 -u admin -p admin123
onvif devicemgmt GetCapabilities Category=All -H 192.168.1.17 -P 8000 -u admin -p admin123
onvif ptz ContinuousMove ProfileToken=Profile_1 \
    Velocity='{"PanTilt": {"x": 0.1, "y": 0}}' \
    -H 192.168.1.17 -P 8000 -u admin -p admin123

# Save output to JSON / XML
onvif devicemgmt GetDeviceInformation -H 192.168.1.17 -P 8000 -u admin -p admin123 \
    --output device_info.json
onvif media GetProfiles -H 192.168.1.17 -P 8000 -u admin -p admin123 \
    --output profiles.xml
```

--------------------------------

### Discover ONVIF Devices Interactively

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Finds ONVIF devices on the network using WS-Discovery and starts an interactive shell session. Supports filtering and credential prompting.

```bash
onvif --discover --username admin --password admin123 --interactive
```

```bash
onvif -d -u admin -p admin123 -i
```

```bash
onvif --discover --filter "C210" --interactive
```

```bash
onvif -d -f ptz -u admin -p admin123 -i
```

```bash
onvif -d -i
```

--------------------------------

### ONVIF CLI - Command-Line Interface

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

The onvif CLI is installed automatically with the package. It supports direct command execution, interactive shell mode with tab completion, WS-Discovery, and a built-in ONVIF product database search.

```APIDOC
## ONVIF CLI — Command-Line Interface

The `onvif` CLI is installed automatically with the package. It supports direct command execution, interactive shell mode with tab completion, WS-Discovery, and a built-in ONVIF product database search.

```bash
# Show help
onvif --help

# Direct command execution
onvif devicemgmt GetDeviceInformation -H 192.168.1.17 -P 8000 -u admin -p admin123
onvif devicemgmt GetCapabilities Category=All -H 192.168.1.17 -P 8000 -u admin -p admin123
onvif ptz ContinuousMove ProfileToken=Profile_1 \
    Velocity='{"PanTilt": {"x": 0.1, "y": 0}}' \
    -H 192.168.1.17 -P 8000 -u admin -p admin123

# Save output to JSON / XML
onvif devicemgmt GetDeviceInformation -H 192.168.1.17 -P 8000 -u admin -p admin123 \
    --output device_info.json
onvif media GetProfiles -H 192.168.1.17 -P 8000 -u admin -p admin123 \
    --output profiles.xml

# WS-Discovery: find devices, then enter interactive shell
onvif --discover --username admin --password admin123 --interactive
onvif -d -f "Profile/Streaming" -u admin -p admin123 -i

# Interactive shell
onvif -H 192.168.1.17 -P 8000 -u admin -p admin123 -i
# Interactive shell commands:
#   caps                      — show device capabilities
#   cd devicemgmt             — enter Device Management service context
#   GetDeviceInformation      — call method (no params needed)
#   GetServices IncludeCapability=True
#   store services_info       — save last result as variable
#   show services_info        — display stored variable
#   up                        — exit service context
```
```

--------------------------------

### Execute ONVIF Method with Stored Data Parameter

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Shows how to use stored data, referenced by '$variable' syntax, as a parameter for an ONVIF method. This example uses a stored profile token.

```bash
GetImagingSettings VideoSourceToken=$profiles[0].VideoSourceConfiguration.SourceToken
```

--------------------------------

### Accessing Additional ONVIF Services

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Provides examples of accessing various other ONVIF services, including Media, Recording, Access Control, Device I/O, and more, using the ONVIFClient.

```APIDOC
## Additional Service Accessors

`ONVIFClient` exposes accessors for all 25+ implemented ONVIF services. Each follows the same lazy-initialization pattern and returns a service object with full ONVIF operation coverage.

```python
from onvif import ONVIFClient

client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

# Media & streaming
media        = client.media()          # Profile S media operations
media2       = client.media2()         # Profile T / Media2 (H.265, metadata)

# Recording & search (Profile G)
recording    = client.recording()      # Recording control
search       = client.search()         # Recording search
replay       = client.replay()         # Replay control

# Access control (Profile C/A/D)
accesscontrol = client.accesscontrol() # Door/access monitoring
doorcontrol   = client.doorcontrol()   # Door control
accessrules   = client.accessrules()   # Access rule management
credential    = client.credential()    # Credential management
authbehavior  = client.authenticationbehavior()

# Device I/O
deviceio      = client.deviceio()      # Relay outputs, digital inputs
display       = client.display()       # Video output display

# Other services
thermal       = client.thermal()       # Thermal imaging
provisioning  = client.provisioning()  # Zero-touch provisioning
receiver      = client.receiver()      # RTSP receiver
schedule      = client.schedule()      # Time schedules
uplink         = client.uplink()       # Cloud uplink
appmanagement = client.appmanagement() # Application management
analyticsdevice = client.analyticsdevice()  # Analytics device

# Example: get relay outputs from DeviceIO
outputs = deviceio.GetRelayOutputs()
for out in outputs:
    print(out.token, out.Properties.Mode)
```
```

--------------------------------

### Get ONVIF Device Capabilities and Services

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Retrieve all capabilities of an ONVIF device or list available services. Ensure the ONVIFClient is initialized with correct device IP, port, username, and password.

```python
from onvif import ONVIFClient

# Assuming 'device' is an initialized ONVIFClient instance
# device = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

# Get all capabilities
caps = device.GetCapabilities(Category="All")
print(caps)

# Get all available services
services = device.GetServices(IncludeCapability=False)
for svc in services:
    print(svc.Namespace, "->", svc.XAddr)
```

--------------------------------

### Example ONVIF Product Search Output

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Illustrates the tabular output format for ONVIF product search results, including details like ID, Test Date, Model, Firmware, Profiles, Category, Type, and Company.

```text
Found 15 product(s) matching: hikvision
Showing 1-10 of 15 results

ID  | Test Date           | Model             | Firmware | Profiles | Category | Type    | Company
----|---------------------|-------------------|----------|----------|----------|---------|---------
342 | 2024-08-15 17:53:12 | DS-2CD2143G2-IU   | V5.7.3   | S,G,T    | Camera   | device  | Hikvision
341 | 2024-08-14 14:22:05 | DS-2DE2A404IW-DE3 | V5.6.15  | S,G,T    | Camera   | device  | Hikvision
...

Page 1 of 2
Navigation: Next: --page 2
```

--------------------------------

### Example PR Titles

Source: https://github.com/nirsimetri/onvif-python/blob/main/CONTRIBUTING.md

Examples of commit/PR titles following the conventional commit format for different types of changes.

```markdown
- `feat: add Media service auto path detection`  
- `fix: handle empty response in GetServices`  
- `chore: update dependencies`  

```

--------------------------------

### Initialize ONVIFClient

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Create an ONVIFClient instance with device credentials and IP address. A custom WSDL directory can be specified for advanced configurations.

```python
from onvif import ONVIFClient

# Basic connection
client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

# With custom WSDL directory (optional)
client = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    wsdl_dir="/path/to/custom/wsdl"  # Use custom WSDL files in this path
)
```

--------------------------------

### Imaging Operations

Source: https://github.com/nirsimetri/onvif-python/blob/main/onvif/wsdl/ver20/util/operationIndex.html

Operations related to imaging control, such as moving the camera and getting status.

```APIDOC
## GetOptions

### Description
Retrieves the available options for imaging operations.

### Method
POST

### Endpoint
/onvif/ver20/imaging

## Move

### Description
Initiates a move operation for the camera.

### Method
POST

### Endpoint
/onvif/ver20/imaging

## GetMoveOptions

### Description
Retrieves the available options for move operations.

### Method
POST

### Endpoint
/onvif/ver20/imaging

## Stop

### Description
Stops any ongoing move operation.

### Method
POST

### Endpoint
/onvif/ver20/imaging

## GetStatus

### Description
Retrieves the current status of the imaging system.

### Method
POST

### Endpoint
/onvif/ver20/imaging
```

--------------------------------

### Get RTSP URL

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

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

```APIDOC
## Get RTSP URL

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

```python
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', ...}
```
```

--------------------------------

### Initialize ONVIFClient

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Create an instance of ONVIFClient by providing your device's IP address, port, username, and password. You can also specify a custom WSDL directory.

```APIDOC
## Initialize the ONVIFClient

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

```python
from onvif import ONVIFClient

# Basic connection
client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

# With custom WSDL directory (optional)
client = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    wsdl_dir="/path/to/custom/wsdl"  # Use custom WSDL files in this path
)
```
```

--------------------------------

### Get Device Information

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

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

```APIDOC
## Get Device Information

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

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

--------------------------------

### Get Device Information

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Retrieve essential device details like manufacturer, model, and serial number using the Device Management service.

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

--------------------------------

### Configure ONVIF Client for Production Environment

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Set up the ONVIF client with recommended production settings for optimal performance, security, and compatibility. This includes enabling HTTPS, verifying SSL certificates, and applying patches.

```python
from onvif import ONVIFClient, CacheMode

# Recommended production settings
client = ONVIFClient(
    host="your-cctv-node.viewplexus.com",
    port=443,
    username="admin",
    password="secure_password",
    timeout=15,
    cache=CacheMode.ALL,        # Maximum performance (default)
    use_https=True,             # Secure communication
    verify_ssl=True,            # Verify certificates (default)
    apply_patch=True,           # Enhanced parsing (default)
    capture_xml=False,          # Disable debug mode (default)
    wsdl_dir=None               # Use built-in WSDL files (default)
)
```

--------------------------------

### ONVIF CLI Help and Usage

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Displays the help message for the ONVIF CLI, outlining all available commands, options, and arguments. Use this to understand the full range of functionalities.

```bash
usage: onvif [-h] [--host HOST] [--port PORT] [--username USERNAME] [--password PASSWORD] [--discover] [--filter FILTER] [--search SEARCH] [--page PAGE]
             [--per-page PER_PAGE] [--timeout TIMEOUT] [--https] [--no-verify] [--no-patch] [--interactive] [--debug] [--wsdl WSDL]
             [--cache {all,db,mem,none}] [--health-check-interval HEALTH_CHECK_INTERVAL] [--output OUTPUT] [--version] [--version]
             [service] [method] [params ...]

ONVIF Terminal Client — v0.2.10
https://github.com/nirsimetri/onvif-python

positional arguments:
  service               ONVIF service name (e.g., devicemgmt, media, ptz)
  method                Service method name (e.g., GetCapabilities, GetProfiles)
  params                Method parameters as Simple Parameter or JSON string

options:
  -h, --help            show this help message and exit
  --host HOST, -H HOST  ONVIF device IP address or hostname
  --port PORT, -P PORT  ONVIF device port (default: 80)
  --username USERNAME, -u USERNAME
                        Username for authentication
  --password PASSWORD, -p PASSWORD
                        Password for authentication
  --discover, -d        Discover ONVIF devices on the network using WS-Discovery
  --filter FILTER, -f FILTER
                        Filter discovered devices by types or scopes (case-insensitive substring match)
  --search SEARCH, -s SEARCH
                        Search ONVIF products database by model or company (e.g., 'c210', 'hikvision')
  --page PAGE           Page number for search results (default: 1)
  --per-page PER_PAGE   Number of results per page (default: 20)
  --timeout TIMEOUT     Connection timeout in seconds (default: 10)
  --https               Use HTTPS instead of HTTP
  --no-verify           Disable SSL certificate verification
  --no-patch            Disable ZeepPatcher
  --interactive, -i     Start interactive mode
  --debug               Enable debug mode with XML capture
  --wsdl WSDL           Custom WSDL directory path
  --cache {all,db,mem,none}
                        Caching mode for ONVIFClient (default: all). 'all': memory+disk, 'db': disk-only, 'mem': memory-only, 'none': disabled.
  --health-check-interval HEALTH_CHECK_INTERVAL, -hci HEALTH_CHECK_INTERVAL
                        Health check interval in seconds for interactive mode (default: 10)
  --output OUTPUT, -o OUTPUT
                        Save command output to file. Supports .json, .xml extensions for format detection, or plain text. XML format automatically enables
                        debug mode for SOAP capture.
  --version, -v         Show ONVIF CLI version and exit
```

--------------------------------

### Get RTSP Stream URL

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Obtain the RTSP URL for live video streaming by querying the Media service and selecting the first available profile.

```python
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', ...}
```

--------------------------------

### Manage Users on ONVIF Device

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Create new users with specified usernames, passwords, and privilege levels, and then retrieve the list of all users. Ensure the ONVIFClient is initialized.

```python
# Assuming 'device' is an initialized ONVIFClient instance
# device = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

device.CreateUsers(
    User=[{"Username": "newuser", "Password": "newpass", "UserLevel": "User"}]
)
print(device.GetUsers())
```

--------------------------------

### Media Operations

Source: https://github.com/nirsimetri/onvif-python/blob/main/onvif/wsdl/ver20/util/operationIndex.html

Operations related to media configuration, including getting and setting various audio and video configurations, as well as managing stream URIs and snapshots.

```APIDOC
## GetAudioOutputConfiguration

### Description
Retrieves the audio output configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioOutputConfiguration

## GetAudioDecoderConfiguration

### Description
Retrieves the audio decoder configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioDecoderConfiguration

## GetCompatibleVideoEncoderConfigurations

### Description
Retrieves a list of compatible video encoder configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleVideoEncoderConfigurations

## GetCompatibleVideoSourceConfigurations

### Description
Retrieves a list of compatible video source configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleVideoSourceConfigurations

## GetCompatibleAudioEncoderConfigurations

### Description
Retrieves a list of compatible audio encoder configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleAudioEncoderConfigurations

## GetCompatibleAudioSourceConfigurations

### Description
Retrieves a list of compatible audio source configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleAudioSourceConfigurations

## GetCompatibleVideoAnalyticsConfigurations

### Description
Retrieves a list of compatible video analytics configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleVideoAnalyticsConfigurations

## GetCompatibleMetadataConfigurations

### Description
Retrieves a list of compatible metadata configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleMetadataConfigurations

## GetCompatibleAudioOutputConfigurations

### Description
Retrieves a list of compatible audio output configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleAudioOutputConfigurations

## GetCompatibleAudioDecoderConfigurations

### Description
Retrieves a list of compatible audio decoder configurations.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetCompatibleAudioDecoderConfigurations

## SetVideoSourceConfiguration

### Description
Sets the video source configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetVideoSourceConfiguration

## SetVideoEncoderConfiguration

### Description
Sets the video encoder configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetVideoEncoderConfiguration

## SetAudioSourceConfiguration

### Description
Sets the audio source configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetAudioSourceConfiguration

## SetAudioEncoderConfiguration

### Description
Sets the audio encoder configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetAudioEncoderConfiguration

## SetVideoAnalyticsConfiguration

### Description
Sets the video analytics configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetVideoAnalyticsConfiguration

## SetMetadataConfiguration

### Description
Sets the metadata configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetMetadataConfiguration

## SetAudioOutputConfiguration

### Description
Sets the audio output configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetAudioOutputConfiguration

## SetAudioDecoderConfiguration

### Description
Sets the audio decoder configuration.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetAudioDecoderConfiguration

## GetVideoSourceConfigurationOptions

### Description
Retrieves options for video source configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetVideoSourceConfigurationOptions

## GetVideoEncoderConfigurationOptions

### Description
Retrieves options for video encoder configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetVideoEncoderConfigurationOptions

## GetAudioSourceConfigurationOptions

### Description
Retrieves options for audio source configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioSourceConfigurationOptions

## GetAudioEncoderConfigurationOptions

### Description
Retrieves options for audio encoder configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioEncoderConfigurationOptions

## GetMetadataConfigurationOptions

### Description
Retrieves options for metadata configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetMetadataConfigurationOptions

## GetAudioOutputConfigurationOptions

### Description
Retrieves options for audio output configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioOutputConfigurationOptions

## GetAudioDecoderConfigurationOptions

### Description
Retrieves options for audio decoder configuration.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetAudioDecoderConfigurationOptions

## GetGuaranteedNumberOfVideoEncoderInstances

### Description
Retrieves the guaranteed number of video encoder instances.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetGuaranteedNumberOfVideoEncoderInstances

## GetStreamUri

### Description
Retrieves the URI for a media stream.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetStreamUri

## StartMulticastStreaming

### Description
Starts multicast streaming.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.StartMulticastStreaming

## StopMulticastStreaming

### Description
Stops multicast streaming.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.StopMulticastStreaming

## SetSynchronizationPoint

### Description
Sets the synchronization point for media streams.

### Method
POST

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.SetSynchronizationPoint

## GetSnapshotUri

### Description
Retrieves the URI for a snapshot image.

### Method
GET

### Endpoint
/onvif/ver10/media/wsdl/media.wsdl#op.GetSnapshotUri
```

--------------------------------

### Get Snapshot URI from Media Service

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Retrieve the URI for a snapshot image from a specific media profile. Requires an initialized ONVIFClient and access to the media service.

```python
from onvif import ONVIFClient

client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
media = client.media()
profiles = media.GetProfiles()
profile = profiles[0]  # use first profile

# Get snapshot URI
snapshot = media.GetSnapshotUri(ProfileToken=profile.token)
print("Snapshot URI:", snapshot.Uri)
```

--------------------------------

### Create Service Instance

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

`ONVIFClient` provides access to various ONVIF services like Device Management, Events, Imaging, Media, PTZ, and Analytics.

```APIDOC
## 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 [Implemented ONVIF Services](https://github.com/nirsimetri/onvif-python?tab=readme-ov-file#implemented-onvif-services) for more details

Example usage:
```python
device = client.devicemgmt()      # Device Management (Core)
media = client.media()            # Media
```
```

--------------------------------

### Get Network Information from ONVIF Device

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Retrieve network interface details, hostname, and DNS server information from an ONVIF device. Requires an initialized ONVIFClient.

```python
# Assuming 'device' is an initialized ONVIFClient instance
# device = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")

print(device.GetNetworkInterfaces())
print(device.GetHostname())
print(device.GetDNS())
```

--------------------------------

### ONVIFClient - Create a Client Connection

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

The ONVIFClient class is the primary entry point for connecting to an ONVIF device. It handles service discovery and provides access to various ONVIF services. Key parameters include host, port, username, and password, with optional parameters for timeout, HTTPS, SSL verification, and XML capture.

```APIDOC
## ONVIFClient — Create a Client Connection

`ONVIFClient` is the main entry point. It connects to an ONVIF device, performs automatic service discovery, and provides access to all service accessors. Key parameters: `host`, `port`, `username`, `password` (required); `timeout`, `cache`, `use_https`, `verify_ssl`, `apply_patch`, `capture_xml`, `wsdl_dir` (optional).

### Basic Connection
```python
from onvif import ONVIFClient

client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
```

### HTTPS Connection with Custom Timeout
```python
from onvif import ONVIFClient

client_https = ONVIFClient(
    "camera.example.com", 443, "admin", "secure_pass",
    timeout=30,
    use_https=True,
    verify_ssl=False,  # set False for self-signed certificates
)
```

### Memory-Only Cache
```python
from onvif import ONVIFClient, CacheMode

client_mem = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    cache=CacheMode.MEM
)
```

### Debug Mode with XML Capture
```python
from onvif import ONVIFClient

client_debug = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    capture_xml=True
)
device = client_debug.devicemgmt()
info = device.GetDeviceInformation()
print(client_debug.xml_plugin.last_sent_xml)     # raw SOAP request
print(client_debug.xml_plugin.last_received_xml) # raw SOAP response
```

### Custom WSDL Directory
```python
from onvif import ONVIFClient

client_custom = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    wsdl_dir="/path/to/custom/wsdl"
)
```
```

--------------------------------

### Discover and Execute ONVIF Command

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Discovers ONVIF devices on the network and executes a specified command on the first discovered device. Requires credentials.

```bash
onvif media GetProfiles --discover --username admin --password admin123
```

--------------------------------

### Initialize ONVIF Client for Service Discovery

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Initialize the ONVIF client to automatically discover device services. This is a crucial first step before performing operations on an ONVIF device.

```python
from onvif import ONVIFClient

client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
```

--------------------------------

### SetVideoOutputLayout

Source: https://github.com/nirsimetri/onvif-python/blob/main/onvif/wsdl/ver10/display/wsdl/index.htm

Changes the layout of a display, for example, from a single view to a split-screen view. This affects a specific video output and consists of a list of PaneConfigurations and their associated display areas.

```APIDOC
## SetVideoOutputLayout

### Description
Change the layout of a display (e.g. change from single view to split screen view). The Layout assigns a pane configuration to a certain area of the display. The layout settings directly affect a specific video output. The layout consists of a list of PaneConfigurations and their associated display areas.

### Method
POST

### Endpoint
/onvif/device_service

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **VideoOutputToken** (string) - Required - Token of the Video Output whose Layout shall be changed.
- **Layout** (object) - Required - The Layout to be set.
  - **PaneConfigurations** (array) - List of PaneConfigurations.
    - **PaneConfiguration** (object) - Configuration of a pane.
      - **PaneToken** (string) - Token of the pane.
      - **Area** (object) - Display area of the pane.
        - **X** (integer)
        - **Y** (integer)
        - **Width** (integer)
        - **Height** (integer)
      - **AudioSourceConfiguration** (object) - Optional - Audio source associated with the pane.
      - **AudioOutputConfiguration** (object) - Optional - Audio output associated with the pane.

### Request Example
```json
{
  "VideoOutputToken": "some_video_output_token",
  "Layout": {
    "PaneConfigurations": [
      {
        "PaneToken": "pane_1_token",
        "Area": {
          "X": 0, "Y": 0, "Width": 1920, "Height": 1080
        }
      }
    ]
  }
}
```

### Response
#### Success Response (200)
None (typically returns an empty response on success for commands that modify state).

#### Response Example
```json
{} 
```
```

--------------------------------

### Create ONVIFClient Connection

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Instantiate ONVIFClient with device credentials and optional parameters for connection and debugging. Use `capture_xml=True` to inspect raw SOAP requests and responses.

```python
from onvif import ONVIFClient, CacheMode

# Basic connection (HTTP, default cache=CacheMode.ALL)
client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
```

```python
# HTTPS with custom timeout
client_https = ONVIFClient(
    "camera.example.com", 443, "admin", "secure_pass",
    timeout=30,
    use_https=True,
    verify_ssl=False,  # set False for self-signed certificates
)
```

```python
# Memory-only cache (useful for short-lived scripts)
client_mem = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    cache=CacheMode.MEM
)
```

```python
# Debug mode with XML capture
client_debug = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    capture_xml=True
)
device = client_debug.devicemgmt()
info = device.GetDeviceInformation()
print(client_debug.xml_plugin.last_sent_xml)     # raw SOAP request
print(client_debug.xml_plugin.last_received_xml) # raw SOAP response
```

```python
# Custom WSDL directory (flat structure: /my/wsdl/devicemgmt.wsdl, etc.)
client_custom = ONVIFClient(
    "192.168.1.17", 8000, "admin", "admin123",
    wsdl_dir="/path/to/custom/wsdl"
)
```

--------------------------------

### Execute ONVIF Method with Simple Parameters

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Use this command to execute an ONVIF method with simple key-value parameters. This is an alternative to JSON parameter format.

```bash
GetServices IncludeCapability=True
```

--------------------------------

### imaging() — Imaging Service

Source: https://context7.com/nirsimetri/onvif-python/llms.txt

Returns the Imaging service object for getting and setting camera image parameters such as brightness, contrast, sharpness, white balance, and exposure settings.

```APIDOC
## imaging() — Imaging Service

### Description
Returns the Imaging service object for getting and setting camera image parameters such as brightness, contrast, sharpness, white balance, and exposure settings.

### Usage
```python
from onvif import ONVIFClient

client = ONVIFClient("192.168.1.17", 8000, "admin", "admin123")
profile = client.media().GetProfiles()[0]
imaging = client.imaging()

# VideoSourceToken comes from the media profile's VideoSourceConfiguration
source_token = profile.VideoSourceConfiguration.SourceToken

# Get current imaging settings
settings = imaging.GetImagingSettings(VideoSourceToken=source_token)
print(settings)
# Example output: {Brightness: 50, ColorSaturation: 50, Contrast: 50, Sharpness: 50, ...}

# Get supported options (ranges, allowed values)
options = imaging.GetOptions(VideoSourceToken=source_token)
print("Brightness range:", options.Brightness)
```
```

--------------------------------

### Initialize ONVIF Client with Custom WSDL Directory

Source: https://github.com/nirsimetri/onvif-python/blob/main/README.md

Configure the ONVIF client to use custom WSDL files from a specified directory. This is useful when the built-in WSDLs are outdated or unavailable.

```python
from onvif import ONVIFClient

# Use custom WSDL files instead of built-in ones
client = ONVIFClient(
    "192.168.1.17", 
    80, 
    "admin", 
    "password",
    wsdl_dir="/path/to/custom/wsdl"  # Custom WSDL directory
)

# All services will automatically use custom WSDL files
device = client.devicemgmt()
media = client.media()
ptz = client.ptz()
```