obs-action-history

소리를 들을 수 있는 OBS Studio용 MCP 서버

이런 서버는 이미 여럿 있다. 대부분은 obs-websocket 요청 표면을 호출 하나씩 감싸고 거기서 멈춘다. 그렇게 만드는 것도 타당하고, OBS를 유능하게 다룰 수 있는 도구가 된다. 다만 그 도구는 특정한 방식으로, 그리고 결과적으로 큰 귀가 먹은 도구다.

이 서버는 이벤트 스트림을 구독하고, 일어난 일을 유한한 크기의 기록으로 보관한 뒤 그에 관한 질문에 답한다.

의존성 없음. Node 내장 모듈만 사용. Windows, macOS, Linux 지원.

중요한 차이

요청은 정확히 한 종류의 질문에만 답한다. 지금 이 순간에 무엇이 true인가. 물어보면 OBS가 답하고, 당신이 판단한다. 그 사이에 일어났던 일은 사라져 있고, 그것이 있었는지조차 알 수 없다.

물론 이건 아키텍처 각주처럼 들린다. 아니다. 그것이 당신에게 받는 대가를 생각해보라.

obs-websocket 프로토콜에는 오디오 레벨을 반환하는 요청이 하나도 없다. GetInputVolume은 페이더 위치를 준다. GetInputMute는 불리언을 준다. 어느 것도 실제로 소리가 마이크에서 나오는지는 말해주지 않는다. 레벨은 오직 이벤트인 InputVolumeMeters 한 곳에만 존재한다.

그래서 "내 마이크가 지금 제대로 동작하는가"라는 질문은 순수 request만으로 구축된 서버가 답할 수 없다. 형편없게 답하는 것도, 느리게 답하는 것도, 아예 답을 못 하는 것이다. 148개의 도구를 노출하는 서버는 12개를 노출하는 서버와 똑같은 사각지대를 가진다. 답이 둘 다 어떤 표면에서 만들어지는지 그 표면에 없기 때문이다.

이 서버는 그 스트림을 붙잡아 둔다:

GXP1.

InputVolumeMeters 는 소스당 초당 약 50회 듣는다. 아무도 도구 호출 한 번으로 원시 프레임 3,000개를 돌려받고 싶어 하지 않는다. 사람이 실제로 궁금한 것은 누가 컸나이므로 미터는 아예 버퍼에 들어가지 않는다. 소스당 최고치로 줄여진 뒤 결괏값으로 반환된다.

이것이 구체적으로 무엇을 가져다 주는가

설정은 올바른데 아무 소리도 내지 못하는 마이크. 페이더는 통일(0dB)이고 음소거도 아니며, 잘못된 장치가 선택되거나 케이블이 조용히 끊깁니다. 요청으로 살펴볼 수 있는 모든 설정값은 완벽하게 정상으로 보고된다. 이것은 가상 시나리오가 아니다. 그래서 이 서버가 만들어지기 전에는 이 리그에 별도의 마이크 점검 프로세스가 필요했던 것이다.

목소리를 따라가는 카메라. 두 마이크 중 어느 쪽이 더 큰 소리를 내는지를 계속 아는 방법이 필요하다. 그리고 고정된 임계값보다는 서로 비교해야 한다. 한 방에 있는 두 마이크는 이득(gain)이 다르고, 각자 모두의 목소리를 듣기 때문이다. 이 정보를 조회할 만한 것이 없다. 정보는 오직 발생하는 순간에만 도착한다.

살아 있지만 끼어버릂, 죽어 있는 것보다 나쁜 상태. 개발 중에 이 서버는 미디어 소스 다섯 개를 살폈고, 그중 모든 것이 PLAYING 으로 보고되었다. 그중 하나는 0밀리초 진행한 반면 나머지는 약 2,540ms 이동했다. 상태만으로는 구분할 수 없는 상태였다. 동작하는 피드와 죽은 것을 가르는 것은 경과된 시간뿐이었고, 그 사각지대는 이미 17시간 동안 소리 없는 음악을 초록색으로 보이는 대시보드 뒤에 숨겨져 있었다.

2분 전에 무슨 일이 있었는가. 폴링은 현재만을 설명할 수 있고, 그 밖에는 아무것도 할 수 없다. 일이 지나가고 나면 더는 할 수 없기 때문에, 해명하려고 하는바로 그 사고에 대해서 추측만 할 수 있을 뿐이다.

설명은 제품의 일부다

도구 설명은 파라미터 목록을 다시 늘어놓는 곳이 아니다. 모델은 이미 스키마를 읽을 수 있다. 그 자리는 그렇지 않으면 비용을 치러가며 배우게 될 것들 위해서다.

• OBS는 오디오 싱크 오프셋을 약 960ms에서 제한한다. 더 큰 값은 조용히 "아무것도 아닌 것으로" 적용된다. 그래서 2초인 단ого를 보정했다고 믿지만 실제로는 전혀 보정되지 않았었.

• 씬 아이템 인덱스 0은 맨 아래이다. 배경 위에 얹힌 전체 캔버스 소스는 그 배경을 완전히 가리고, 어디서도 오류가 발생하지 않는다.

• 캔버스 바깥에 둔 소스는 계속 화면에 보이고 오디오 집계. ** As을 그 대신 hide 했을 때는 오디오가 끊긴다. 따라서 audio-only 오버레이는 hidden이 아니라 off-canvas에 둔다.

• RemoveInput 은 성공을 반환하지만, 대상이 여전히 참조 중인 소스는 지우지 못하며.

• boundsType 필드는 먼저 설정하지 않은 한 동작하지 않는다.

• TriggerHotkeyByName 은 그냥 이름을 받으며, libobs.mute 는 오디오 소스당 한번씩, 이 레퍼레이스 머신에서 24회 등록해 있다. 따라서 핫키는, 합리적으로 기대하는 것과 달리 특정 소스를 지칭할 수 없다.

각각 하나씩 누군가에게 대가를 치르게 한다. 모델이 그 내용을 모르면 자신 있게 행동하고 틀릴 것이 때문에 남은 것이다. 그것은 조심스럽게 행동하고 맞는 것보다 훨씬 나쁘다.

새 기계를 가능하게 해주는 도구

obs_input_property_items 는 프로퍼티 뒤의 실제 선택지를 나열한다. 모든 웹캠과 모든 오디오 장치를 OBS가 실제로 요구하는 식별자와 함께.

Microphone (Some USB Mic)
  -> {0.0.1.00000000}.{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

거기에는 추측할 만한 사람이 읽을 수 있는 내용이 하나도 없다. 이 호출이 없으면 어시스턴트는 사람이 이미 손으로 만든 소스만 조정할 수 있다. 이 호출이 있으면 소스가 처음부터 만든다.

기능 범위

11개 모듈에 걸쳐 67개 도구.

설치

Node 22 이상 필요. 전역 WebSocket을 위해. OBS 31+ 에서 Tools → WebSocket server settings → Enable WebSocket server 를 켠다.

.mcp.example.json 을 MCP 클라이언트 설정으로 복사하고 args를 server.js에 지정한다. 비밀번호는 OBS_WEBSOCKET_PASSWORD 가 설정되어 있을 때 그것에서 읽고, 그 외에는 서버 옆의 secrets.json 파일에 적은 것을 읽는다:

GXP3.

잘못된 비밀번호는 잘못된 비밀번호로 드러나지 않는다. OBS는 소켓을 받아들인 다음 코드 4009로 닫는다. 대부분의 클아이언트는 이걸 timeout으로 보고하여, 네트워크 문제를 조사하느라 오후를 보낸다. 이 서버는 그 이유를 제대로 짚는다.

레퍼런스 머신

여기서 언급되는 수치들, 43종 필터, 88개만 고유한 411개의 핫키, 960ms 한계, 5개 output과 2개의리플레이 버퍼는 Windows에서 OBS 32.2.1와 obs-websocket 5.7.4를 돌리고 있는 머신으로, 그 머신이 세 플랫폼에 동시 송출하고 있을 때 측정했다. 서문에 나오는 레퍼런스 머신이라는 표현 그 모두 이 기기를 말한다. 각 설치에 따라 차이는 달라지며, 그 모든 숫자는 여기 있는 도구로 직접 확인할 수 있다. 애매숭한 수치를 둥글 어둡다고 하지 않고 명확히 밝혀 두는 것이 목적.두 기계에서 오픈된 obs-websocket 문서의 오류가 존재한다. GetSourceFilterKindList 는 문서에 따 filterKinds로 되어 있는 곳에서 sourceFilterKinds를 반환한다. 그리고 SetSourceFilterSettings는 기본값이 true인데 어떤 요약에서는 false라고 주장한다. false 를 넘기면 obs_source_reset_settings를 호출하고 그 필터의 tuned 파일 값을 모두 파괴한다. 이런은 한 번은 실수하는 종류다.

기여

mcp/tools/index.js 가 컨트랙트를 맺고 있다. 모듈은 (obs) => [{ name, description, inputSchema, handler }]를 내보내며 obs.request(type, data) 외에는 아무것도 사용하지 않는다.

로딩은 의도적으로 오류를 허용하는 방식이다. 누락되었거나, 빌드 도중 예외를 던지거나, 잘못된 툴을 반환하거나, 이름은 중복인 모듈은 로그만 남기고 건너뛴다. 서버는 그 나머지는 그대로 유지한 채 시작된다. 깨진 모듈은 당신의 몫이고, 다른 사람의 중계를 끊는 일은 되어서는 안 된다.

대쪽집이 열기 전에:

npm run preflight

그 토큰은 인증 정보, 절대 절대 경로, 시스템별 주소, 장치 식별자 거부하고, 각자 소중에 있는 모든 모듈은 여전히 로드되는지 확인한다.

상태

0.1.0 도구 이름은 1.0 이전에 변경될 수 있다. 스크립트에서 그 이름을 해당하면 정확한 버전을 잠가두라.

라이선스

MIT. LICENSE**참조.