---
title: FAQ
sidebar_position: 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.