duvc-ctl Python Documentation

A guide to using the duvc-ctl Python library for controlling USB Video Class (UVC) cameras on Windows.

---

Contents

Getting Started

• 1. Quick Start & Installation

  • 1.1 Installation

  • 1.2 Your First Program

  • 1.3 Platform Requirements & Compatibility

Core Concepts

• 2. Architecture & Design Overview

  • 2.1 Two-Tier Architecture

  • 2.2 API Comparison & Selection

  • 2.3 Core Design Patterns

Pythonic API

• 3. Pythonic API (CameraController)

  • 3.1 Initialization & Device Connection

  • 3.2 Context Manager & Lifecycle

  • 3.3 Internal State Management & Thread Safety

  • 3.4 Class Constants & Built-In Configurations

  • 3.5 Internal Property Mappings

  • 3.6 Video Properties - Image Processing Control

  • 3.7 Camera Properties - Physical Control

  • 3.8 Relative Movement & Combined PTZ

  • 3.9 String-Based Universal Property Access

  • 3.10 Property Aliases & Discovery

  • 3.11 Convenience Setter Methods

  • 3.12 Convenience Getter Methods

  • 3.13 Validation & Safe Operations

  • 3.14 Preset Configuration Management

  • 3.15 Bulk Operations & Batch Control

  • 3.16 Camera Reset & Defaults

  • 3.17 Device Information & Status

  • 3.18 Connection Management & Recovery

  • 3.19 Internal Helper Methods & String Conversion

  • 3.20 Special Methods & Pythonic Features

Result-Based API

• 4. Result-Based API

  • 4.1 Core Functions & Device Enumeration

  • 4.2 Camera Class - Result-Based Operations

  • 4.3 Result Type System

  • 4.4 Result Method Reference & Error Handling

  • 4.5 Device Capabilities & Property Analysis

Reference

• 5. Comprehensive Type Reference

  • 5.1 Core Types & Their Methods

  • 5.2 Error & Status Types

  • 5.3 TypedDicts & Type Definitions

  • 5.4 Windows-Only Types

• 6. Enumeration & Constant Reference

  • 6.1 Property Enumerations

  • 6.2 Control & Error Enumerations

  • 6.3 String Conversion Functions

• 7. Exception Hierarchy & Error Handling

  • 7.1 Exception Base & Device Errors

  • 7.2 Property & Value Errors

  • 7.3 System & Advanced Exceptions

  • 7.4 Exception Mapping & Recovery

Utilities & Advanced

• 8. Convenience Functions & Helpers

  • 8.1 Device Discovery & Management

  • 8.2 Device Context Managers

  • 8.3 Property & Connection Helpers

  • 8.4 Logging Setup & Utilities

• 9. Logging, Diagnostics & Callbacks

  • 9.1 Logging Functions & Level Management

  • 9.2 Error Decoding & Windows Diagnostics

  • 9.3 Device Callbacks & Hot-Plug

• 10. Vendor-Specific Extensions

  • 10.1 Logitech Extensions

  • 10.2 GUID & Vendor Properties

  • 10.3 Abstract Interfaces for Extension

Implementation & Contribution

• 11. Building, Contributing & pybind11 Integration

  • 11.1 Installation & Build Methods

  • 11.2 pybind_module.cpp Architecture

  • 11.3 Contributing & Extension

Complete Property Reference

• 12. Complete Property Reference

  • 12.1 Video Properties Reference

  • 12.2 Camera Properties Reference

  • 12.3 Auto vs Manual Modes

  • 12.4 Range Discovery & Clamping

Practical Guide

• 13. Common Patterns & Recipes

  • 13.1 Basic & Multi-Camera Control

  • 13.2 Bulk & Property Operations

  • 13.3 Advanced Patterns

• 14. Troubleshooting & FAQs

  • 14.1 Common Issues

  • 14.2 Value & Connection Issues

  • 14.3 Build & Performance Issues

Deep Dive

• 15. Advanced Architecture & Special Methods

  • 15.1 pybind11 Module Design

  • 15.2 Pythonic Special Methods

  • 15.3 Windows-Specific Features

  • 15.4 Type Hints & Static Analysis

• 16. Architecture Decision Records

  • 16.1 Design Decisions

  • 16.2 Implementation Rationale

  • 16.3 Future Planning

Learning

• 17. Tutorials & Getting Started

  • 17.1 Beginner Tutorial

  • 17.2 Intermediate Patterns

  • 17.3 Advanced Workflows

Overview

duvc-ctl provides native USB Video Class (UVC) camera control on Windows via DirectShow. Two complementary APIs:

• CameraController: High-level, Pythonic, exception-based

• Result-Based: Low-level, explicit error handling, C++ semantics

Both share identical underlying C++ bindings through pybind11. Choose based on error-handling preference.

Requirements: Windows 8+, Python 3.8+, DirectShow libraries (built-in on Windows)