feat(vdo): Add safe Rust bindings for VDO API by vsem-azamat · Pull Request #223 · AxisCommunications/acap-rs

vsem-azamat · 2025-12-28T15:09:29Z

Safe Rust bindings for VDO (Video Capture) API

Safe wrappers over vdo-sys with builder pattern for stream creation, iterator-based frame capture, and automatic resource cleanup.

Tested on device: YUV, JPEG, H.264, H.265 formats work correctly.

Describe your changes

This PR adds a new vdo crate providing safe Rust bindings for the VDO API, enabling video capture from Axis cameras.

Based on the work from PR #153 by @JsGjKJzi — completed the implementation, added comprehensive tests, and updated the example application.

Note: @JsGjKJzi hasn't responded since January 2024.

Key features:

StreamBuilder with builder pattern for configuring video streams
Stream, RunningStream, StreamIterator for lifecycle management
StreamBuffer and Frame for zero-copy frame access
Automatic resource cleanup via Drop implementations
Comprehensive error handling with VdoError including error code names
Platform compatibility documentation (Artpec-6/7/8/9, Ambarella CV)

Changes:

New crates/vdo/ crate with safe bindings
Updated apps/vdo_encode_client/ to use the new vdo crate
Unit tests (no device required) + device tests (gated by device-tests feature)

Issue ticket number and link

Continues Add VDO #153
Enables Add Larod #120 (Larod ML API depends on VDO)

Checklist before requesting a review

I have performed a self-review of my own code
I have verified that the code builds perfectly fine on my local system
I have added tests that prove my fix is effective or that my feature works
I have commented my code, particularly in hard-to-understand areas
I have verified that my code follows the style already available in the repository
I have made corresponding changes to the documentation

Safe wrappers over vdo-sys with builder pattern for stream creation, iterator-based frame capture, and automatic resource cleanup. Tested on device: YUV, JPEG, H.264, H.265 formats work correctly.

Copilot

Pull request overview

This PR adds safe Rust bindings for the VDO (Video Capture) API, enabling video capture from Axis cameras. The implementation provides a builder pattern for stream configuration, iterator-based frame capture, and automatic resource cleanup through RAII principles.

Key changes:

New vdo crate with safe abstractions over vdo-sys FFI bindings
Comprehensive error handling with detailed error code mapping
Builder pattern for ergonomic stream configuration
Updated vdo_encode_client application demonstrating multiple video formats

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
crates/vdo/src/lib.rs	Core library implementation with safe wrappers for VDO API, including Stream, StreamBuffer, Frame types, and comprehensive tests
crates/vdo/examples/basic.rs	Simple example demonstrating video stream capture with YUV format
crates/vdo/Cargo.toml	Package configuration for the new vdo crate with device-tests feature flag
apps/vdo_encode_client/src/main.rs	Updated example application testing multiple video formats (YUV, JPEG, H.264, H.265)
apps/vdo_encode_client/Cargo.toml	Updated dependency from vdo-sys to the new vdo crate
Cargo.toml	Added vdo workspace member
Cargo.lock	Updated lock file with vdo crate dependencies

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

vsem-azamat · 2025-12-28T15:26:38Z

I'll wait for feedback from the maintainers before addressing these suggestions, as some may be more relevant than others for this codebase.

apljungquist · 2025-12-29T09:07:47Z

I won't have time to look at the code before new year, but I would like to say already now that I'm happy you are interested in carrying on the work that Jonathan started 🙂

apljungquist

I skimmed the PR and I think it looks pretty good. I'll try to do a more thorough read in the before next weekend focusing on safety and I'll try to respond to comments within 24h.

apljungquist

Some API design related questions.

API design is difficult and typically subjective. I don't want it to stall this PR, so consider this inspiration. (that's not to say that the previous review was not subjective or disputable, only that this is even more so)

apljungquist · 2026-01-09T17:19:09Z

I created this to help with my understanding of VDO, posting it here in case you find it usefule: https://github.com/apljungquist/acap-rs/blob/f778576222874210e51f0c46ab4d6ffbdd877572/crates/vdo-sys/README.md

apljungquist

I have focused this review on the Map type, which looks good. Once we have decided if/how to change it I will continue reviewing other parts.

I do this to not overwhelm you with comments and to not overwhelm myself with different discussions to keep track of and large diffs that need to be reviewed with every now commit.

Address all review comments. Fix GObject leak in Stream::drop. - Consume-by-value ownership: start(self), stop(self), unref(self) - Replace Iterator with next_buffer() -> Result - Merge Frame into StreamBuffer (VdoBuffer = VdoFrame) - Extract Map to separate module, keys as &CStr - Add Resolution enum, remove buffer_strategy, rename to custom_timestamp_us - Replace as_mut_slice with data_copy(), file_descriptor() returns Result Tested: cargo clippy clean, 33/33 tests pass on Artpec-9 device.

vsem-azamat · 2026-02-10T20:51:10Z

@apljungquist @guoxe
I've tried to fix all things. Pls, review

apljungquist · 2026-02-11T22:27:04Z

Will try to get around to this tomorrow

Address all review comments. Fix GObject leak in Stream::drop. - Consume-by-value ownership: start(self), stop(self), unref(self) - Replace Iterator with next_buffer() -> Result - Merge Frame into StreamBuffer (VdoBuffer = VdoFrame) - Extract Map to separate module, keys as &CStr - Add Resolution enum, remove buffer_strategy, rename to custom_timestamp_us - Replace as_mut_slice with data_copy(), file_descriptor() returns Result Tested: cargo clippy clean, 33/33 tests pass on Artpec-9 device.

apljungquist · 2026-02-12T23:18:29Z

@vsem-azamat nice progress!

Please refrain from force pushing in the future as it makes it difficult to review the changes and keep track of comments. I took the liberty of cherry-picking your fix onto the branch before it was force pushed and force pushing that, so now the git history looks as it should.

A few of my comments seem to have gone unaddressed. You don't have to always to things the way I think is the best, but I would appreciate if you at least acknowledge on each comment that you have read it and state what, if anything, you will do to address it 🙂

I haven't seen the results of the CI yet, but if we get more revisions in on this I will make sure to start it as soon as I can instead of waiting until I have time to do human review like this time around.

apljungquist · 2026-02-13T18:42:22Z

It looks like something changed with github actions and it now hangs after starting the dev container: [2026-02-13T18:09:55.811Z] Container started 😮‍💨

I will try to look into this in the next week or so. In the meanwhile I encourage you to run the same check locally so that we have a good PR ready to go when CI gets fixed. The check that compares checksums can be a bit unreliable and is easy to fix, so if that is the only one that is failing we should be all right.

apljungquist

I forgot to submit this review, sorry. Among the new comments I only feel strongly about the glob import, but as I said, please respond to all new and old comments.

…ct-test Replace `use vdo_sys::*` with explicit type imports and `vdo_sys::`-qualified function/constant calls at call sites. This addresses the PR review feedback about avoiding glob imports. Also adds the missing VDO_ERROR_NO_VIDEO error code and adopts expect-test for display/formatting tests.

- Clamp size to capacity in data_copy to prevent out-of-bounds reads - Replace debug_assert with assert in unsafe constructors (from_ptr, from_raw) - Document BorrowedFd lifetime constraints on file_descriptor() - Fix double vdo_stream_stop by delegating to Drop - Add Error::InvalidFd instead of overloading NullPointer for bad fds - Return Option<usize> from header_size() for negative (no header) values - Fix from_gerror safety comment to match actual code order - Add Debug for Map and CStringPtr, Deref<Target=CStr> for CStringPtr - Use explicit ptr::null::<c_char>(), comment as_ptr GLib convention

socket-security · 2026-02-21T13:09:44Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/expect-test@1.5.1

View full report

apljungquist

Some nice improvements in this iteration. But there are still old comments that remain unaddressed. You may want to also take at least a quick look at Gustaf's comments as he he the person who will ultimately merge your PR if approved 😉

apljungquist · 2026-03-07T14:32:54Z

I took the liberty of fixing a couple of outstanding issues, I hope that's ok.

vsem-azamat · 2026-03-07T15:21:32Z

I took the liberty of fixing a couple of outstanding issues, I hope that's ok.

Sure. Thanks)

vsem-azamat · 2026-03-08T12:41:56Z

@guoxe
Hi!
please take a look when you have time 😄
I addressed ur comments

…fety Remove async load/run APIs (overengineering for typical load-once + sync inference workflow). Fix Send soundness for Tensors and JobRequest by storing raw connection pointer instead of &Connection, avoiding the Connection: Sync requirement. Apply PR AxisCommunications#223 review feedback: rename Map::new to try_new, add SAFETY comments on unsafe blocks, fix error handling to use from_utf8_lossy. Harden Drop impls to free larodError even on success, fix panic safety in devices()/models() array handling, add #[must_use] to OwnedTensorPtrs, fix PhantomData invariance in JobRequest.

guoxe

I have some questions relating to some of the functions added.
Overall I think it looks good!

vsem-azamat · 2026-06-15T12:06:00Z

Hi!
@guoxe
I've brought some updates 😄

guoxe

Nice work!

Sorry it took a while for me to get around to reviewing, unless there is something else you want to address I am happy with merging this PR as is.

vsem-azamat · 2026-07-03T11:02:48Z

@guoxe
I've fixed checksum. Please, approve it again

vsem-azamat · 2026-07-03T11:27:25Z

@guoxe I've fixed checksum. Please, approve it again

@apljungquist @guoxe

Thanks you so much for for helping and reviewing this PR. It was tough for me.

I'd like to merge this PR and in anything appears I'll open new FollowUp MR.

Thanks)

apljungquist · 2026-07-03T11:46:21Z

I'm happy you were up for the challenge and that it hasn't discouraged you :)

…fety Remove async load/run APIs (overengineering for typical load-once + sync inference workflow). Fix Send soundness for Tensors and JobRequest by storing raw connection pointer instead of &Connection, avoiding the Connection: Sync requirement. Apply PR AxisCommunications#223 review feedback: rename Map::new to try_new, add SAFETY comments on unsafe blocks, fix error handling to use from_utf8_lossy. Harden Drop impls to free larodError even on success, fix panic safety in devices()/models() array handling, add #[must_use] to OwnedTensorPtrs, fix PhantomData invariance in JobRequest.

feat(vdo): Add safe Rust bindings for VDO API

2326701

Safe wrappers over vdo-sys with builder pattern for stream creation, iterator-based frame capture, and automatic resource cleanup. Tested on device: YUV, JPEG, H.264, H.265 formats work correctly.

Copilot AI review requested due to automatic review settings December 28, 2025 15:09

vsem-azamat requested a review from a team as a code owner December 28, 2025 15:09

Copilot started reviewing on behalf of vsem-azamat December 28, 2025 15:09 View session

Copilot AI reviewed Dec 28, 2025

View reviewed changes

apljungquist reviewed Jan 4, 2026

View reviewed changes

guoxe requested changes Jan 7, 2026

View reviewed changes

apljungquist reviewed Jan 9, 2026

View reviewed changes

Comment thread crates/vdo/src/lib.rs Outdated

Comment thread crates/vdo/src/lib.rs Outdated

Comment thread crates/vdo/src/lib.rs Outdated

Comment thread crates/vdo/src/lib.rs Outdated

vsem-azamat force-pushed the feature/vdo-completion branch from 2326701 to 70e2962 Compare February 10, 2026 20:47

vsem-azamat requested review from apljungquist and guoxe February 10, 2026 20:51

apljungquist and others added 2 commits February 12, 2026 23:21

Merge remote-tracking branch 'upstream/main' into HEAD

864abce

apljungquist force-pushed the feature/vdo-completion branch from 70e2962 to 2326701 Compare February 12, 2026 22:22

apljungquist reviewed Feb 17, 2026

View reviewed changes

Comment thread crates/vdo/src/lib.rs Outdated

Comment thread crates/vdo/src/lib.rs

vsem-azamat added 3 commits February 21, 2026 13:13

style(vdo): Apply rustfmt

87a708d

vsem-azamat requested a review from apljungquist February 21, 2026 13:16

apljungquist reviewed Feb 22, 2026

View reviewed changes

apljungquist previously approved these changes Mar 7, 2026

View reviewed changes

fix make check_docs

52edcd3

apljungquist dismissed their stale review via 52edcd3 March 7, 2026 17:13

don't attempt to run vdo tests on host

5f9a469

apljungquist previously approved these changes Mar 8, 2026

View reviewed changes

vsem-azamat mentioned this pull request Mar 11, 2026

feat(larod): Add safe Rust bindings #230

Open

12 tasks

guoxe reviewed Mar 17, 2026

View reviewed changes

vsem-azamat added 3 commits June 9, 2026 21:15

Merge branch 'main' into feature/vdo-completion

73cf845

address review comments

7489918

update checksums

b2ccc73

vsem-azamat dismissed apljungquist’s stale review via b2ccc73 June 9, 2026 19:18

vsem-azamat added 3 commits June 15, 2026 11:07

document fd lifetime assumption

ef3ca6a

remove file_descriptor until there is a consumer

17f0d26

update checksums

f4c9497

guoxe previously approved these changes Jul 2, 2026

View reviewed changes

Comment thread crates/vdo/src/lib.rs Outdated

update checksums

db02c34

vsem-azamat dismissed guoxe’s stale review via db02c34 July 2, 2026 18:47

vsem-azamat requested a review from guoxe July 2, 2026 18:50

guoxe approved these changes Jul 3, 2026

View reviewed changes

guoxe merged commit 8e58acb into AxisCommunications:main Jul 3, 2026
8 checks passed

vsem-azamat mentioned this pull request Sep 3, 2026

docs: Update status of vdo and larod in README #261

Merged

Uh oh!

Conversation

vsem-azamat commented Dec 28, 2025

Safe Rust bindings for VDO (Video Capture) API

Describe your changes

Issue ticket number and link

Checklist before requesting a review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vsem-azamat commented Dec 28, 2025

Uh oh!

apljungquist commented Dec 29, 2025

Uh oh!

apljungquist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apljungquist left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apljungquist commented Jan 9, 2026

Uh oh!

apljungquist left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vsem-azamat commented Feb 10, 2026

Uh oh!

apljungquist commented Feb 11, 2026

Uh oh!

apljungquist commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apljungquist commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

apljungquist left a comment •

edited

Loading

apljungquist commented Feb 12, 2026 •

edited

Loading

apljungquist commented Feb 13, 2026 •

edited

Loading

apljungquist left a comment •

edited

Loading

socket-security Bot commented Feb 21, 2026 •

edited

Loading