Skip to content

fix: Linux aarch64 build + native SSP connector (no libssp dependency)#89

Open
damienheiser wants to merge 6 commits into
summershrimp:masterfrom
damienheiser:fix/linux-aarch64-build-compat
Open

fix: Linux aarch64 build + native SSP connector (no libssp dependency)#89
damienheiser wants to merge 6 commits into
summershrimp:masterfrom
damienheiser:fix/linux-aarch64-build-compat

Conversation

@damienheiser
Copy link
Copy Markdown

@damienheiser damienheiser commented Mar 8, 2026 •
edited
Loading

Summary

Adds Linux aarch64 build support and a native SSP client — a clean-room, open-source
replacement for the closed-source libssp.so that the upstream connector depends on.

The SSP wire protocol was reverse-engineered from live Z CAM E2-M4 captures,
libssp-py, and symbol analysis.

Changes

  • Build fixes — aarch64/modern GCC compatibility (packed struct alignment, Qt6 includes)
  • Native SSP connector (ssp_native.c) — drop-in replacement, auto-selected on Linux aarch64
  • Wire format fixes — correct metadata (9-byte header + 17 BE32 fields), video (17-byte header), audio (9-byte header) packet parsing verified against live captures
  • Stop() deadlock fix — kill connector process before thread join
  • Library refactor — split into embeddable ssp.c library + ssp_connector_main.c CLI
  • Cross-platform sockets — ssp_platform.h abstracts POSIX/Windows differences
  • 38 unit tests — byte helpers, packet parsing, metadata layout, API surface
  • Protocol documentation — complete wire spec in SSP_PROTOCOL.md
  • README rewrite — build instructions, architecture, camera compatibility

Architecture

ssp.c                  → Embeddable library (ssp_client_t API, callback-driven)
ssp_connector_main.c   → CLI bridge (library callbacks → IPC → OBS plugin)
ssp_platform.h         → POSIX / Windows socket abstraction
ssp.h                  → Public C API header
test_ssp.c             → Unit tests (38 tests, all passing)
SSP_PROTOCOL.md        → Wire protocol specification

Commits

  1. 470d16a — Build fixes for aarch64 and modern toolchains
  2. f4c5769 — Native SSP connector implementation
  3. 17e349a — Wire format parsing fixes from live camera captures
  4. da71ec8 — Stop() deadlock fix
  5. 51ef16f — Protocol documentation and public API header
  6. 89fb27c — Library refactor with tests and README

Test Plan

  • Builds on Linux aarch64 (Asahi Fedora 42, GCC 15.2.1)
  • 38/38 unit tests pass (cmake -DSSP_BUILD_TESTS=ON)
  • Streams live H.264/AAC from Z CAM E2-M4 into OBS
  • Correct metadata parsing (1920x1080, 30000/1001 fps, 48kHz stereo AAC)
  • Heartbeat keep-alive maintains connection
  • Clean shutdown (no deadlock on Stop())
  • Windows build (cross-platform abstractions in place, not yet tested)
  • macOS build (should work with USE_NATIVE_SSP=ON)
  • H.265 stream testing (encoder ID 265 supported in code)

hedon added 2 commits March 8, 2026 12:30
fix: Linux build compatibility for aarch64 and modern toolchains
470d16a 
- Fix FFmpeg component names (AVCODEC/AVUTIL → avcodec/avutil) to match
  FindFFmpeg.cmake case-sensitive comparison
- Fix ENABLE_FRONTEND_API/ENABLE_QT to use option() instead of set() so
  CMake preset cache variables are respected
- Fix Qt6 alias target error with Qt 6.10+ by checking ALIASED_TARGET
  before setting properties
- Add Linux libssp linking case in ssp_connector/CMakeLists.txt
- Add Linux install targets for ssp-connector and libssp
- Skip ssp-connector build on aarch64 Linux (no vendor binary available)
- Fix int64_t vs long long type mismatch on aarch64 in obs-ssp-source.cpp
feat: native SSP connector — drop-in replacement for closed-source li…
f4c5769 
…bssp

Add ssp_native.c, a clean-room SSP protocol implementation that replaces
the closed-source libssp dependency entirely. Protocol reverse-engineered
from libssp-py and symbol analysis of the original library.

Features:
- TCP-based SSP client with SHA1 challenge-response auth
- Stream start/stop, metadata, video and audio frame parsing
- Heartbeat keepalive via poll()-based event loop
- Compatible IPC output format for the obs-ssp plugin
- Zero proprietary dependencies (only needs OpenSSL for SHA1)
- Builds natively on any architecture (aarch64, x86_64, etc.)

Build system changes:
- New USE_NATIVE_SSP cmake option (auto-enabled on Linux aarch64)
- Falls back to original libssp-based connector when available
- Simplified install targets for all platforms

Also adds scripts/zcam-rtsp.sh for low-latency GStreamer RTSP fallback.
@damienheiser damienheiser changed the title fix: Linux build compatibility for aarch64 and modern toolchains fix: Linux aarch64 build + native SSP connector (no libssp dependency) Mar 8, 2026
hedon added 4 commits March 8, 2026 13:11
fix(ssp_native): correct SSP wire format parsing from live camera cap…
17e349a 
…ture

Metadata, video, and audio packet formats were reverse-engineered from
a live Z CAM wire capture. The original offsets were guesswork and
produced garbage values (e.g. video=0x1114112).

Metadata (0x6E): 9-byte header (type + 4 version + 4 field_count),
then 17 × BE32 fields in order: video.timescale, video.unit, width,
height, gop, reserved, audio.sample_rate, audio.unit, audio.timescale,
audio.sample_size, channel, bitrate, pts_is_wall_clock, video.encoder,
audio.encoder, timecode, tc_drop_frame.

Video (0x6F): [0]=type [1..8]=pts(BE64) [9..12]=frame_type(BE32)
[13..16]=frm_no(BE32) [17..]=NAL data.  No ntp_timestamp on wire.

Audio (0x70): [0]=type [1..8]=pts(BE64) [9..]=ADTS data.
No ntp_timestamp on wire.

Verified: video=1920x1080 ts=30000/1001 gop=30 enc=H264(96),
audio=48000hz ch=2 enc=AAC(37) br=128000.
fix(ssp-client): kill connector process before join to prevent deadlock
da71ec8 
Stop() called worker.join() before destroying the pipe, but the worker
thread was blocked in fread() waiting for connector output. Since
os_process_pipe_destroy (which kills the connector) was only called
AFTER join, the sequence deadlocked — OBS froze on source stop.

Fix: send SIGTERM to the connector process before joining the worker.
The connector's signal handler sets g_running=false, recv() returns
EINTR, the connector exits, stdout closes, fread returns 0, the worker
loop breaks, and join() completes immediately.

Added os_process_pipe_signal() to both POSIX (kill()) and Windows
(TerminateProcess()) pipe implementations.
docs: SSP wire protocol specification and public library API
51ef16f 
Add clean-room SSP protocol documentation reverse-engineered from live
Z CAM E2-M4 wire captures. Includes complete packet layouts for all
message types, authentication flow, and metadata field map.

Add public C API header (ssp/ssp.h) defining callback-based client
interface for embedding the SSP client in other applications.

Update copyright to Hedonistic, LLC. Include ssp_connector in repo
via .gitignore allowlist.
refactor: split ssp_native into library + CLI with tests
89fb27c 
Extract protocol logic from monolithic ssp_native.c into a clean
embeddable library (ssp.c) implementing the public ssp_client_t API.

- ssp.c: callback-driven library, no globals, cross-platform sockets
- ssp_connector_main.c: thin CLI bridging library callbacks to IPC
- ssp_platform.h: POSIX/Windows socket abstraction layer
- test_ssp.c: 38 unit tests covering byte helpers, packet parsing,
  metadata field layout, and library API
- CMakeLists.txt: object library + test target (SSP_BUILD_TESTS)
- README.md: complete rewrite with build instructions, architecture
  overview, protocol summary, and camera compatibility table
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@damienheiser