본문으로 건너뛰기
sstreamzet/docs
Linux SDK preview콘솔 열기
개발자 문서 / Linux SDK
API와 연동 가이드 · 수정 2026-09-22

Linux 앱에 연동하기

C ABI·Go SDK의 빌드, 설정, 메모리 소유권과 종료 처리를 실행 가능한 예제로 확인합니다.

1. 대상과 준비물

현재 Linux SDK는 통합 검토용 preview입니다. Ubuntu 24.04의 일반 사용자 실행을 기준으로 하며 xSpan의 구형 ARMv5/Linux 2.6 제품 SDK와 별개입니다. arm64/amd64는 각각 대상 ABI에서 빌드해야 합니다. macOS에서 만든 .so를 Linux에 복사해 사용할 수 없습니다.

Go 1.26.x, C 컴파일러, make, Bash, CA 인증서 저장소가 필요합니다. 대상 시스템의 아키텍처와 glibc 버전을 먼저 기록하세요. TLS 검증을 끄지 말고 배포판 ca-certificates와 필요한 사내 CA를 올바르게 설치합니다.

sh
uname -m
getconf GNU_LIBC_VERSION
go version
sudo apt-get update
sudo apt-get install --no-install-recommends build-essential ca-certificates bash
# Run application builds and support as your normal user:
cd source
make sdk

2. 설정과 기기 상태 디렉터리

json
{
  "config": {
    "supabase_url": "https://YOUR_BACKEND",
    "publishable_key": "YOUR_PUBLIC_ANON_KEY",
    "signal_url": "wss://YOUR_SIGNALING",
    "device_name": "SDK integration test",
    "mode": "terminal"
  },
  "state_dir": "/home/operator/.local/state/streamzet-sdk-test",
  "fleet": false
}

YOUR_*를 제공받은 공개 연결 값으로 바꾸고 state_dir를 현재 사용자 전용의 절대 경로로 바꿉니다. JSON 안의 ~나 $HOME은 확장되지 않습니다. 디렉터리는 0700, identity.json은 0600이며 다른 SDK/에이전트와 공유하지 않습니다. 복제 이미지에 identity.json을 넣지 마세요.

sh
chmod 600 config.json
mkdir -p /home/operator/.local/state/streamzet-sdk-test
chmod 700 /home/operator/.local/state/streamzet-sdk-test
./dist/sdk/native/embedded-example config.json
# Press Enter for a graceful stop.

3. C/C++에서 사용하기

생성된 libstreamzet.h와 같은 빌드의 libstreamzet.so를 한 쌍으로 사용합니다. 아래 명령은 SDK source 디렉터리 기준이며 실행파일 옆의 라이브러리를 찾는 rpath를 설정합니다. Windows DLL이나 xSpan 정적 라이브러리와 호환되지 않습니다.

sh
cc -Wall -Wextra -Werror -I dist/sdk/native examples/embedded.c \
  -L dist/sdk/native -lstreamzet -Wl,-rpath,'$ORIGIN' \
  -o dist/sdk/native/embedded-example
ldd dist/sdk/native/embedded-example
./dist/sdk/native/embedded-example config.json
c
#include "libstreamzet.h"
#include <stdio.h>

/* Call from a worker thread; config_json is NUL-terminated UTF-8. */
int run_support(char *config_json) {
    int rc = StreamzetStart(config_json);
    char *status = StreamzetStatus();
    puts(status);
    StreamzetFree(status); /* Exactly once, including error paths. */
    if (rc != 0) return rc;
    /* The real host continues its work here until support should end. */
    getchar();
    StreamzetStop(); /* Waits for peers/background work; not a UI callback. */
    return 0;
}

Start 반환값은 0=시작됨, 1=잘못된 설정/시작 실패, 2=이미 시작됨입니다. JSON 입력은 호출 중 복사하며 호출자 소유입니다. Status 문자열은 호출자에게 소유권을 넘기므로 StreamzetFree로 한 번 해제합니다. Stop은 동기적·반복 호출 가능하며 프로세스 수명 중 dlclose하지 않습니다.

4. Go 호스트에 연결

현재 공개 버전 태그를 가정한 go get 명령은 제공하지 않습니다. 전달 ZIP의 source를 vendor/streamzet-linux에 두고 호스트 모듈에 로컬 replace를 추가합니다. internal 패키지를 직접 import하지 않습니다.

sh
# Run inside your existing host Go module:
go mod edit -require=github.com/plitsoft/streamzet/[email protected]
go mod edit -replace=github.com/plitsoft/streamzet/linux-agent=./vendor/streamzet-linux
# After adding the SDK import to your host:
go mod tidy
# Or run the complete example shipped in the source package:
cd vendor/streamzet-linux
go run ./examples/go /absolute/path/config.json
go
import (
    "context"
    "github.com/plitsoft/streamzet/linux-agent/sdk"
)

func startSupport(ctx context.Context, options sdk.Options) (*sdk.Support, error) {
    support, err := sdk.Start(ctx, options)
    if err != nil { return nil, err }
    // support.Identity() returns only device ID/code; enrollment is asynchronous.
    // Keep support while the host performs its normal work.
    return support, nil
}

func stopSupport(support *sdk.Support) error {
    support.Stop() // Requests cancellation; nonblocking.
    return support.Wait() // Join before host shutdown, off the UI thread.
}

완전한 실행 예제는 examples/go/main.go입니다. 컨텍스트 취소와 Stop은 종료 요청이며 Done/Wait가 완료를 확인합니다. 프로세스당 한 인스턴스만 허용합니다. SDK는 호스트의 signal handler를 바꾸거나 os.Exit를 호출하거나 업데이터를 설치하지 않습니다.

5. 데스크톱 캡처를 추가할 때

처음에는 mode=terminal로 연결과 종료를 확인합니다. GUI가 필요하면 해당 로그인 사용자의 그래픽 세션 안에서 mode=auto로 실행합니다. DISPLAY, WAYLAND_DISPLAY, XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS를 임의로 다른 사용자 것으로 바꾸지 않습니다.

sh
sudo apt-get install --no-install-recommends pkg-config libgstreamer1.0-dev \
  libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good gstreamer1.0-pipewire wl-clipboard
mkdir -p dist/sdk/native
cc -O2 -Wall -Wextra -Werror native/capture.c \
  -o dist/sdk/native/streamzet-capture \
  $(pkg-config --cflags --libs gstreamer-app-1.0)
# Set config.capture_helper to the ABSOLUTE path of streamzet-capture.
# Set config.mode to "auto".

Wayland는 PipeWire와 해당 데스크톱의 xdg-desktop-portal 구현이 필요하고 사용자가 공유/원격 제어를 승인해야 합니다. 거부하면 데스크톱 제어가 생기지 않으며 터미널 연결은 별도로 유지될 수 있습니다. X11도 실제 디스플레이 권한과 GStreamer 플러그인을 확인합니다. 파일 전송은 이 SDK의 지원 기능이 아닙니다.

6. 전달과 운영

호스트와 함께 대상 ABI의 라이브러리, 생성 헤더, 필요한 캡처 헬퍼, 라이선스와 공개 설정 주입 절차를 전달합니다. 상태 디렉터리는 업데이트 때 보존하고 백업 권한을 제한합니다. 대시보드 온라인·연결 상태와 SDK의 running을 같은 의미로 취급하지 마세요.