UVC API Manual

Overview

The UVC module provides USB camera detection, configuration, and image capture functionality, supporting single-camera operation.

API Reference

UVC.probe - Detect Camera

Function Checks whether a USB camera is connected to the system (currently supports single-camera detection only).

Syntax

from media.uvc import UVC
plugin, devname = UVC.probe()

Return Values

Parameter	Type	Description
plugin	bool	True if camera is detected, False otherwise
devname	str	Camera device information in “Manufacturer#Product” format

Example

plugin, devinfo = UVC.probe()
print(f"Camera detection: {'Connected' if plugin else 'Not connected'}, Device info: {devinfo}")

UVC.video_mode - Video Mode Operations

Function Constructs or retrieves the current video mode configuration.

Syntax

# Get current mode
mode = UVC.video_mode()

# Create new configuration
mode = UVC.video_mode(width, height, format, fps)

Parameters

Parameter	Type	Description
width	int	Resolution width in pixels
height	int	Resolution height in pixels
format	int	Image format (see constant definitions)
fps	int	Frame rate in fps

Return Value Returns a uvc_video_mode object.

UVC.list_video_mode - List Supported Modes

Function Retrieves all video modes supported by the camera.

Syntax

modes = UVC.list_video_mode()

Return Value Returns a list of supported uvc_video_mode objects.

Example

for i, mode in enumerate(UVC.list_video_mode()):
    print(f"Mode {i}: {mode.width}x{mode.height} {mode.format}@{mode.fps}fps")

UVC.select_video_mode - Select Video Mode

Function Sets the camera output mode.

Syntax

succ, actual_mode = UVC.select_video_mode(mode)

Parameters

Parameter	Type	Description
mode	uvc_video_mode	Video mode configuration to set

Return Values

Parameter	Type	Description
succ	bool	True if setting was successful
actual_mode	uvc_video_mode	The actual mode that was applied

UVC.start - Start Video Stream

Function Starts the camera video stream output.

Syntax

success = UVC.start(delay_ms=0, cvt=True)

Parameters

Parameter	Type	Description
delay_ms	int	Delay in milliseconds to wait for UVC camera data output (default: 0)
cvt	bool	Whether to hardware-decode snapshot images to NV12 format (default: True)

Return Value Returns True if the stream started successfully.

UVC.stop - Stop Video Stream

Function Stops the video stream and releases resources.

Syntax

UVC.stop()

UVC.snapshot - Capture Frame

Function Captures a single frame from the video stream.

Syntax

frame = UVC.snapshot(timeout_ms=1000)

Parameters

Parameter	Type	Description
timeout_ms	int	Timeout in milliseconds for frame capture (default: 1000)

Return Value Returns image data in NV12 Frame format (if hardware decoding enabled) or JPEG/YUV422 format.

Data Structures

uvc_video_mode Structure

class uvc_video_mode:
    width: int    # Resolution width in pixels
    height: int   # Resolution height in pixels
    format: int   # Image format (see constants)
    fps: int      # Frame rate in fps

Constant Definitions

Constant	Value	Description
UVC.FORMAT_MJPEG	1	MJPG compressed format (recommended for low bandwidth)
UVC.FORMAT_UNCOMPRESS	2	YUV422 uncompressed format (requires higher bandwidth)

Recommended Workflow

1. Detect camera (probe())

2. List supported modes (list_video_mode())

3. Select an appropriate mode (select_video_mode())

4. Start video stream (start())

5. Capture images (snapshot())

6. Stop video stream (stop())

Best Practices

Software Decoding Example

import time
from media.display import *
from media.media import *
from media.uvc import *

DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480

# Initialize LCD display
Display.init(Display.ST7701, width=DISPLAY_WIDTH, height=DISPLAY_HEIGHT, to_ide=True)
# Initialize media manager
MediaManager.init()

# Detect camera
while True:
    plugin, dev = UVC.probe()
    if plugin:
        print(f"Detected USB Camera: {dev}")
        break

# Set video mode
mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30)
succ, mode = UVC.select_video_mode(mode)
print(f"Mode selection: {'Success' if succ else 'Failed'}, Actual mode: {mode}")

# Start video stream
UVC.start()

try:
    while True:
        img = UVC.snapshot()
        if img is not None:
            img = img.to_rgb565()  # Convert to RGB565 format
            Display.show_image(img)  # Display image
finally:
    # Cleanup resources
    Display.deinit()
    UVC.stop()
    time.sleep_ms(100)
    MediaManager.deinit()

Hardware Decoding Example

import time
from media.display import *
from media.media import *
from media.uvc import *
from nonai2d import CSC  # Hardware Color Space Converter

DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480

# Initialize hardware color space converter
csc = CSC(0, CSC.PIXEL_FORMAT_RGB_565)

# Initialize LCD display
Display.init(Display.ST7701, width=DISPLAY_WIDTH, height=DISPLAY_HEIGHT, to_ide=True)
# Initialize media manager
MediaManager.init()

# Detect camera
while True:
    plugin, dev = UVC.probe()
    if plugin:
        print(f"Detected USB Camera: {dev}")
        break
    time.sleep_ms(100)

# Set video mode
mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30)
succ, mode = UVC.select_video_mode(mode)
print(f"Mode selection: {'Success' if succ else 'Failed'}, Actual mode: {mode}")

# Start video stream with hardware decoding
UVC.start(cvt=True)

clock = time.clock()  # For FPS calculation

try:
    while True:
        clock.tick()

        img = UVC.snapshot()
        if img is not None:
            img = csc.convert(img)  # Hardware color space conversion
            Display.show_image(img)

        print(f"Current FPS: {clock.fps()}")
finally:
    # Cleanup resources
    Display.deinit()
    csc.destroy()
    UVC.stop()
    time.sleep_ms(100)
    MediaManager.deinit()