API와 연동 가이드 · 수정 2026-09-22

Linux API 명세

Name: Streamzet
Author: Plitsoft

Go 필드·C JSON 이름·반환 코드·메모리 소유권. 작업 시작 전에 설정을 검증합니다.

이 페이지에서

sdk.Options / 최상위 JSON

필드 / API	형식 / 기본값	계약
Config / config	sdk.Config · required	아래 연결·기능 설정. Start에서 복사본을 검증·기본값 처리.
StateDir / state_dir	string · required	소유한 절대 경로 디렉터리, 0700, 심볼릭 링크 불가. 없으면 생성. 파일 잠금으로 동시 ID 사용 금지. 업데이트 시 유지하고 타 기기로 복제 금지.
Fleet / fleet	bool · false	지원 실행 중 호스트 OS 사용자 권한의 원격 일괄 명령 허용 여부.

필드 / API	형식 / 기본값	계약
SupabaseURL / supabase_url	string · required	HTTPS origin. 포트·끝 / 허용. 자격 정보·하위 경로·쿼리(빈 ? 포함)·fragment 금지.
PublishableKey / publishable_key	string · required	공백이 아닌 공개/anon 키. service-role 금지.
RegistrationKey / registration_key	string · ""	선택적 테넌트 등록. sz_live_ 접두사·최대 128바이트. 등록에만 전송. 빈 값이면 기기 코드 연결.
SignalURL / signal_url	string · required	SupabaseURL과 같은 제한을 따르는 WSS origin.
DeviceName / device_name	string · hostname	빈 값은 os.Hostname(). 최종 이름은 공백 불가·UTF-8 최대 128바이트.
CaptureHelper / capture_helper	string · /usr/lib/streamzet/streamzet-capture	캡처 도우미 절대 경로. terminal 모드도 경로 형식 검증. 파일 존재 여부는 Start가 아닌 캡처 시작 시 확인.
Mode / mode	string · auto	빈 값은 auto. auto는 현재 사용자 데스크톱 탐지, terminal은 터미널 전용. 다른 값 거부.
RelayOnly / relay_only	bool · false	true는 WebRTC를 릴레이 후보로 제한하며 TURN 필요. false는 직접·릴레이 경로 허용.

필드 / API	형식 / 기본값	계약
Start(ctx, options)	(*Support, error)	ctx: nil·취소되지 않은 context.Context. options: sdk.Options. root·설정/경로 오류·프로세스/상태 중복·파일/ID 실패 거부. ErrRunning은 같은 프로세스의 기존 SDK. 성공 후 비동기 등록. 서비스·시그널 핸들러 설치 없음.
Support.Stop()	void	반복 가능한 비차단 취소. 종료 완료를 보장하지 않습니다.
Support.Wait()	error	작업 종료까지 차단. 정상 종료 nil, 그 외 최종 오류. GUI 스레드 호출 금지.
Support.Done()	<-chan struct{}	작업 정리 완료 시 닫히는 읽기 전용 채널.
Support.Identity()	Identity	스레드 안전 공개 스냅샷. 비밀 제외. DeviceCode는 등록 후, DeviceID는 등록 전에도 존재 가능. 접속 상태 아님.

필드 / API	형식 / 기본값	계약
StreamzetStart(char *json)	int	NUL 종료 UTF-8 JSON. 반환 전 복사, 입력은 호출자 소유. 알 수 없는 필드·추가 JSON 거부. 0 시작, 1 설정/시작 오류, 2 이미 시작된 핸들(작업 종료 후에도 재사용 전 Stop).
StreamzetStatus()	char * · owned JSON	아래 필드의 스냅샷. 반환 포인터는 StreamzetFree로 정확히 한 번 해제. Start/Stop과 직렬화되어 Stop 중 Status가 대기할 수 있습니다.
StreamzetStop()	void	직렬화·반복 가능·차단. 종료 요청·대기·핸들 해제. 작업 스레드에서 호출. ID는 삭제하지 않습니다.
StreamzetFree(char *value)	void	Status 반환 포인터 또는 NULL만 전달. 중복 해제·호출자/Go 포인터 전달 금지.

필드 / API	형식 / 기본값	계약
running	boolean · false	작업이 살아 있음. 온라인·등록·운영자 연결 상태와 다릅니다.
error	string · ""	최근 동기 Start 실패 또는 Stop이 수집한 오류. 빈 값은 기록된 오류 없음이며 통신 성공이 아닙니다.
identity	object · omitted	C 핸들이 있으면 제공. Start 전·Stop 후 생략. secret·instance_id 미노출.
Identity.DeviceID / identity.device_id	string	등록 전에 생성되는 영구 공개 UUID.
Identity.DeviceCode / identity.device_code	string · ""	등록 후 연결 코드. 미등록이면 빈 값.