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, os, urandom, sys, gc

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

DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480

# use lcd as display output
Display.init(Display.ST7701, width = DISPLAY_WIDTH, height = DISPLAY_HEIGHT, to_ide = True)
# init media manager
MediaManager.init()

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

mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30)

succ, mode = UVC.select_video_mode(mode)
print(f"select mode success: {succ}, mode: {mode}")

UVC.start(cvt = False)

fps = time.clock()

while True:
    fps.tick()
    img = UVC.snapshot()
    if img is not None:
        try:
            img = img.to_rgb565()
            Display.show_image(img)
            img.__del__()
            gc.collect()
        except OSError as e:
            pass

    print(f"fps: {fps.fps()}")

# deinit display
Display.deinit()
UVC.stop()
time.sleep_ms(100)
# release media buffer
MediaManager.deinit()

Hardware Decoding Example

import time, os, urandom, sys, gc

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

from nonai2d import CSC

DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480

csc = CSC(0, CSC.PIXEL_FORMAT_RGB_565)

# use lcd as display output
Display.init(Display.ST7701, width = DISPLAY_WIDTH, height = DISPLAY_HEIGHT, to_ide = True)
# init media manager
MediaManager.init()

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

mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30)

succ, mode = UVC.select_video_mode(mode)
print(f"select mode success: {succ}, mode: {mode}")

UVC.start(cvt = True)

clock = time.clock()

while True:
    clock.tick()

    img = None
    while img is None:
        try:
            img = UVC.snapshot()
        except:
            print("drop frame")
            continue

    img = csc.convert(img)
    Display.show_image(img)
    img.__del__()
    gc.collect()

    print(f"fps: {clock.fps()}")

# deinit display
Display.deinit()
csc.destroy()
UVC.stop()
time.sleep_ms(100)
# release media buffer
MediaManager.deinit()