webcam

README

go-webcam

This is a go library for working with webcams and other video capturing devices. It depends entirely on V4L2 framework, thus will compile and work only on Linux machine.

Installation

$ go get github.com/blackjack/webcam

Usage

import "github.com/blackjack/webcam"
// ...
cam, err := webcam.Open("/dev/video0") // Open webcam
if err != nil { panic(err.Error()) }
defer cam.Close()
// ...
// Setup webcam image format and frame size here (see examples or documentation)
// ...
err = cam.StartStreaming()
if err != nil { panic(err.Error()) }
for {
  err = cam.WaitForFrame(timeout)

  switch err.(type) {
  case nil:
  case *webcam.Timeout:
    fmt.Fprint(os.Stderr, err.Error())
    continue
  default:
    panic(err.Error())
  }

  frame, err := cam.ReadFrame()
  if len(frame) != 0 {
   // Process frame
  } else if err != nil {
    panic(err.Error())
  }
}

For more detailed example see examples folder The number of frame buffers used may be set as:

// If already streaming, stop streaming.
if streaming_on {
  cam.StopStreaming()
}
err = cam.SetBufferCount(64)

Roadmap

The library is still under development so API changes can happen. Currently library supports streaming using only MMAP method, which should be sufficient for most of devices available on the market. Other streaming methods can be added in future (please create issue if you need this).

Also currently image format is defined by 4-byte code received from V4L2, which is good in terms of compatibility with different versions of Linux kernel, but not very handy if you want to do some image manipulations. Plans are to aligh V4L2 image format codes with Image package from Go library.

License

See LICENSE file

Documentation

Index

• Constants
• Variables
• func CToGoString(c []byte) string
• func Compress(frame []byte, format string, width uint32, height uint32, quality uint32, ...) ([]byte, string, error)
• func CompressionAvailable(format string) bool
• func DecodeFormat(format PixelFormat) string
• type Camera
  • func Open(path string) (*Camera, error)
  • func (w *Camera) Card() (string, error)
  • func (w *Camera) Close() error
  • func (w *Camera) GetControl(id ControlID) (int32, error)
  • func (w *Camera) GetControls() map[ControlID]Control
  • func (w *Camera) GetFrame() ([]byte, uint32, error)
  • func (w *Camera) GetSupportedFormats() map[PixelFormat]string
  • func (w *Camera) GetSupportedFrameSizes(f PixelFormat) []FrameSize
  • func (w *Camera) ReadFrame() ([]byte, error)
  • func (w *Camera) ReleaseFrame(index uint32) error
  • func (w *Camera) SetAutoWhiteBalance(val bool) error
  • func (w *Camera) SetBufferCount(count uint32) error
  • func (w *Camera) SetControl(id ControlID, value int32) error
  • func (w *Camera) SetImageFormat(f PixelFormat, width, height uint32) (PixelFormat, uint32, uint32, error)
  • func (w *Camera) StartStreaming() error
  • func (w *Camera) StopStreaming() error
  • func (w *Camera) WaitForFrame(timeout uint32) error
• type Control
• type ControlID
• type FrameSize
  • func (s FrameSize) GetString() string
• type PixelFormat
  • func EncodeFormat(value string) PixelFormat
• type Timeout
  • func (e *Timeout) Error() string

Constants

const (
	V4L2_CAP_VIDEO_CAPTURE      uint32 = 0x00000001
	V4L2_CAP_STREAMING          uint32 = 0x04000000
	V4L2_BUF_TYPE_VIDEO_CAPTURE uint32 = 1
	V4L2_MEMORY_MMAP            uint32 = 1
	V4L2_FIELD_ANY              uint32 = 0
)

const (
	V4L2_FRMSIZE_TYPE_DISCRETE   uint32 = 1
	V4L2_FRMSIZE_TYPE_CONTINUOUS uint32 = 2
	V4L2_FRMSIZE_TYPE_STEPWISE   uint32 = 3
)

const (
	V4L2_CID_BASE               uint32 = 0x00980900
	V4L2_CID_AUTO_WHITE_BALANCE uint32 = V4L2_CID_BASE + 12
	V4L2_CID_PRIVATE_BASE       uint32 = 0x08000000
)

const (
	V4L2_CTRL_TYPE_INTEGER      uint32 = 1
	V4L2_CTRL_TYPE_BOOLEAN      uint32 = 2
	V4L2_CTRL_TYPE_MENU         uint32 = 3
	V4L2_CTRL_TYPE_BUTTON       uint32 = 4
	V4L2_CTRL_TYPE_INTEGER64    uint32 = 5
	V4L2_CTRL_TYPE_CTRL_CLASS   uint32 = 6
	V4L2_CTRL_TYPE_STRING       uint32 = 7
	V4L2_CTRL_TYPE_BITMASK      uint32 = 8
	V4L2_CTRL_TYPE_INTEGER_MENU uint32 = 9

	V4L2_CTRL_COMPOUND_TYPES uint32 = 0x0100
	V4L2_CTRL_TYPE_U8        uint32 = 0x0100
	V4L2_CTRL_TYPE_U16       uint32 = 0x0101
	V4L2_CTRL_TYPE_U32       uint32 = 0x0102
)

const (
	V4L2_CTRL_FLAG_DISABLED  uint32 = 0x00000001
	V4L2_CTRL_FLAG_NEXT_CTRL uint32 = 0x80000000
)

Variables

var (
	VIDIOC_QUERYCAP  = ioctl.IoR(uintptr('V'), 0, unsafe.Sizeof(v4l2_capability{}))
	VIDIOC_ENUM_FMT  = ioctl.IoRW(uintptr('V'), 2, unsafe.Sizeof(v4l2_fmtdesc{}))
	VIDIOC_S_FMT     = ioctl.IoRW(uintptr('V'), 5, unsafe.Sizeof(v4l2_format{}))
	VIDIOC_REQBUFS   = ioctl.IoRW(uintptr('V'), 8, unsafe.Sizeof(v4l2_requestbuffers{}))
	VIDIOC_QUERYBUF  = ioctl.IoRW(uintptr('V'), 9, unsafe.Sizeof(v4l2_buffer{}))
	VIDIOC_QBUF      = ioctl.IoRW(uintptr('V'), 15, unsafe.Sizeof(v4l2_buffer{}))
	VIDIOC_DQBUF     = ioctl.IoRW(uintptr('V'), 17, unsafe.Sizeof(v4l2_buffer{}))
	VIDIOC_G_CTRL    = ioctl.IoRW(uintptr('V'), 27, unsafe.Sizeof(v4l2_control{}))
	VIDIOC_S_CTRL    = ioctl.IoRW(uintptr('V'), 28, unsafe.Sizeof(v4l2_control{}))
	VIDIOC_QUERYCTRL = ioctl.IoRW(uintptr('V'), 36, unsafe.Sizeof(v4l2_queryctrl{}))
	//sizeof int32
	VIDIOC_STREAMON        = ioctl.IoW(uintptr('V'), 18, 4)
	VIDIOC_STREAMOFF       = ioctl.IoW(uintptr('V'), 19, 4)
	VIDIOC_ENUM_FRAMESIZES = ioctl.IoRW(uintptr('V'), 74, unsafe.Sizeof(v4l2_frmsizeenum{}))

	NativeByteOrder = getNativeByteOrder()
)

Functions

func CToGoString

func CToGoString(c []byte) string

func Compress

func Compress(frame []byte, format string, width uint32, height uint32, quality uint32, rotation string, rwidth int, rheight int) ([]byte, string, error)

Conversion of raw image formats to compressed jpegs Conversion is categorised by a string 4CC code for code readibility

func CompressionAvailable

func CompressionAvailable(format string) bool

Interface to check if format is supported

func DecodeFormat

func DecodeFormat(format PixelFormat) string

Types

type Camera

type Camera struct {
	// contains filtered or unexported fields
}

Camera object

func Open

func Open(path string) (*Camera, error)

Open a camera with a given path Checks if device is a v4l2 device and if it is capable to stream video

func (*Camera) Card

func (w *Camera) Card() (string, error)

Get the card/name of the device

func (*Camera) Close

func (w *Camera) Close() error

Close the device

func (*Camera) GetControl

func (w *Camera) GetControl(id ControlID) (int32, error)

Get the value of a control.

func (*Camera) GetControls

func (w *Camera) GetControls() map[ControlID]Control

Get a map of available controls.

func (*Camera) GetFrame

func (w *Camera) GetFrame() ([]byte, uint32, error)

Get a single frame from the Camera and return the frame and the buffer index. To return the buffer, ReleaseFrame must be called. If frame cannot be read at the moment function will return empty slice

func (*Camera) GetSupportedFormats

func (w *Camera) GetSupportedFormats() map[PixelFormat]string

Returns image formats supported by the device alongside with their text description

func (*Camera) GetSupportedFrameSizes

func (w *Camera) GetSupportedFrameSizes(f PixelFormat) []FrameSize

Returns supported frame sizes for a given image format

func (*Camera) ReadFrame

func (w *Camera) ReadFrame() ([]byte, error)

Read a single frame from the Camera If frame cannot be read at the moment function will return empty slice

func (*Camera) ReleaseFrame

func (w *Camera) ReleaseFrame(index uint32) error

Release the frame buffer that was obtained via GetFrame

func (*Camera) SetAutoWhiteBalance

func (w *Camera) SetAutoWhiteBalance(val bool) error

Sets automatic white balance correction

func (*Camera) SetBufferCount

func (w *Camera) SetBufferCount(count uint32) error

Set the number of frames to be buffered. Not allowed if streaming is already on.

func (*Camera) SetControl

func (w *Camera) SetControl(id ControlID, value int32) error

Set a control.

func (*Camera) SetImageFormat

func (w *Camera) SetImageFormat(f PixelFormat, width, height uint32) (PixelFormat, uint32, uint32, error)

Sets desired image format and frame size Note, that device driver can change that values. Resulting values are returned by a function alongside with an error if any

func (*Camera) StartStreaming

func (w *Camera) StartStreaming() error

Start streaming process

func (*Camera) StopStreaming

func (w *Camera) StopStreaming() error

func (*Camera) WaitForFrame

func (w *Camera) WaitForFrame(timeout uint32) error

Wait until frame could be read

type Control

type Control struct {
	Name string
	Min  int32
	Max  int32
}

type ControlID

type ControlID uint32

type FrameSize

type FrameSize struct {
	MinWidth  uint32
	MaxWidth  uint32
	StepWidth uint32

	MinHeight  uint32
	MaxHeight  uint32
	StepHeight uint32
}

Struct that describes frame size supported by a webcam For fixed sizes min and max values will be the same and step value will be equal to '0'

func (FrameSize) GetString

func (s FrameSize) GetString() string

Returns string representation of frame size, e.g. 1280x720 for fixed-size frames and [320-640;160]x[240-480;160] for stepwise-sized frames

type PixelFormat

type PixelFormat uint32

Represents image format code used by V4L2 subsystem.

func EncodeFormat

func EncodeFormat(value string) PixelFormat

Functions allow the conversion of PixelFormats to and from human readable 4CC strings ie; "YUYV" to 0x55595659 and vice versa

type Timeout

type Timeout struct{}

Timeout error

func (*Timeout) Error

func (e *Timeout) Error() string