cuframes-docs/site/docs/faq.md

title, sidebar_position

title	sidebar_position
FAQ	99

Frequently Asked Questions

Is cuframes production-ready?

Honest answer: early but tested in one real deployment. v0.4 has been running 24+ hours in a CCTV setup (4 IP cameras → publisher → 2 subscribers: NVR record + grid composer → TV) without intervention. That's not "battle-tested at scale" — that's "one engineer's home setup".

We recommend cuframes if:

• You're building your own video pipeline and understand the risks of adopting an OSS library at v0.x.
• Your team can read the source if something breaks (it's ~2k lines of C).
• You'd rather pin a known commit than chase semver promises.

We don't recommend cuframes if:

• You need vendor support contracts.
• You're shipping to customers who'd file an incident on the maintainer's email at 3 AM.
• You can't afford to write a workaround if a feature lands wrong.

How does cuframes compare to DeepStream?

	cuframes	NVIDIA DeepStream
Scope	Library (data plane only)	Full SDK + runtime
License	LGPL-2.1+	Proprietary EULA
Footprint	~140 KB .so	Multi-GB runtime
Lock-in	None — you own the pipeline	Pipeline = DeepStream plugins
Cross-process sharing	Native (this is the point)	Inside one process tree
Support	Best-effort GitHub	Paid enterprise
Learning curve	Hours	Weeks

cuframes is not trying to replace DeepStream. It solves one specific problem: "I have one CUDA decoder and multiple processes that want the decoded frames without re-decoding."

Why not GStreamer?

GStreamer has cudaupload / cudadownload elements but no zero-copy cross-process model — every consumer pulls its own pipeline. You can hack around with shmsink / shmsrc but you lose CUDA-residency (frames bounce through CPU memory). cuframes specifically avoids that round trip.

Why not DMA-BUF + V4L2?

That's the modern kernel-native path and works cross-vendor. We considered it. Reasons we went with CUDA VMM:

• Our target was NVIDIA-only anyway (existing CUDA decode pipeline).
• DMA-BUF integration with CUDA requires EGLStream interop boilerplate — more code than VMM + POSIX FD path.
• Driver support varies by GPU age; CUDA VMM is stable since CUDA 10.2.

If your project is cross-vendor, DMA-BUF is the right choice and cuframes is not for you.

Can I use this on Windows?

No. Implementation uses POSIX shared memory (shm_open), Unix sockets, and SCM_RIGHTS file descriptor passing. Porting to Windows would require:

• Windows shared memory primitives (CreateFileMapping).
• Different FD-sharing mechanism (DuplicateHandle via named pipe).
• CUDA VMM WIN32_HANDLE instead of POSIX_FILE_DESCRIPTOR.

Not on the roadmap. PRs welcome.

Can publisher and consumer be on different machines?

No. POSIX file descriptors don't traverse a network. For cross-host video sharing you need a different transport: RTSP, SRT, NDI, or roll your own with shared-memory NIC RDMA. cuframes is strictly same-host.

What if the publisher dies while consumer is reading?

Consumer's next cuframes_subscriber_next() returns CUFRAMES_ERR_DISCONNECTED. Consumer should:

1. Call cuframes_subscriber_destroy().
2. Wait (e.g., 1–2 sec backoff).
3. Try cuframes_subscriber_create() again with the same key.

The FFmpeg demuxer (cuframes://) does this automatically — every 2 seconds re-subscribes and returns EAGAIN to the avformat layer instead of EOF. See libavformat/cuframesdec.c if you're reimplementing this for another framework.

Can I have multiple publishers on the same key?

No. Each key (/run/cuframes/<key>.sock + /dev/shm/cuframes-<key>) maps to exactly one publisher. The publisher detects "already running" on create() via shm header + PID liveness check and fails with CUFRAMES_ERR_ALREADY_EXISTS.

For load balancing or HA scenarios you'd need to layer your own naming scheme on top (e.g., cam1-primary, cam1-backup, and consumer logic to pick which to subscribe to).

How many subscribers can a publisher handle?

CUFRAMES_MAX_SUBSCRIBERS = 32 (bitmap-limited). Bumping this requires a protocol version change because the bitmap is in the SHM header.

In practice we run 2–3 subscribers per camera (NVR + AI inference + grid composer). 32 is more than enough.

License questions

LGPL-2.1+. You can use cuframes in commercial closed-source products as long as:

• Dynamic linking (the .so is replaceable by the end user).
• Any modifications to libcuframes itself are published under LGPL.

Static linking pulls the whole project under LGPL — usually not what you want.

If LGPL is incompatible with your use case (e.g., embedded with no replaceable library), reach out before forking.

Where do I report bugs / contribute?

• Source repo: https://git.goldix.org/gx/cuframes
• Issues: same repo /issues
• Contributing guide: CONTRIBUTING.md in the source tree

This documentation site lives separately at https://git.goldix.org/gx/cuframes-docs — typo fixes and content PRs land via the same Gitea.