2. Architecture & Design Overview

2.1 Two-Tier Architecture

duvc-ctl uses a layered design with two distinct Python APIs sitting on top of a shared C++ core. Both APIs access the same underlying DirectShow functionality but present different models to the user.

High-level overview

┌─────────────────────────────────────────────────┐
│          Python User Code                       │
├──────────────────────┬──────────────────────────┤
│ Pythonic API         │ Result-Based API         │
│ (CameraController)   │ (open_camera, Result<T>)│
├──────────────────────┴──────────────────────────┤
│   pybind11 Python Bindings                      │
├─────────────────────────────────────────────────┤
│        C++ Core Library (duvc-ctl)              │
│  (Device enumeration, property access, etc.)   │
├─────────────────────────────────────────────────┤
│      Windows DirectShow & COM                   │
└─────────────────────────────────────────────────┘

Both Python APIs call the same C++ code. The difference is in how they handle device lifecycle, errors, and API design.

Pythonic API (Exception-based)

The Pythonic API, implemented in CameraController, wraps the C++ core and adds Python conventions:

  • Error handling: Exceptions (DuvcError and subclasses) are raised for failures. Callers use try-except blocks.

  • Device management: Automatic device selection (first camera, or by name). Connection/disconnection handled via context manager (with statement).

  • API style: Property-based access (cam.brightness = 75) and method calls (cam.pan_relative(15)).

  • State: The controller maintains internal state—the active device, connection handle, property cache—so the user doesn’t think about it.

Example:

import duvc_ctl as duvc

try:
    with duvc.CameraController() as cam:
        cam.brightness = 80
        print(f"Brightness: {cam.brightness}")
except duvc.PropertyNotSupportedError as e:
    print(f"Cannot set brightness: {e}")

When to use: Learning, scripting, simple applications where you want minimal boilerplate.

Result-Based API (Explicit error handling)

The Result-Based API, in the init.py module, provides low-level control without exceptions:

  • Error handling: Functions return Result<T> types. Callers check is_ok() or is_error() and access the value or error explicitly.

  • Device management: Explicit. You pass a Device or device index to each function.

  • API style: Functional (open_camera(device), camera.get(property) returns Result<PropSetting>).

  • State: Minimal and explicit. You own the Device and Camera objects.

Example:

import duvc_ctl as duvc

devices = duvc.list_devices()
if not devices:
    print("No devices found")
else:
    device = devices[0]
    camera_result = duvc.open_camera(device)
    
    if camera_result.is_ok():
        camera = camera_result.value()
        brightness_result = camera.get(duvc.VidProp.Brightness)
        
        if brightness_result.is_ok():
            setting = brightness_result.value()
            print(f"Brightness: {setting.value}")
        else:
            print(f"Error: {brightness_result.error().description()}")
    else:
        print(f"Error: {camera_result.error().description()}")

When to use: Production code, detailed error recovery, systems that need to handle failures gracefully without exception overhead.

Design rationale

Two APIs instead of one?

The Pythonic API is easier to use for most cases. But production systems often need explicit error handling and minimal overhead. Rather than compromise with a single API, we provide both:

  • Beginners and scripts use the simpler Pythonic API.

  • Production code that needs fine-grained control uses the Result-Based API.

  • Both use the same C++ backend, so there’s no code duplication in the core logic.

Why exceptions vs. results?

  • Pythonic API (exceptions): Python developers expect exceptions. They’re idiomatic. Errors are detected early (at the point of failure) and propagate up without explicit checks.

  • Result-Based API (results): No exceptions mean no exception-throwing overhead. Each operation is explicit—you see exactly where errors are handled. This is valuable in production systems where you need to recover from failures gracefully.

C++ bindings layer (pybind11)

The bridge between Python and C++ is pybind11. It handles:

  • Type conversion (Python int ↔ C++ int32_t, Python str ↔ C++ std::string, etc.)

  • Lifetime management (Python garbage collection ↔ C++ RAII and reference counting)

  • Exception translation (C++ exceptions to Python exceptions in the Pythonic API)

  • Module organization (separate namespaces for Pythonic and Result-based APIs)

The Result-Based API types (Result<T>, Device, PropSetting, etc.) are bound directly from C++ to Python. The Pythonic API (CameraController) is written entirely in Python and uses the Result-based bindings internally.

Thread safety

Both APIs are thread-safe at the module level, but individual devices are not thread-safe:

  • Multiple threads can safely call list_devices(), open different cameras, etc.

  • If two threads access the same camera (same CameraController or Camera object), data races can occur. Use a lock or ensure only one thread accesses a camera at a time.

Example of thread-safe usage (different cameras per thread):

import duvc_ctl as duvc
import threading

def camera_worker(camera_index):
    with duvc.CameraController(camera_index) as cam:
        cam.brightness = 75
        print(f"Camera {camera_index}: brightness set")

devices = duvc.list_devices()
threads = [threading.Thread(target=camera_worker, args=(i,)) for i in range(len(devices))]
for t in threads:
    t.start()
for t in threads:
    t.join()

The C++ core uses a mutex internally to protect shared state (DirectShow device enumeration). Individual camera operations do not hold this mutex long; property get/set operations lock only the minimal necessary time to avoid contention.

Connection state machine

A camera connection goes through these states:

  1. Closed: No active connection.

  2. Opening: Connecting to the device (transitional).

  3. Open: Connected; properties can be read and written.

  4. Closing: Disconnecting (transitional).

The Pythonic API (CameraController) manages these transitions automatically via the context manager. You enter the with block → connection opens. You exit the with block → connection closes.

The Result-Based API requires you to manage state explicitly:

camera_result = duvc.open_camera(device)  # Opens connection
if camera_result.is_ok():
    camera = camera_result.value()
    # Use camera...
    # Connection closes when camera object is destroyed or explicitly closed

Error propagation

Pythonic API:

  • Errors are raised as exceptions. The exception propagates up the call stack until caught or reaches the top level (where Python prints a traceback).

Result-Based API:

  • Errors are wrapped in the Result type. You check is_ok() or is_error() and access the error via error(). No automatic propagation; you decide how to handle each error.

Why this design?

  1. Separation of concerns: Pythonic API handles convenience; Result-Based API handles control.

  2. Flexibility: Users pick the API that fits their use case.

  3. Performance: The Result-Based API avoids exception overhead if desired.

  4. Production-ready: Both are suitable for production; the choice is about error handling philosophy.

2.2 API Comparison & Selection

This section compares both APIs head-to-head so you can choose the right one for your use case.

When to use each API

Scenario

Recommended API

Why

Learning or prototyping

Pythonic

Fewer lines of code, quick iteration

Quick script or automation

Pythonic

Automatic device selection, built-in defaults

Production application with error handling

Result-based

Explicit error checks, no exceptions, full control

High-frequency camera control loop

Result-based

Lower overhead; no exception throwing

Handling multiple cameras concurrently

Either

Both are thread-safe; choose based on error handling preference

Interactive or CLI application

Pythonic

Users expect exceptions; easier debugging

Embedded or headless system

Result-based

Explicit error handling fits production patterns

Real-time or time-critical code

Result-based

Predictable performance; no exception overhead

Detailed feature comparison

Feature

Pythonic

Result-Based

Device Selection

Automatic (first device or by name)

Manual (you pass Device)

Error Handling

Exceptions (try-except)

Result types (is_ok() / is_error())

Property Access

Direct (cam.brightness = 75)

Method call (camera.set(VidProp.Brightness, ...))

Code Style

Object-oriented

Functional

Boilerplate

Minimal

More verbose

Exception Overhead

Yes (thrown on error)

No (checks Result)

Error Details

Exception message + type

Error code + detailed description

Device Lifecycle

Context manager (with)

Manual (you control lifetime)

State Management

Automatic (maintained by controller)

Manual (you own state)

Learning Curve

Beginner-friendly

Moderate

IDE Autocomplete

Good (Python class)

Good (types exported)

Type Hints

Yes (CameraController class)

Yes (Result and types)

Device management lifecycle

Both APIs handle device discovery, connection, and disconnection, but at different levels.

Pythonic API lifecycle:

import duvc_ctl as duvc

# 1. Discovery (implicit)
# First camera found automatically during construction
with duvc.CameraController() as cam:
    # 2. Connected
    cam.brightness = 75
    # 3. Auto-disconnect on exit

Result-based API lifecycle:

import duvc_ctl as duvc

# 1. Explicit discovery
devices = duvc.list_devices()

# 2. Explicit connection
camera_result = duvc.open_camera(devices[0])
if camera_result.is_ok():
    camera = camera_result.value()
    
    # 3. Use camera
    brightness_result = camera.get(duvc.VidProp.Brightness)
    
    # 4. Implicit disconnect when camera object is destroyed

Error handling strategies

Pythonic API (exception-based):

import duvc_ctl as duvc

try:
    with duvc.CameraController() as cam:
        cam.brightness = 999  # Out of range
except duvc.InvalidValueError as e:
    print(f"Invalid value: {e}")
except duvc.PropertyNotSupportedError:
    print("Brightness not supported")
except duvc.DeviceNotFoundError:
    print("No camera found")

Advantages:

  • Errors interrupt execution; you can’t accidentally ignore them.

  • Idiomatic Python; most libraries use exceptions.

  • Compact code for the happy path.

Disadvantages:

  • Exception handling adds overhead (though typically small).

  • Stack unwinding can complicate debugging in some cases.

Result-based API (explicit):

import duvc_ctl as duvc

devices = duvc.list_devices()
if not devices:
    print("No camera found")
else:
    device = devices[0]
    camera_result = duvc.open_camera(device)
    
    if camera_result.is_ok():
        camera = camera_result.value()
        brightness_result = camera.get(duvc.VidProp.Brightness)
        
        if brightness_result.is_ok():
            setting = brightness_result.value()
            print(f"Brightness: {setting.value}")
        else:
            error = brightness_result.error()
            print(f"Error: {error.description()}")
    else:
        error = camera_result.error()
        print(f"Failed to open camera: {error.description()}")

Advantages:

  • No hidden control flow; every error is explicit.

  • No exception overhead.

  • Detailed error codes and descriptions available.

Disadvantages:

  • More boilerplate (more if statements).

  • Error handling is mandatory; harder to “forget.”

Performance comparison

Both APIs ultimately call the same C++ code, so performance differences are small. However, there are measurable differences in specific scenarios:

Operation

Pythonic

Result-Based

Notes

Single property read (success)

~100 µs

~95 µs

Pythonic has minimal overhead; difference negligible

Single property read (error path)

~200 µs

~100 µs

Exceptions slow down error handling

Rapid property reads (1000x)

~100 ms

~95 ms

Exception overhead adds up over many calls

Device enumeration

~10 ms

~10 ms

Same code path; no difference

Context manager overhead

~5 µs

N/A

Negligible

(These values are estimates and not entirely accurate, timings may differ depending on the system and devices) Practical takeaway: For most use cases, the performance difference is imperceptible. Only if you’re performing thousands of property operations in a tight loop should you consider the Result-based API for performance.

Trade-offs summary

Choose Pythonic if:

  • You’re learning or prototyping.

  • Your code is straightforward with few error cases.

  • You like Python idioms and exceptions.

  • You want less boilerplate.

  • Performance is not critical.

Choose Result-based if:

  • You need detailed error recovery logic.

  • You’re building a production system that must handle failures gracefully.

  • You want explicit, predictable control flow (no exception throwing).

  • You’re processing high volumes of property operations.

  • You need to distinguish between different error types programmatically.

  • You prefer functional APIs and explicit error handling.

Mixing both APIs

You can use both APIs in the same application. The Pythonic API’s CameraController has a .core property that gives you the underlying Result-based Camera object:

import duvc_ctl as duvc

with duvc.CameraController() as cam:
    # Use Pythonic API
    cam.brightness = 75
    
    # Drop down to Result-based API for detailed control
    core_camera = cam.core
    brightness_result = core_camera.get(duvc.VidProp.Brightness)
    
    if brightness_result.is_ok():
        setting = brightness_result.value()
        print(f"Current brightness: {setting.value}")

This gives you flexibility: start simple with the Pythonic API, and switch to explicit Result handling when you need more control.

2.3 Core Design Patterns

This section explains the key design principles that shape duvc-ctl’s architecture, threading model, and internal behavior.

Resource ownership and RAII

duvc-ctl follows the Resource Acquisition Is Initialization (RAII) principle throughout its C++ core. Every resource (COM objects, device handles, property state) is tied to an object’s lifetime.

In C++:

class Device {
public:
    Device() { /* acquire DirectShow resources */ }
    ~Device() { /* release DirectShow resources */ }
private:
    IMFDeviceEnumerator* enumerator;  // Owned; freed in destructor
};

When a Device object is destroyed, all associated DirectShow resources are automatically released. This prevents memory leaks and dangling pointers.

In Python (Pythonic API):

The CameraController manages a device lifecycle implicitly:

with duvc.CameraController() as cam:
    # Resources acquired at __enter__
    cam.brightness = 75
# Resources released at __exit__, even if an exception occurred

The with statement ensures cleanup happens, following Python’s context manager protocol.

In Python (Result-based API):

Resources are explicitly managed:

camera_result = duvc.open_camera(device)
if camera_result.is_ok():
    camera = camera_result.value()
    # Use camera
    # Destructor called when camera goes out of scope

Python’s garbage collector triggers the destructor, which releases C++ resources via pybind11.

Threading and concurrency model

duvc-ctl is designed for multi-threaded environments but with careful constraints.

Module-level thread safety:

The module’s global state (device enumeration cache, module initialization) is protected by an internal mutex. Multiple threads can safely call:

import duvc_ctl as duvc
import threading

def thread_worker(index):
    devices = duvc.list_devices()  # Safe; uses module lock internally
    print(f"Thread {index} found {len(devices)} devices")

threads = [threading.Thread(target=thread_worker, args=(i,)) for i in range(4)]
for t in threads:
    t.start()
for t in threads:
    t.join()

Per-camera thread safety:

Once a device is opened, accessing a single camera from multiple threads is not thread-safe without external synchronization. Each camera is a single-threaded object and must be accessed from the thread it was marshalled from. This is a result of the COM model used by windows.

# BAD: Race condition
import duvc_ctl as duvc
import threading

with duvc.CameraController() as cam:
    def thread_worker():
        cam.brightness = 50  # Unsafe if another thread accesses cam simultaneously
    
    threads = [threading.Thread(target=thread_worker) for _ in range(4)]
    for t in threads: t.start()
    for t in threads: t.join()

# GOOD: Multiple cameras, one per thread
import duvc_ctl as duvc
import threading

devices = duvc.list_devices()

def thread_worker(device_index):
    with duvc.CameraController(device_index) as cam:
        cam.brightness = 50  # Each thread has its own camera; safe

threads = [threading.Thread(target=thread_worker, args=(i,)) for i in range(len(devices))]
for t in threads: t.start()
for t in threads: t.join()

Concurrency strategy:

  • Share devices across threads: Use a lock around camera operations.

  • Don’t share devices: Each thread gets its own camera (preferred).

  • Module-level operations (list_devices(), open_camera()) are always safe.

C++ core vs. Python wrapper layer

duvc-ctl’s architecture has two distinct layers:

C++ Core:

  • Pure C++17 with minimal dependencies.

  • Direct access to Windows COM interfaces (DirectShow).

  • Handles device enumeration, property access, and DirectShow API calls.

  • No Python knowledge; can be used independently or from other languages via C bindings.

Python Wrapper (pybind11):

  • Binds C++ types to Python (Device, Camera, Result, etc.).

  • Translates Python exceptions to C++ exceptions and vice versa.

  • Manages object lifetime (Python GC ↔ C++ destructors).

  • Provides type conversion (Python str ↔ C++ std::string).

The Pythonic API (CameraController) is written entirely in Python and uses the pybind11 bindings internally:

User Python Code
    ↓
CameraController (Python)
    ↓
pybind11 Bindings (Device, Camera, Result<T>)
    ↓
C++ Core
    ↓
DirectShow & Windows COM

This layering allows:

  • The C++ core to evolve independently of Python bindings.

  • Python code to be simple and Pythonic (using Python idioms).

  • The pybind11 layer to be thin (mostly type translations, not business logic).

Move semantics in Python bindings

The C++ core uses move semantics to efficiently transfer ownership of resources without copying:

// C++
Result<Camera> open_camera(const Device& device) {
    auto camera = std::make_unique<Camera>(device);
    return Result<Camera>(std::move(camera));  // Move, don't copy
}

pybind11 preserves this semantic when binding to Python. When you receive a Camera from Python, it’s a move-constructed object with full ownership:

camera_result = duvc.open_camera(device)
if camera_result.is_ok():
    camera = camera_result.value()  # Efficient transfer of ownership

Internally, pybind11 uses holder types to manage the C++ object’s lifetime through Python’s garbage collector. When camera goes out of scope in Python, the C++ object is destroyed and its resources freed.

Connection management state machine

A camera connection follows these states:

State

Description

Valid Transitions

Closed

No active connection to device

→ Opening

Opening

Attempting to connect

→ Open, → Closed (on failure)

Open

Connected; properties can be read/written

→ Closing

Closing

Disconnecting

→ Closed

Error

Connection failed or lost

→ Opening (retry)

Pythonic API state transitions:

with duvc.CameraController() as cam:  # Closed → Opening → Open
    cam.brightness = 75                # Operations in Open state
# Open → Closing → Closed

Result-based API state transitions:

camera_result = duvc.open_camera(device)  # Closed → Opening
if camera_result.is_ok():                  # Succeeded; now Open
    camera = camera_result.value()
    brightness_result = camera.get(duvc.VidProp.Brightness)
    if brightness_result.is_ok():
        setting = brightness_result.value()
# Open → Closing → Closed (on camera destruction)

State violations (e.g., trying to access a property in Closed state) raise an exception or return an error.

Device discovery patterns

Device discovery follows a lazy enumeration pattern:

  1. On demand: Devices are discovered when list_devices() is called, not at module import.

  2. Caching: The device list is cached; repeated calls are fast.

  3. Invalidation: The cache is invalidated if device hotplug events are detected (if callback registered).

Example:

import duvc_ctl as duvc

# First call: actual enumeration via DirectShow
devices1 = duvc.list_devices()

# Second call: returns cached list (no DirectShow overhead)
devices2 = duvc.list_devices()

# Register for device change notifications
def on_device_change(added, device_path):
    print(f"Device {'added' if added else 'removed'}: {device_path}")

duvc.register_device_change_callback(on_device_change)

# When a device is plugged/unplugged, the callback fires and the cache is invalidated

Thread safety guarantees

duvc-ctl provides these thread-safety guarantees:

Operation

Thread-Safe

Notes

list_devices()

✓ Yes

Internally synchronized

open_camera(device)

✓ Yes

Returns independent Camera object

camera.get(property) (single camera)

✗ No

Use lock if accessing from multiple threads

camera.set(property, value) (single camera)

✗ No

Use lock if accessing from multiple threads

Multiple cameras in different threads

✓ Yes

Each camera is isolated

Device change callbacks

✓ Yes

Callbacks are thread-safe; executed on internal worker thread

register_device_change_callback()

✓ Yes

Safe to call from any thread

Safe multi-threaded pattern:

import duvc_ctl as duvc
import threading
from threading import Lock

devices = duvc.list_devices()

# One camera per thread: no lock needed
def worker(device_index):
    with duvc.CameraController(device_index) as cam:
        cam.brightness = 75

threads = [threading.Thread(target=worker, args=(i,)) for i in range(len(devices))]
for t in threads: t.start()
for t in threads: t.join()

Unsafe pattern (and how to fix it):

# UNSAFE: Multiple threads accessing same camera
with duvc.CameraController() as cam:
    def worker():
        cam.brightness = 75  # Race condition!
    
    threads = [threading.Thread(target=worker) for _ in range(4)]
    # ...

# SAFE: Use a lock
with duvc.CameraController() as cam:
    lock = Lock()
    
    def worker():
        with lock:
            cam.brightness = 75  # Protected by lock
    
    threads = [threading.Thread(target=worker) for _ in range(4)]
    # ...