Skip to content
Smelter logo Smelter logo Smelter

Video for Linux 2 (V4L2 API)

An input type that allows Smelter to capture video using the Video for Linux 2 API. V4L2 devices can be found in paths that look like this:

  • /dev/video[N], where N is the device number,
  • /dev/v4l/by-id/[DEVICE ID],
  • /dev/v4l/by-path/[PCI/USB PATH].

Usage

To use the V4L2 Input you must register it first. You can do it by sending a request like this:

Example request 

POST: /api/input/:input_id/register
Content-Type: application/json


{
  "type": "v4l2",
  "path": "/dev/video0",
  "format": "yuyv",
  "resolution": {
    "width": 1920,
    "height": 1080,
  },
  "framerate": 30,
}

See HTTP Routes documentation to learn more about managing inputs.

Reference

Type definition 

type RegisterV4l2Input = {
  type: "v4l2";
  path: string;
  format: "yuyv" | "nv12";
  resolution?: {
    width: u32;
    height: u32;
  };
  framerate?: u32 | string;
  required?: bool;
  side_channel?: SideChannel;
};

Parameters for registering a V4L2 device as an input.

Properties

path

Path to the V4L2 device.

  • Type: string

format

A format used for video capture.

  • Type: "yuyv" | "nv12"
  • Supported values:
    • yuyv - YUYV, which is a form of interleaved 4:2:2 YUV.
    • nv12 - NV12, which is a form of planar 4:2:0 YUV, with one plane for Y and a second plane for interleaved UV.

resolution

The capture resolution. This value may be changed by the device driver to the closest resolution supported at the selected format. If not provided, the input will use the default resolution for the given format.

  • Type: { width: u32; height: u32; }

framerate

Video framerate. This value may be changed by the device driver to the closest framerate supported at the selected format and resolution. Has to be either a u32 or a string in the "NUM/DEN" form, representing a fraction. If not provided, the input will use the default framerate for the given format and resolution.

  • Type: u32 | string

required

Determines if the input stream is essential for output frame production. If set to true and the stream is delayed, Smelter will postpone output frames until the stream is received.

  • Type: bool
  • Default value: false

side_channel

Enable side channel publishing for this input. The external consumer reads decoded frames / audio from a Unix socket created under SMELTER_SIDE_CHANNEL_SOCKET_DIR.

SideChannel

Per-track side channel configuration. See the Side Channel overview for details on how decoded data is exposed and consumed.

Type definition 

type SideChannel = {
  video?: bool;
  audio?: bool;
  delay_ms?: f64;
};

Properties

video

Publish decoded RGBA video frames for this input on the side channel.

  • Type: bool
  • Default value: false

audio

Publish decoded PCM audio batches for this input on the side channel.

  • Type: bool
  • Default value: false

delay_ms

Side channel delay in milliseconds. Frames are buffered for this duration ahead of when the queue consumes them, so the side-channel subscriber receives them early and has roughly this much time to process before the frame is due.

  • Type: f64
  • Default value: 0