Overview

duvc-ctl is a comprehensive Windows camera control library that provides direct access to DirectShow API for UVC cameras. Control PTZ operations, exposure, focus, brightness, and other camera properties programmatically without any additional drivers or vendor SDKs.

Built with modern C++17, the library offers multiple interfaces: a native C++ API, stable C ABI for language bindings, Python bindings, and a full-featured CLI tool. Whether you're building professional streaming applications or need precise camera control, duvc-ctl handles the DirectShow complexity for you.

Key Capabilities

Professional Camera Control

PTZ Operations with precise pan, tilt, and zoom control. Camera Properties including exposure, focus, iris, and privacy settings. Video Properties such as brightness, contrast, white balance, and gamma correction. All accessible through clean, modern APIs.

Multiple Interface Options

C++ Modern API using smart pointers and Result types for safe error handling. C ABI with stable interface for language bindings. Python Package with Pythonic interfaces and context managers. CLI Tool for scripting and command-line automation.

Enterprise Features

Device Monitoring with hotplug detection and real-time status updates. Connection Pooling for performance optimization in multi-camera scenarios. Vendor Extensions with comprehensive Logitech camera support and extensible framework for other manufacturers.

Robust Architecture

Thread-Safe operations for concurrent device control. RAII Resource Management preventing leaks and ensuring cleanup. Comprehensive Error Handling with detailed diagnostics and system error decoding.

Usage Examples

Modern C++ API

#include <duvc-ctl/duvc.hpp>

// Initialize platform interface
auto platform = duvc::create_platform_interface();

// List available cameras
auto devices_result = platform->list_devices();
if (!devices_result.is_ok()) {
    std::cerr << "Failed to enumerate devices" << std::endl;
    return;
}

const auto& devices = devices_result.value();
if (devices.empty()) return;

// Create connection to first camera
auto connection_result = platform->create_connection(devices[0]);
if (!connection_result.is_ok()) return;
auto connection = std::move(connection_result.value());

// Get property range for validation
auto range_result = connection->get_camera_property_range(duvc::CamProp::Pan);
if (range_result.is_ok()) {
    const auto& range = range_result.value();
    std::cout << "Pan range: " << range.min << " to " << range.max << std::endl;
}

// Set camera to center position
duvc::PropSetting center_setting{0, duvc::CamMode::Manual};
connection->set_camera_property(duvc::CamProp::Pan, center_setting);
connection->set_camera_property(duvc::CamProp::Tilt, center_setting);

Python Bindings

import duvc_ctl as duvc

# List available cameras
devices = duvc.list_devices()
if not devices:
    print("No cameras found")
    return

# Create connection with automatic cleanup
with duvc.DeviceConnection(devices[0]) as conn:
    # Get property capabilities
    pan_range = conn.get_camera_property_range(duvc.CamProp.Pan)
    print(f"Pan range: {pan_range.min} to {pan_range.max}")
    
    # Set properties with validation
    setting = duvc.PropSetting(0, duvc.CamMode.Manual)
    conn.set_camera_property(duvc.CamProp.Pan, setting)
    
    # Read current values
    current_pan = conn.get_camera_property(duvc.CamProp.Pan)
    print(f"Current pan position: {current_pan.value}")
    
    # Control video properties
    brightness = duvc.PropSetting(50, duvc.CamMode.Manual)
    conn.set_video_property(duvc.VidProp.Brightness, brightness)

Command Line Interface

# List all available cameras with details
duvc-cli list --detailed

# Get current camera property value
duvc-cli get --device 0 --property pan --camera

# Set camera to center position
duvc-cli set --device 0 --property pan --value 0 --mode manual
duvc-cli set --device 0 --property tilt --value 0 --mode manual

# Get property ranges and capabilities
duvc-cli ranges --device 0 --camera

# Control video properties
duvc-cli set --device 0 --property brightness --value 75 --video

# Monitor device changes in real-time
duvc-cli monitor --timeout 30 --verbose

# Vendor-specific Logitech controls
duvc-cli vendor logitech --device 0 --property face-tracking --enable

C API for Language Bindings

#include "duvc-ctl/c/api.h"

// Initialize library
duvc_initialize();

// Enumerate devices
duvc_device_t** devices;
size_t device_count;
if (duvc_list_devices(&devices, &device_count) == DUVC_SUCCESS) {
    if (device_count > 0) {
        // Get property range
        duvc_prop_range_t range;
        duvc_get_camera_property_range(devices[0], DUVC_CAM_PROP_PAN, &range);
        
        // Set property value
        duvc_prop_setting_t setting = {0, DUVC_CAM_MODE_MANUAL};
        duvc_set_camera_property(devices[0], DUVC_CAM_PROP_PAN, &setting);
    }
    
    duvc_free_device_list(devices, device_count);
}

// Cleanup
duvc_shutdown();

Supported Camera Operations

Camera Properties (IAMCameraControl)

Pan/Tilt/Roll for directional control, Zoom with optical and digital variants, Exposure with manual and automatic modes, Focus including relative positioning, Iris aperture control, Privacy shutter functionality.

Video Properties (IAMVideoProcAmp)

Image Quality controls including brightness, contrast, saturation, sharpness, and gamma correction. Color Management with hue, white balance, and color enable/disable. Advanced Features like backlight compensation and gain control.

Vendor Extensions

Logitech Support with RightLight auto-exposure, face tracking, LED indicator control, and focus assist. Extensible Framework for adding support for other camera manufacturers through the IKsPropertySet interface.

Architecture & Performance

Modern C++ Design

Built with C++17 using modern idioms including smart pointers, RAII resource management, and move semantics. Result type system provides safe error handling without exceptions. Template metaprogramming enables compile-time optimizations.

DirectShow Integration

Deep integration with ICreateDevEnum for device discovery, IAMCameraControl for PTZ operations, IAMVideoProcAmp for image processing, and IKsPropertySet for vendor extensions. Handles COM lifecycle automatically.

Performance Optimizations

Connection Pooling reduces device access overhead from ~50ms to ~1ms for cached connections. Thread-Safe Operations enable concurrent multi-camera control. Lazy Initialization minimizes resource usage until needed.

Error Handling Strategy

Multi-Level Diagnostics with detailed HRESULT information and system error decoding. Comprehensive Logging with configurable levels and custom callbacks. Graceful Degradation when device capabilities vary.

Installation & Build

Python Package

Install directly from PyPI with pip install duvc-ctl. The package includes pre-built binaries for Windows x64 and requires Python 3.8 or later.

CMake Build

git clone https://github.com/allanhanan/duvc-ctl.git
cd duvc-ctl

# Configure with all features
cmake -B build -G "Visual Studio 17 2022" -A x64 \
    -DDUVC_BUILD_SHARED=ON \
    -DDUVC_BUILD_PYTHON=ON \
    -DDUVC_BUILD_CLI=ON \
    -DDUVC_BUILD_TESTS=ON

# Build and install
cmake --build build --config Release
cmake --install build --config Release

System Requirements

Windows 10/11 (Windows 8.1 compatible), Visual Studio 2019/2022 or MinGW-w64 with GCC 9+, CMake 3.16+, and Windows SDK for DirectShow headers.

Advanced Features

Real-Time Device Monitoring

Built-in hotplug detection automatically discovers new cameras and detects disconnections. Device status tracking monitors connection state and capability changes. Event callbacks notify applications of device state changes.

Comprehensive Testing Suite

Three-tier testing with unit tests for component isolation, integration tests for real device interaction, and functional tests for complete workflows. Performance benchmarks ensure optimal operation under load.

Language Ecosystem

Multiple Interfaces including native C++, stable C ABI, and Python bindings. Future Bindings planned for Rust, Go, Node.js, and .NET. Package Manager Support for vcpkg, Conan, and conda-forge.

Project Context

This library emerged from the need for precise camera control in professional streaming and video production applications. While many solutions require vendor-specific SDKs or additional drivers, duvc-ctl leverages the standard DirectShow framework already present in Windows.

The design philosophy emphasizes zero external dependencies for the core library while providing multiple interface layers to suit different use cases. From simple Python scripts to enterprise C++ applications, duvc-ctl scales to meet diverse requirements.

Active development continues with community contributions, vendor extension support, and cross-platform exploration. The project demonstrates modern C++ library design patterns and serves as a reference for DirectShow API integration.