This release primarily introduces a new fix to the Device API which was forcing an awkward call sequence (see #95). The release also introduces many new features and enhancements.

Fixes

• Fixes Start()/GetOutput()/GetFrames() ordering issue (#95) — allow calling Start() before selecting a
  streaming API
• Start() now handles buffer queueing and StreamOn directly, without requiring a streaming mode to be
  pre-selected
• GetOutput() / GetFrames() can be called after Start()
• Calling the wrong streaming API (e.g., GetFrames() after GetOutput()) now panics

End-to-end Testin Enhancements

Overhaul integration test infrastructure to support both real devices and v4l2loopback emulation cleanly. This allows tests to run on a device such as Raspberry Pi with a camera attached or in a CI/CD environment. End-to-end integration tests are important to catch issues that unit tests are not capable of revealing.

sudo modprobe v4l2loopback devices=2 video_nr=42,43 card_label="go4vl_test_1,go4vl_test_2" exclusive_caps=0
go test -v -tags=integration ./test/... -args -use-device-emulation=/dev/video42,/dev/video43

New test flags

• -use-device=auto — auto-discover real V4L2 devices
• -use-device=/dev/video0 — use specific real device
• -use-device-emulation=auto — auto-discover or load v4l2loopback
• -use-device-emulation=/dev/video42,/dev/video43 — use specific loopback devices
• No flags — auto-detect (tries loopback first, then real devices)

New Hardware Codecs
Implement new V4L2 codec support for hardware-accelerated video encoding/decoding:

• Codec Commands: Full support for VIDIOC_ENCODER_CMD and VIDIOC_DECODER_CMD ioctls including START, STOP, PAUSE, RESUME, and FLUSH operations
• State Machine: codec state machine (Uninitialized → Initialized → Streaming → Draining → Stopped)
  with validation for legal transitions
• M2M Device Support: functions for memory-to-memory codec devices with dual OUTPUT/CAPTURE queue management
• Dynamic Resolution Changes: Decoder support for handling mid-stream resolution changes via V4L2 events
• High-Level Abstractions: Channel-based Encoder and Decoder types in the device package with simple feed/receive
  patterns

What's Changed

• issue-108 - chore: Implement missing data formats and flags by @vladimirvivien in #109
• issue-110: Hardware-supported encodeing/decoding by @vladimirvivien in #111

Full Changelog: 0.4.0...v0.5.0

Release Notes: v0.3.0

Breaking Changes

Removed Vendored Linux Headers (#88)

The vendored Linux kernel headers (include/linux/ directory) have been removed from the repository. go4vl now requires system V4L2 kernel headers to be installed.

Migration Required:

Users must install V4L2 kernel headers on their system:

# Ubuntu/Debian
sudo apt install linux-libc-dev

# Fedora/RHEL/CentOS
sudo dnf install kernel-headers

# Arch Linux
sudo pacman -S linux-headers

# Alpine Linux
apk add linux-headers

Why this change?

• Follows Linux kernel documentation best practices for user-space applications
• Reduces repository size by ~5,500 lines of vendored code
• Simplifies maintenance and ensures headers stay up-to-date with the system
• Provides flexibility for users to choose kernel header versions

Using Custom Headers:

If you need specific kernel header versions or are cross-compiling, use the CGO_CFLAGS environment variable:

CGO_CFLAGS="-I/path/to/custom/headers" go build ./v4l2

See docs/BUILD.md for comprehensive build instructions.

Build System Enhancements (#88)

New Build Documentation

• Added comprehensive docs/BUILD.md with detailed build instructions
• Covers prerequisite installation for multiple Linux distributions
• Includes cross-compilation guides (GCC, Zig, Docker)
• Platform-specific instructions for Raspberry Pi, WSL2, and more
• Troubleshooting section for common build issues

Updated Build Instructions

• Enhanced README.md with new "Building" section
• Updated examples/README.md with header installation steps
• Documented CGO_CFLAGS override mechanism for custom headers
• Added examples for cross-compilation with custom headers

CGo Configuration

• Centralized CGo directives in v4l2/cgo.go
• Default configuration uses system headers from /usr/include
• Simplified CGo setup with clear documentation on overrides
• Better support for cross-compilation scenarios

Cleanup (#86)

Removed Unsupported Code

• Removed multipass directory and related code
• Cleaned up legacy/deprecated packages
• Repository structure simplified for better maintainability

Documentation Improvements

Build System Documentation

• New comprehensive build guide covering all major Linux distributions
• Cross-compilation instructions for ARM (32-bit and 64-bit)
• Docker-based build examples
• Static linking and debug build options
• Example build scripts for automation

Prerequisites Documentation

• Clear system requirements for building go4vl
• Package installation commands for all major distros
• User permission setup instructions
• V4L2 utilities installation guidance

Files Changed

Added

• docs/BUILD.md - Comprehensive build documentation (519 lines)

Modified

• README.md - Added Building section with quick start commands
• examples/README.md - Updated with header installation instructions
• v4l2/cgo.go - Centralized CGo configuration with documentation
• v4l2/doc.go - Updated package documentation

Removed

• include/linux/videodev2.h - 2,770 lines (now uses system headers)
• include/linux/v4l2-controls.h - 2,486 lines (now uses system headers)
• include/linux/v4l2-common.h - 108 lines (now uses system headers)
• include/README.md - Removed vendored headers documentation
• multipass/ - Removed unsupported package

Full Changelog

Merged Pull Requests:

• #88: Issue #87 - Remove Linux headers, enhance build support
• #86: Issue #84 - Remove multipass directory

Commits: +620 additions, −5,586 deletions across 18 files

Compare: v0.2.0...v0.3.0

API Addition

Introduction of the new Deivce.GetFrames that creates a pool of buffers to avoid continuous allocation. The method uses type Frame which not only returns the captured buffer from the driver, but also include metadata for each frame.

New pooling API for frame capture:

• device/frame.go - Frame struct with metadata (timestamp, sequence, flags)
• device/frame_pool.go - Buffer pool implementation using sync.Pool
• device/frame_pool_test.go - Pool performance benchmarks
• device/frame_test.go - Frame API unit tests
• examples/capture_frames/ - Complete example demonstrating new API

Fixes

Fix race condition in Device.Stop() and deprecate Device.GetOutput() API
The Device.Stop() method had a critical race condition causing segmentation faults during streaming cleanup.
Stop() would un-map memory buffers while capture goroutines were still accessing them, leading to crashes in
benchmarks and tests.

Updates

Test infrastructure improvements:

• test/integration_test.go - Removed all time.Sleep() workarounds, removed problematic

Integration tests and benchmarks

• test/main_test.go - Added binary checks for ffmpeg/v4l2-ctl, improved module reload logic
• test/helpers.go - Changed exclusive_caps=1 to 0 for shared device access

See test/README.md for detail

Documentation updates:

• README.md - Added GetFrames() example and performance comparison
• ROADMAP.md - Marked frame metadata and performance optimization phases as complete
• TESTING_GUIDE.md - Added frame pool benchmarks section

API Deprecation

Marked GetOutput() as deprecated with clear migration guidance:
// Deprecated: Use GetFrames() instead. GetFrames() provides the same functionality
// with significantly better performance through buffer pooling, using 540x less memory
// (1 KB vs 614 KB per frame) and reducing GC pressure. This method will be removed
// in a future version.

What's Changed

• issue #82 - Implement API for safer/performant frame capture by @vladimirvivien in #83

Full Changelog: v0.1.0...v0.2.0

Project reboot

This release is a reboot of the project to introduce work that has been done in the last couple years with a formal tag. Thank you to the many contributors who have participated in the project so far.

What's Changed

• Add camera control values by @x2ocoder in #35
• Fix typo and grammar issues in comments by @alexandear in #39
• Refactor: get rid of reflect package by @alexandear in #38
• Cross compilation instruction by @vladimirvivien in #40
• device: Device.Start, init channel to reuse device by @mcuadros in #49
• Fix: correctly parse the item name of IntegerMenu by @vincent-vinf in #51
• Fix: Incorrect parsed FrameSize by @vincent-vinf in #53
• timeout and fdSet need to be set on each loop iteration as select() can modify them on linux by @ericbalsa in #64
• chore: Update doc by @vladimirvivien in #70
• issue-69 - chore: add testing support by @vladimirvivien in #71
• Enhanced README.md by @vladimirvivien in #73
• Add benchmark infrastructure for performance profiling by @vladimirvivien in #76
• Improve/fix device data capture pipeline by @vladimirvivien in #78
• #79 - Improve device testing and test documentation by @vladimirvivien in #81

New Contributors

• @x2ocoder made their first contribution in #35
• @alexandear made their first contribution in #39
• @mcuadros made their first contribution in #49
• @vincent-vinf made their first contribution in #51
• @ericbalsa made their first contribution in #64

Full Changelog: v0.0.5...v0.1.0

This release primarily focused on code changes to support updates to the webcam example, including:

• New updates to the webcam example GUI
• Streaming loop code update to copy frames to corruption by device during capture
• Update webcam to include face detection feature
• New examples including snapshot and simplecam
• Updates to the example documentation

This release introduced crucial bug fixes and other features including:

• Support for extended controls (i.e. querying, value get/set, enumerating)
• Capture sequence refactor to fix device-open bug
• Memory leak identified when running video capture programs for long period

Support for extended video controls

This release introduces support for V4L2 extended controls.

• Use existing control types, values for V4L2 extended control features
• Addition of low level Go functions to query, get, and set control values
• Ability to enumerate extended controls and their values.

The following example shows how to retrieve all available extended controls from the driver.

func main() {
	device, err := dev.Open("/dev/video0")
	if err != nil {
		log.Fatalf("failed to open device: %s", err)
	}
	defer device.Close()

	ctrls, err := v4l2.QueryAllExtControls(device.Fd())
	if err != nil {
		log.Fatalf("failed to get ext controls: %s", err)
	}
	if len(ctrls) == 0 {
		log.Println("Device does not have extended controls")
		os.Exit(0)
	}
	for _, ctrl := range ctrls {
		printControl(ctrl)
	}
       
       func printControl(ctrl v4l2.Contro) { ... }
}

See full example here

Capture sequence refactor

Since the inception of the project, it was known there were some bugs that needed to be revisited. We found out that some of the examples were failing when running on a Raspberry PI and capturing from a Raspberry Pi HD camera module. The code's use of the Go's standard library os.OpenFile was causing the device to report busy (when compared to similar programs in C).

So this called for an overhaul of the entire capture sequence which delivered the followings

• Fix device open failure by providing a simpler device operation that make system calls directly
• Successful test using the Raspberry Pi's HD camera module connected as a capture device
• Add more aggressive system call error handling for v4l2 calls including open, ioctl VIDIOC_QBUF, VIDIOC_DQBUFF, etc. This causes to run smoother, remove internal flickers that would happen sometimes

Memory leak fix

User @oyarzun reported a memory leak when running the webcam example (see issue #22). After a few hours of Go program profiling, it was found that the internal stream loop was leaking Go channel resources (by reinitialize the channel in the loop). After a simple fix (moving the channel initialization outside of the loop), the leak went away. After running the webcam program for over 25 hours on a RPi 3, it was observed that the memory consumption did not go over 1%. That was an awesome find.

VL2 user control support

The main theme for this release is the introduction of the Control API with initial support of the V4L2 user controls. This release adds the followings:

• Control types, values, and functions
• Addition of low level Go functions, in the v4l2 package, to query, get, and set control values
• Update to the Device type to add new methods to work with the control API

func main() {
        device, err := dev.Open(devName)
	if err != nil {
		log.Fatalf("failed to open device: %s", err)
	}
	defer device.Close()

        // set single device control value
        val := 12
        device.SetControlValue(v4l2.CtrlBrightness, v4l2.CtrlValue(val))

        // retrieve Control
        ctrl, _ := device.GetControl(ctrlID)

       fmt.Printf("Control id (%d) name: %s\t[min: %d; max: %d; step: %d; default: %d current_val: %d]\n",
		ctrl.ID, ctrl.Name, ctrl.Minimum, ctrl.Maximum, ctrl.Step, ctrl.Default, ctrl.Value)
}

For more detail, see the example

V4L2 header files added

Another improvement contributed by the community (thanks @ajcasagrande) is the inclusion of V4L2 header files as part of the project. This will provide consistent builds without relying on user's local header files (which can sometimes be outdated).

See the include directory for detail.

Local development

To ease local development for non-Linux environment, this release comes with a script that can launch a Canonical Ubuntu VM managed by Multipass. This provides a VM along with a fake V4L2 driver (V4L2Loopback) to help run and test the project without the need of an environment with a real video camera attached.

See the multipass directory for detail.

This release introduces major refactor that simplifies the way the API works. Unfortunately, these changes are not backward compatible with the previous version. Meaning, if you adopt this release, you will have to modify your existing code a bit.

The new device package

This release introduces a new device package to create and access device functionalities.

Creating a device with the device package

The device API creates a device without having to use the v4l2 directly.

import  "github.com/vladimirvivien/go4vl/device"

func main() {
    device, err := device.Open("/dev/video0")
    ...
}

function device.Open supports variable length arguments that can be used to specify the configuration of the device as it is being created:

func main() {
    device, err := device.Open("/dev/video0",
        device.WithIOType(v4l2.IOTypeMMAP),
        device.WithPixFormat(v4l2.PixFormat{PixelFormat: getFormatType(format), Width: uint32(width), Height: uint32(height)}),
        device.WithFPS(uint32(frameRate)),
    )
}

Starting a device

Once a device is created, it can be started with a context as shown below

func main() {
    device, err := device.Open("/dev/video0")
    ctx, stop := context.WithCancel(context.TODO())
    if err := device.Start(ctx); err != nil {
        log.Fatalf("failed to start stream: %s", err)
    }
}

Streaming device output

After a device has started, it's stream can be accessed as shown

func main() {
    device, err := device.Open("/dev/video0")
    ctx, stop := context.WithCancel(context.TODO())
    if err := device.Start(ctx); err != nil {
        log.Fatalf("failed to start stream: %s", err)
    }

    for frame := range device.GetOutput() {
    ....
    }
}

Other enhancements

This release introduces access to more device information via additional types.

• Ability to enumerate all attached v4l2 devices
• Enhanced device capability information (including capability description)
• Access to media info (including bus info, driver, card, model, etc)
• Driver version information
• Video input information (i.e. video input status)
• Enhanced pixel format description (including format sizes)
• Enhanced crop capability (with default crop bounds)
• Access to stream parameters (including both capture and output capabilities and capture modes)

See the device info example for detail.

This release comes after an internal rewrite to use cgo-generated types and values (instead of hand-crafted types) to deal with type alignment issues. Since the project targets the Linux OS, there is no need to be concerned with portability or cross-platform supportability.

The API is the same from the previous release. However, there are some changes that will cause code breakage (if you are using the previously tagged version) in how some types expose their values.

Features

• Capture and control video data from your Go programs
• Idiomatic Go API for device access and video capture
• Use cgo-generated types for correct data representation in Go
• Use familiar types such as channels to stream video data
• Exposes device enumeration and information
• Provides device capture control
• Access to video format information
• Streaming support using memory map (other methods coming later)

Examples

The ./examples directory contains additional examples including:

• device_info - queries and prints devince information
• webcam - uses the v4l2 package to create a simple webcam that streams images from an attached camera accessible via a web page.