ccap (CameraCapture)

The ccap C interface provides full camera capture functionality using an opaque pointer pattern to hide C++ implementation details.

Opaque Pointers

• CcapProvider*: Encapsulates the ccap::Provider object for device management and control.
• CcapVideoFrame*: Encapsulates a ccap::VideoFrame shared pointer.

Memory Management Principles

1. Creation and Destruction: Every object created via ccap_xxx_create() must be released using its corresponding ccap_xxx_destroy() function.
2. Array Release: Use specialized release functions for arrays of strings or structures returned by the API.
3. Frame Management: Frames obtained via ccap_provider_grab() must be released using ccap_video_frame_release() to prevent memory leaks.

Windows

• DirectShow: The default backend. Stable and widely compatible. If certain VR headsets cause crashes during enumeration, build with -DCCAP_WIN_NO_DEVICE_VERIFY=ON.
• Media Foundation (msmf): Supported via explicit selection. Uses Source Reader for frame acquisition.
• Virtual Cameras: Supports OBS Virtual Camera, ManyCam, and NDI Virtual Input.

macOS / iOS

• AVFoundation: The modern, high-performance backend. Supports native formats like NV12 and BGRA.
• Permissions: Ensure NSCameraUsageDescription is set in your Info.plist.

Linux

• V4L2: Direct kernel interface with low overhead and wide format support.
• Permissions: Users must be in the video group to access devices (sudo usermod -a -G video $USER).

ccap automatically switches its frame delivery strategy based on the source provided to provider.open():

• Camera Mode: Optimized for real-time/low latency. It prioritizes the latest frames. If your processing loop is slower than the camera's frame rate, old frames are automatically dropped to keep the stream current.
• File Mode: Optimized for completeness. It ensures every single frame is preserved. It uses a backpressure mechanism where the decoder pauses reading when the internal buffer is full and resumes only when you call grab(). This allows you to process extremely long videos with constant, bounded memory usage and zero frame loss.

// Camera Mode (prioritizes latest, drops old)
ccap::Provider provider;
provider.open(0, true); 

// File Mode (preserves all, uses backpressure)
ccap::Provider provider;
provider.open("video.mp4", true);

The ccap library provides two distinct interfaces:

• C Interface: Uses opaque pointers and manual memory management. It is designed for pure C projects and for creating language bindings (e.g., for Python, Go, or Rust) because it provides a stable ABI.
• C++ Interface: Uses smart pointers and RAII (Resource Acquisition Is Initialization) for a more modern and safer developer experience.

Warning: Do not mix C and C++ interfaces within the same program. They manage different internal states, and mixing them may lead to undefined behavior or errors.

Standalone skills in this repository are designed to be reusable general agent skills. To ensure compatibility and portability, every standalone skill must adhere to the following structural rules:

• Location: Each skill must reside in its own dedicated folder under the skills/ directory.
• Documentation: The skill folder must contain a top-level SKILL.md file.
• File Types: All supporting files within the skill folder must be text-based.
• Metadata: Frontmatter used for configuration or metadata must remain concise and machine-parseable.
• Packaging: When publishing or packaging a skill, commands must target the specific skill folder rather than the repository root.

Currently, the repository includes the following standalone skill:

• ccap (located in ./ccap)

On Windows, ccap defaults to DirectShow for maximum compatibility with virtual cameras (like OBS Virtual Camera). Media Foundation (MSMF) is also supported.

• auto mode (Default): Merges both backends. It routes devices to the most compatible backend automatically.
• Explicit Selection: You can force a backend via the constructor or an environment variable.

Environment Variable: Set CCAP_WINDOWS_BACKEND to auto, msmf, or dshow.

C++ Explicit Selection:

// Force Media Foundation
ccap::Provider msmfProvider("", "msmf");

// Force DirectShow
ccap::Provider dshowProvider("", "dshow");

# PowerShell: opt into Media Foundation for the current process
$env:CCAP_WINDOWS_BACKEND = "msmf"
.\ccap --list-devices

On Windows, you can choose between dshow (DirectShow) and msmf (Media Foundation). DirectShow is the default and offers better compatibility with virtual cameras like OBS Virtual Camera.

To select a backend, you can:

1. Set the CCAP_WINDOWS_BACKEND environment variable to auto, msmf, or dshow.
2. Use one of the following Rust API methods and pass the backend string (e.g., "msmf" or "dshow") as part of the extra info:
   • Provider::with_device_name_and_extra_info
   • Provider::with_device_and_extra_info
   • Provider::open_device_with_extra_info
   • Provider::open_with_index_and_extra_info

ccap operates in two primary modes with different memory and frame handling behaviors:

1. Camera Mode: Optimized for live streaming and real-time use. It uses bounded memory and employs a frame-dropping strategy (keeping only the latest frame) to maintain low latency.
2. File Mode: Optimized for video analysis and processing. It uses bounded memory but employs a backpressure mechanism instead of dropping frames, ensuring every frame is processed.

To use File Mode in C++, pass true to the open method to enable playback/file behavior.

// File mode: process all frames without dropping
ccap::Provider provider;
provider.open("video.mp4", true); // true enables file/playback mode

while (auto frame = provider.grab(1000)) {
    // Backpressure ensures no frames are lost
    // Memory remains constant (approx 25-30MB for HD)
    processFrame(frame);
}

When using ccap, keep the following operational constraints in mind:

• Permissions: Do not assume camera permissions are automatically granted.
• Headless Environments: Avoid defaulting to preview modes in headless environments.
• Platform Differences: Video playback feature support varies; do not assume Linux supports the same features as macOS or Windows.
• Parsing: Always prefer JSON parsing via the --json flag over text scraping for reliability.