ASIMOV Camera Module

An ASIMOV module that streams camera frames via FFmpeg and emits one JSON-LD Image per frame to stdout.

✨ Features

• To be determined!

🛠️ Prerequisites

• Rust 1.85+ (2024 edition)
• FFmpeg installed and on PATH (ffmpeg must be callable)

⬇️ Installation

Installation with the ASIMOV CLI

asimov module install camera -v

Installation from Source Code

cargo install asimov-camera-module

👉 Examples

Basic camera stream

asimov-camera-reader

(file:/dev/video0 is used by default.)

Enumerate cameras (text)

# Short summary (IDs + human names)
asimov-camera-cataloger

# Verbose (descriptions, misc info, resolutions, frame rates)
asimov-camera-cataloger -v

Enumerate cameras (JSONL)

# JSONL with logical IDs and formats
asimov-camera-cataloger --output jsonl

# Pipe into jq
asimov-camera-cataloger --output jsonl | jq .

Then take the id from the cataloger output and plug it into the reader:

# Using a discovered device, e.g. "file:/dev/video2"
asimov-camera-reader <device-id>

⚙ Configuration

This module requires no configuration.

📚 Reference

Installed Binaries

• asimov-camera-reader — streams camera frames as JSONL KNOW Image objects.
• asimov-camera-cataloger — lists available camera devices and their supported formats.

asimov-camera-reader

Usage: asimov-camera-reader [OPTIONS] [device]

Arguments:
  [device]  Input camera device (default: file:/dev/video0)

Options:
  -s, --size <WxH>      Desired dimensions (e.g. 640x480, 1920x1080) [default: 640x480]
  -f, --frequency <Hz>  Sampling frequency in Hz (frames per second) [default: 30]
  -D, --debounce...     Debounce level (repeat flag to increase threshold)
  -d, --debug           Enable debugging output
      --license         Show license information
  -v, --verbose...      Enable verbose output (repeat for more verbosity)
  -V, --version         Print version information
  -h, --help            Print help

Device examples

macOS (avfoundation)

Use 0, 1, … (the module maps file:/dev/videoN → N)

asimov-camera-reader 0
asimov-camera-reader --size 1280x720 --frequency 15 0

Linux (v4l2)

asimov-camera-reader 0
asimov-camera-reader file:/dev/video2 -s 1920x1080 -f 30

Windows (dshow)

asimov-camera-reader "video=Integrated Camera"

Debounce

Each -D raises the Hamming-distance threshold (perceptual hash):

asimov-camera-reader -D        # low debounce
asimov-camera-reader -DDD      # stricter

Note

The --frequency option controls how often frames are emitted by the CLI. On some platforms (notably macOS), the actual capture rate is determined by the camera and FFmpeg, and the output is throttled to the requested frequency.

asimov-camera-cataloger

Usage: asimov-camera-cataloger [OPTIONS]

Options:
  -o, --output <FORMAT>  Output format [default: text] [possible values: text, jsonl]
  -d, --debug            Enable debugging output
      --license          Show license information
  -v, --verbose...       Enable verbose output (repeat for more verbosity)
  -V, --version          Print version information
  -h, --help             Print help

Text output

asimov-camera-cataloger
# file:/dev/video0: Integrated Camera
# file:/dev/video1: USB Camera

JSONL output

asimov-camera-cataloger --output jsonl | jq .

Each line is a single device:

{
  "id": "file:/dev/video0",
  "name": "Integrated Camera",
  "usb": false
}

Use the id field with asimov-camera-reader.

Output (JSON-LD Image)

JSONL

One JSON object per line:

{
  "@type": "Image",
  "@id": "file:/dev/video0#1763041205",
  "width": 640,
  "height": 480,
  "source": "file:/dev/video0",
  "data": "data:image/rgb;base64,AAAA..."
}

Note

Note that the image data must be the uncompressed raw 24-bit RGB data, Base64-encoded into a data:image/rgb;base64,... URL.

👨‍💻 Development

git clone https://github.com/asimov-modules/asimov-camera-module.git