Evolve or Replace `belacoder` for Modular, H.265‑Capable, Multi‑Input Streaming

[andrescera]

Note: This issue was cloned from CERALIVE/belaUI-ts#8

---

Proposal: Evolve or Replace belacoder for Modular, H.265‑Capable, Multi‑Input Streaming

📌 Background

Currently, belacoder relies on hardcoded shell pipelines under pipelines/<soc>/ (e.g., rk3588) to manage SoC-specific video ingestion and streaming. While this supports minimal integration per device, it lacks:

• Runtime device/input detection
• Flexibility to switch between USB, HDMI, or network inputs
• Easy extensibility for preview or advanced streaming (SRTLA, RTMP out, etc.)
• Config-based customization (e.g., no JSON/TOML for stream params)

🎯 Objectives

1. Support multiple SoCs via pipeline modules or detection.
2. Auto-discover inputs/resolutions at runtime (USB/UVC, HDMI, RTMP/SRT).
3. Use H.265 encoding via mpph265enc or fallback to software.
4. Stream over SRT/SRTLA, RTMP, with preview via HTTP/WebRTC.
5. Clean extensibility, with JSON config or templated detection logic.

---

🧪 Options Analysis

Option	Pros	Cons	Short‑Term Fit	Long‑Term Viability
A. Grow belacoder	Leverage existing scripts; no code changes	Static; no auto‑detect or preview	⚠️	⚠️ Minimal
B. Patch belacoder (C)	Quick H.265/SRTLA support; minimal edits	Limited extensibility	✅	⚠️ Moderate
C. Python + GStreamer	Dynamic pipelines; auto‑detect; built‑in Web/UI	Higher RAM; interpreter overhead	⚠️	✅ Flexible
D. Rust + gstreamer‑rs	Safe, performant; dynamic graphs	Complex toolchain; slower protos	⚠️	✅ Robust
E. C++ + GStreamer C API	Zero interpreter overhead; fine‑grained control	Boilerplate detection code	⚠️	✅ Optimal

---

✅ Compatibility & Performance Matrix

Feature / Approach	A. Grow	B. Patch	C. Python	D. Rust	E. C++
H.265 (mpph265enc)	✅	✅	✅	✅	✅
USB / UVC (libuvch264)	✅ (static)	✅	✅ auto	✅	✅
HDMI (v4l2src)	✅ (static)	✅	✅ auto	✅	✅
SRT Input	✅	✅	✅	✅	✅
RTMP Input	✅	✅	✅	✅	✅
SRTLA Output	✅	✅	✅	✅	✅
RTMP Output	❌	⚠️ patch	✅	✅	✅
Preview (web/local)	❌	⚠️ patch	✅	✅	✅
Resolution detection	❌	⚠️	✅	✅	✅
RAM Usage (est.)	✅ Low	✅ Low	⚠️ 50–100MB	✅ Low	✅ Low
Latency (est.)	✅ Low	✅ Low	⚠️ ~50ms	✅ Low	✅ Low
SoC Portability	⚠️	✅	✅ via templates	✅	✅
Long-Term Evolution	⚠️ Minimal	⚠️ Moderate	✅ Strong	✅ Strong	✅ Strong

Note: RAM and latency values are based on practical experience with RK3588 + GStreamer. Python options use more RAM due to interpreter runtime. Latency numbers are relative to encoding and network overhead, assuming live pipelines.

---

🧩 Proposal

Let’s choose one of the following strategies:

• 🔧 Patch belacoder: Add preview, config support, RTMP out via minimal C additions
• 🛠️ Start fresh with modular GStreamer app in Rust, Python, or C++
• ♻️ Hybrid: Extend belacoder for legacy, while building belacoder2 for new devices

---

✳️ Discussion Points

• Do we want per-device detection? (e.g., USB camera vs HDMI source)
• Should preview be built-in or via separate web-ui tool?
• Should SoC-specific scripts stay in place or be replaced with detection logic?

[andrescera]

Also take into count CERALIVE/ceracoder#1 for a npm package for managing this

[andrescera]

Progress Update: TypeScript Bindings and CeraUI Integration

Significant progress on this issue with the new ceracoder TypeScript bindings:

ceracoder changes:

• PR: feat: add TypeScript bindings package (@ceralive/ceracoder) ceracoder#10
• New @ceralive/ceracoder TypeScript package with:
  • PipelineBuilder for dynamic GStreamer pipeline generation
  • Support for all hardware types (Jetson, RK3588, N100, Generic)
  • Multiple input sources (HDMI, USB/Cam Link, UVC H264, MJPEG, SRT, RTMP)
  • H.265 encoding support where hardware allows

CeraUI integration:

• PR: refactor: integrate ceracoder bindings with hardware-based pipeline UI #71
• Frontend now displays pipelines organized by hardware type
• DevTools Mock Hardware Switcher for testing different hardware profiles
• i18n translations for hardware types and video sources
• Removed legacy complex pipeline parsing

What this addresses from the proposal:

• Support multiple SoCs via PipelineBuilder with hardware-specific builders
• Config-based customization via Zod schemas and INI config generation
• Clean extensibility - adding new hardware types is straightforward
• Use H.265 encoding - supported on Jetson, RK3588 via hardware encoders

Still pending:

• Auto-discover inputs/resolutions at runtime (device probing)
• Preview via HTTP/WebRTC (separate feature)
• RTMP output support

[andrescera]

Delivered: cerastream as sole streaming engine

Objective: Evolve/replace belacoder with a unified, production-ready streaming engine.

Status: ✅ DELIVERED via cerastream (v2026.6.1+)

Evidence

H.265 on all 4 SoC profiles:

• Generic: cerastream/crates/cerastream-hal/src/profiles/generic.rs → h265_encoder()
• Jetson: cerastream/crates/cerastream-hal/src/profiles/jetson.rs → h265_encoder()
• RK3588: cerastream/crates/cerastream-hal/src/profiles/rk3588.rs → h265_encoder()
• N100: cerastream/crates/cerastream-hal/src/profiles/n100.rs → h265_encoder()

Multi-input support:

• cerastream/crates/cerastream-core/src/sources/spec.rs → InputKind enum (UVC, RTMP, SRT, etc.)

Runtime device auto-discovery:

• cerastream/crates/cerastream-core/src/sources/registry.rs → device enumeration and selection

SRTLA integration:

• cerastream feeds srtla-send-rs for bonded streaming (see ARCHITECTURE.md §2)

Tracked follow-ups

• Decklink capture + hardware-encoder validation: Gated per cerastream/docs/notes/hardware-validation.md (required-but-unrun profiles)
• WebRTC preview: Tracked under Add real-time device preview and audio level monitoring to encoder selectors #72
• Auto-discovery, RTMP-out H.264: Addressed in cerastream core

Retirement

ceracoder fully retired 2026-06-11 after generic boot-parity profile passed. cerastream is the sole engine.