“핸드셰이크 실패 경로에서 호스트 프로세스 전체가 죽었다”는 지적이 당시 검증 기록에 남아 있다. C++와 파이썬을 소켓으로 연결해 본 개발자라도, 연결 실패가 앱 전체의 종료로 번질 수 있다면 어디까지 설계해야 할지 막막해진다. 이 자막 플러그인의 기록이 보여 주는 기준은 메시지 경계부터 취소·스레드 정리까지 하나의 수명 주기로 검토해야 한다는 것이다.

이 프로젝트의 코드와 설계는 AI 에이전트가 작성했고, 적대적 검증도 작성자와 분리된 모델 검증 레인이 수행했다. 운영자는 하이브리드 방향을 결정하고 GPL-2.0 라이선스를 명시적으로 승인했다. 아래 내용은 당시 기록에 남은 설계와 검증 결과이며, 필터 결선과 Windows 플러그인 로드까지 완료한 사례는 아니다.

IPC의 종료 설계는 정상 연결을 끊는 순서뿐 아니라, 시작에 실패한 경로에서 누가 취소하고 스레드를 회수하는지까지 포함해야 한다.

exe 하나로는 안 되는 이유

기존 구조는 별도 실행 파일이 obs-websocket으로 OBS의 텍스트 소스를 갱신하는 방식이었다. 사용자는 외부 도구를 실행하고 OBS와의 연결도 설정해야 했다. 당시 방향 결정은 이 구조를 얇은 C++ 오디오 필터와 파이썬 인식 엔진 사이드카를 연결하는 하이브리드로 옮기는 것이었다.

기록에는 whisper.cpp를 임베드한 오디오 필터 플러그인이 기술적 선례로 검토돼 있다. 하지만 기존 인식 스택의 faster-whisper는 파이썬 전용이어서 C++에 직접 링크하는 방식으로 옮길 수 없었다. 순수 네이티브로 전환하면 클라우드와 로컬을 합친 열두 개 인식 엔진, 설정 GUI와 CSS 자산을 그대로 재사용하기 어려웠다. 하이브리드 선택은 이 파이썬 자산을 유지하면서 OBS 쪽 접점을 필터로 만드는 결정이었다.

확정된 IPC 전송 계층은 자식 프로세스의 표준 입출력(stdin/stdout)을 이용하는 바이너리 파이프였다. 기존 웹소켓 경로와 달리 OBS와 사이드카 사이에 수신 포트를 열지 않는 설계다. 이는 두 프로세스 사이의 IPC에 관한 설명이며, 파이썬 엔진의 클라우드 API 통신까지 없어진다는 뜻은 아니다.

기존 실행 방식과 하이브리드 설계의 비교
항목기존 exe + obs-websocket하이브리드 설계
사용 형태별도 실행 파일 + 연결 설정OBS 필터로 제공하는 것이 목표
통신 경로로컬 웹소켓 포트 + JSONstdin/stdout 바이너리 파이프
OBS↔인식 프로세스 수신 포트웹소켓 포트 사용없음
기존 파이썬 엔진 12종기존 실행 파일에서 사용사이드카에서 재사용
라이선스 결정이 비교에서 별도 판단하지 않음libobs 링크와 선례 호환성을 근거로 GPL-2.0 승인

C++ 필터와 파이썬 사이드카가 나눠 맡는 일

설계에서 C++ 필터는 libobs에 직접 링크되는 얇은 오디오 필터를 맡는다. OBS 오디오 파이프라인에서 PCM 오디오 샘플을 받아 자식 프로세스로 전달하고, 인식 결과가 돌아오면 자막 텍스트 소스를 갱신하는 역할이다. 모델 추론과 클라우드 API 연동, 기존 엔진 설정은 파이썬 쪽에 유지하는 구조였다.

위에서 아래로 세 층이 쌓인 구조다. 맨 위 libobs에 직접 링크된 얇은 C++ 오디오 필터가 OBS 오디오 파이프라인의 PCM 샘플을 받고, 그 아래 파이프로 연결된 IPC 어댑터가 샘플을 자식 프로세스인 파이썬 사이드카로 넘긴다. 모델 추론과 클라우드 API 연동은 파이썬 쪽이 기존 설정 그대로 맡는다.
오디오 콜백 작업과 음성 인식 추론을 서로 다른 프로세스에 두고 그 사이를 IPC 어댑터가 잇는 구조이다.

파이썬 쪽에는 오디오 입력을 받는 feed_audio, 중간 결과를 전달하는 on_partial, 최종 결과를 전달하는 on_final 인터페이스가 이미 있었다. 스트림의 시작·비우기·종료를 위한 start_stream, flush, stop_stream도 기록에 남아 있다. 이 인터페이스에 IPC 어댑터를 연결해 기존 인식 스택을 수정 없이 재사용하는 것이 설계의 이점이었다.

이 분리는 오디오 콜백의 작업과 음성 인식 추론의 작업을 서로 다른 프로세스에 배치한다. 그 사이에서는 입력이 쌓이는 속도, 늦게 돌아오는 응답, 필터 종료 시점을 함께 다뤄야 한다. 따라서 연결 수단을 파이프로 정한 뒤에도 프레이밍과 큐, 결과 반영 시점에 관한 규칙이 필요했다.

16바이트 헤더와 CRC로 프레임을 지킨다

파이프는 바이트 스트림이므로 메시지 경계는 프로토콜이 정해야 한다. 기록된 프레이밍(framing) 규격은 16바이트 헤더와 페이로드의 CRC-32 체크섬을 사용한다. 헤더로 메시지를 구분하고 체크섬으로 데이터 손상 여부를 확인하는 구성이다.

C++ 필터와 파이썬 사이드카가 주고받는 프레임 C++ 오디오 필터와 파이썬 사이드카가 stdin/stdout 바이너리 파이프로 PCM 오디오 샘플과 인식 결과를 주고받고, 아래쪽에는 한 프레임이 16바이트 헤더, 페이로드, CRC-32 순서로 이어지는 모습을 흐르는 점선과 단계별 강조로 보여 준다. stdin/stdout 바이너리 파이프 C++ 오디오 필터 PCM 오디오 샘플 인식 결과 파이썬 사이드카 프레임 헤더 16바이트 페이로드 CRC-32
필터와 사이드카 사이의 파이프에서는 헤더와 CRC-32가 붙은 프레임 단위로 메시지가 오가며, 경계 구분과 손상 확인을 프로토콜이 맡는다.
// 개념 설명용 의사코드 — 실제 바이트 배치와는 다를 수 있음
struct FrameHeader {
  magic;      // 프레임 시작 표식
  length;     // 페이로드 길이
  seq;        // 순번 어긋남 감지용
};
// header(16B) + payload + crc32(payload)

설계 원칙은 프레임 동기화가 어긋나는 desync가 발생하면 세션을 종료하는 것이었다. 다만 구현 기록의 프레이밍 테스트 설명에는 순번 증분을 통한 재동기화와 복구도 등장한다. 두 설명이 같은 상황을 가리키는지는 확인되지 않았으므로, 실제 구현이 모든 재동기화 시도를 배제한다고 단정할 수는 없다.

모든 큐는 크기 상한이 있는 bounded queue로 정해졌다. 인식 속도가 입력 속도보다 느릴 때 대기 데이터가 제한 없이 쌓이지 않도록 하는 선택이다. 상한을 넘으면 오래된 프레임부터 버리는 drop-oldest 정책으로 최신 오디오를 우선한다.

버퍼는 seqlock 방식의 단일 생산자·단일 소비자(SPSC) 링버퍼로 기록돼 있다. 읽는 쪽은 버전을 확인해 쓰기 도중 섞인 값을 읽는 torn-read를 건너뛴다. 방향별 쓰기를 단일 writer로 직렬화하는 규칙도 포함됐다. 이는 버퍼 접근에 관한 규칙이며, 전송 계층의 다른 공유 상태까지 경쟁 상태가 없다는 보장은 아니다.

응답을 읽은 뒤 상태에 반영하는 시점에는 세대 관문(epoch gate)이 적용된다. 기록된 원칙은 reader의 모든 부작용을 실제 반영 시점의 세대로 검사하는 것이다. 독자가 비슷한 구조를 설계한다면 수신 시점의 유효성뿐 아니라, 늦게 도착한 결과를 지금 반영해도 되는지까지 구분해 검토할 수 있다.

종료는 반드시 한 번만

종료 설계에는 요청이 겹쳐도 종료 처리를 한 번만 수행하는 single-flight와, 파괴 요청을 우선하는 destroy-wins 원칙이 포함됐다. 기본 순서는 취소를 먼저 요청하고, 스레드를 join해 종료를 기다린 뒤, 진행 중인 생산자 작업이 멎은 상태에서 링을 해제하는 것이다. 이 순서는 목표로 정한 규칙이며, 당시 기록 끝에서도 destroy-wins 상태기계의 완성은 남은 작업이었다.

종료 순서를 다섯 단계로 나타낸 흐름도이다. 겹친 요청도 종료 처리는 한 번만 수행하고, 먼저 취소를 요청한 뒤 스레드를 join해 종료를 기다린다. 이어 count-then-check 방식의 생산자 정지 배리어로 진행 중인 작업이 멎었는지 확인하고, 마지막으로 링을 해제해 해제된 메모리 재사용을 막는다.
링은 취소와 join, 생산자 정지 확인이 끝난 뒤에만 해제해야 한다는 규칙이다.

해제된 메모리를 다시 사용하는 UAF를 방어하는 장치로는 count-then-check 방식의 생산자 정지 배리어가 기록돼 있다. 생산자 진입을 먼저 계수하고 종료 상태를 확인하며, 자원 해제 전에는 진행 중인 작업이 멎었는지 확인하는 규칙이다. 응답 대기자 역시 응답·타임아웃·종료 취소 중 하나로 정확히 한 번 완료돼야 한다는 조건을 갖는다.

1차 적대적 검증: 채널 필드와 조건 변수

1차 적대적 검증에서는 OBS 오디오 구조체에 존재하지 않는 audio->channels 필드를 가정한 문제가 CRITICAL 지적으로 나왔다. 같은 라운드에서 조건 변수에 predicate 없이 wait()만 호출한 코드도 HIGH 지적을 받았다. 조건 변수 문제는 실제 방송 가동 중 발생한 장애가 아니라, 검토 단계에서 발견한 lost-wakeup 데드락 위험으로 기록돼 있다.

알림이 대기 시작 직전에 도착하면 대기자가 이를 놓칠 수 있으므로, 알림 자체와 별도로 기다리는 조건을 검사해야 한다. 조건을 검사하면 이유 없이 깨어나는 spurious wakeup에서도 작업을 계속해도 되는지 판단할 수 있다. 당시 수정 기록에는 cv.wait(lk, predicate) 형태로 predicate 람다를 추가한 조치가 남아 있다.

이후 독립 검증: 실패 경로를 재현한 결과

이후 독립 검증 모델의 재현 하니스에서는 핸드셰이크 실패 뒤 워커 스레드가 join되지 않는 문제가 확인됐다. start_session() 실패 경로에 stop_session() 호출이 빠져 있었고, 객체 소멸 시 std::terminate가 발생해 호스트 프로세스 전체가 종료됐다. 이는 재현 환경에서 확인된 결과이며, 실제 방송 중 OBS가 종료됐다는 기록으로 확대할 수는 없다.

에이전트의 수정에는 시작 실패 시 종료 처리를 먼저 호출하고, 루프 종료 뒤에도 최종 join 안전망을 두는 조치가 포함됐다. 해당 실패 경로를 겨냥한 회귀 테스트도 추가된 것으로 기록돼 있다. 이 사례에서 검토할 지점은 종료 함수의 존재 여부뿐 아니라, 시작에 실패한 모든 경로가 그 함수를 거치는지다.

별도의 독립 검증에서는 alive()가 종료된 자식을 먼저 회수한 뒤 reap()이 다시 기다려 ECHILD를 받고 실제 종료 코드를 잃는 결함이 나왔다. Windows의 일부 reap() 경로에서는 파이프 핸들 두 개가 누수됐다. 일반 정수형 파일 디스크립터를 공유하면서 취소와 읽기·쓰기 사이에 생긴 데이터 레이스는 검증 레인의 ThreadSanitizer 실행으로 재현됐다. 당시 전송 계층 테스트 실행기에는 이 검사 단계가 없어, 이후 TSan 전용 단계가 추가됐다.

검증 순서: Mac 먼저, Windows는 관문으로

구현 순서는 libobs 없이 검사할 수 있는 순수 C++ 코덱을 먼저 검증하는 방식이었다. 당시 기록에는 프레이밍·링버퍼·에폭 게이트·종료 걸쇠에 대해 macOS에서 ASan·UBSan·TSan이 통과한 결과가 남아 있다. 이는 그 단계의 에이전트 실행 결과이며, 뒤에 추가된 전송 계층이나 완성된 OBS 플러그인 전체의 통과를 뜻하지 않는다.

그다음 관문은 플랫폼별 취소 동작을 분리한 개념 검증(PoC)이었다. 모델 검증 레인은 읽기 블로킹, 가득 찬 파이프의 쓰기 블로킹, 1MB 프레임의 큐 대기를 검사했다. 기록된 대기 해제 시간은 POSIX(macOS) 경로 6ms, 원격 Windows 머신 경로 15ms였고, 두 환경 모두 세 케이스가 PASS였다. 해당 검증에서는 폴백 경로가 필요하지 않았다.

이 수치는 당시 취소 PoC의 결과이지 자막 표시 지연이나 모든 자식 프로세스의 종료 시간을 보장하는 값은 아니다. 구현 계획은 Windows 전송 PoC를 후속 단계 진행의 필수 관문으로 두었다. 다른 앱에서도 전송 계층의 취소를 먼저 분리해 확인하면, 필터 결선 뒤의 문제를 살필 때 비교할 기준을 확보할 수 있다.

다음 항목은 이 기록에서 추린 설계 검토 질문이다. 핸드셰이크 실패 사례처럼 규칙이 있어도 특정 경로에서 호출이 빠질 수 있으므로, 문서와 실패 경로를 함께 대조하는 용도로 쓴다. 조건 변수, 자식 회수, 핸들 소유권은 아래 항목과 별도로 확인해야 한다.

  • 프레이밍: 메시지 경계와 CRC 검증 규칙이 정해져 있는가?
  • desync 대응: 세션 종료 원칙과 구현의 복구 경로가 어떤 조건에서 적용되는지 확인했는가?
  • 큐: 크기 상한과 오버플로 시 폐기 정책이 있는가?
  • 동시성: 방향별 쓰기가 직렬화되고, 다른 공유 상태의 경쟁도 검사되는가?
  • 반영 시점: 응답을 실제 반영할 때 세대의 유효성을 검사하는가?
  • 종료: 중복 요청과 시작 실패 경로에서도 취소·join·자원 해제 순서가 지켜지는가?
  • 플랫폼별 취소: 읽기·쓰기·큐 대기를 대상 운영체제에서 각각 재현해 확인했는가?

당시 남은 작업은 destroy-wins 상태기계와 reap-before-join 재정렬, 필터와 IPC 브리지의 실제 콜백 결선, Windows 플러그인 빌드와 OBS 로드 검증이었다. 특히 SIGTERM에 저항하는 자식 프로세스에서는 스레드 join이 무한 대기할 수 있다는 한계가 남아 상태기계 작업으로 이월됐다. 기록에는 기존부터 실패 중인 테스트도 한 건 남아 있어, 전체가 완료됐거나 모든 검사가 통과했다고 요약할 수 없다. 다른 동시성 프로그래밍 설계에 참고할 때도 확인된 취소 경로와 미완성 종료 경로를 함께 읽어야 한다.

자주 묻는 질문

faster-whisper를 C++ 플러그인에 직접 넣지 않은 이유는 무엇인가요?

faster-whisper는 파이썬 전용이어서 C++에 직접 링크하는 방식으로 옮길 수 없었다. 순수 네이티브 전환은 기존 열두 개 인식 엔진과 설정 GUI의 재사용을 어렵게 했다. 그래서 얇은 C++ 필터와 파이썬 사이드카를 IPC로 연결하는 방향이 선택됐다.

프레임 동기화가 어긋났을 때의 설계 원칙은 무엇인가요?

설계 원칙은 desync 발생 시 세션을 종료하는 것이었다. 다만 구현 기록에는 순번 증분을 통한 재동기화와 복구 테스트도 적혀 있다. 두 설명의 적용 조건은 확인되지 않아, 구현이 재동기화를 전혀 시도하지 않는다고 단정할 수는 없다.

오디오 큐가 가득 차면 왜 오래된 프레임부터 버리나요?

인식 속도가 입력 속도를 못 따라가면 상한 없는 큐에는 대기 데이터가 계속 쌓일 수 있다. 이 설계는 실시간 자막에 사용할 최신 오디오를 우선했다. 그래서 모든 큐에 크기 상한을 두고, 상한을 넘으면 오래된 프레임부터 버리는 정책을 정했다.

전송 계층 검증이 끝났으니 플러그인도 완성된 상태인가요?

아니다. destroy-wins 상태기계와 reap-before-join 재정렬, 필터 IPC 결선, Windows 빌드·OBS 로드 검증이 남아 있었다. SIGTERM에 저항하는 자식 프로세스에서는 스레드 join이 무한 대기할 수 있다는 한계도 상태기계 작업으로 이월됐다.