본문으로 건너뛰기

외부 SDK / API

Middle Control 는 TCP API 를 제공하여 외부 디바이스나 소프트웨어가 Middle Control 에 명령을 보내고, 카메라 및 gimbal 의 실시간 데이터를 읽을 수 있습니다.

다음과 같은 경우에 유용합니다:

  • 커스텀 디바이스 또는 스크립트에서 프리셋을 트리거하거나, 녹화를 시작/정지하거나, gimbal 을 제어할 때
  • Middle Control 을 방송 자동화 워크플로우에 통합할 때
  • Middle Control 과 직접 통신하는 커스텀 컨트롤 패널(하드웨어 또는 소프트웨어)을 구축할 때
포트 변경 — API 가 이제 포트 11584 에서 동작합니다

이 API 는 이전에 포트 11581 로 문서화되어 있었습니다. 해당 포트는 Middle Remote (Glue) 연결과 공유되며, Middle Remote 가 Direct 모드(macOS 기본값)일 때 거부됩니다. 기존 통합이 11581 을 기반으로 구축되어 있다면, 포트를 11584 로 변경하기만 하면 됩니다. 명령어와 피드백 프레임은 동일합니다. (이 외부 API 는 macOS 전용 기능입니다. Windows 에서는 Companion 포트 11580 과 Glue / Remote 포트 11581 을 사용하세요.)

노트

APC-R 유닛과 직접 통신하는 SDK 는 없습니다. 모든 명령은 컴퓨터에서 실행 중인 Middle Control 앱을 통해 전달됩니다.

🔌 연결​

디바이스 또는 소프트웨어는 Middle Control 이 실행 중인 컴퓨터에 일반 텍스트 TCP 명령을 전송합니다. 각 명령은 짧은 문자열(예: CAM3, PRESET1, P500)이며, 줄 바꿈 문자로 끝납니다 — 한 줄에 하나의 명령입니다.

TCP 연결 정보

호스트 : Middle Control 이 실행 중인 컴퓨터의 IP 주소 (소프트웨어가 동일한 컴퓨터에서 실행되는 경우 127.0.0.1 사용)

포트 : 11584

종료 문자 : \n (LF 또는 CRLF)

참고 사항:

  • 명령어는 대소문자를 구분합니다 — 이 페이지에 명시된 그대로 전송하세요.
  • API 는 fire-and-forget 방식입니다. 잘못된 형식이거나 알 수 없는 명령은 오류 응답 없이 무시됩니다. 상태 확인은 실시간 피드백을 사용하세요.
  • 통합이 연결되면, Middle Control 왼쪽 사이드바의 컨트롤러 항목 아래에 External API 항목이 나타나며, 연결이 열려 있는 동안 표시됩니다.

터미널에서 빠른 테스트 — 카메라 1을 선택하고 프리셋 1을 트리거합니다:

printf 'CAM1\nPRESET1\n' | nc <MIDDLE_CONTROL_IP> 11584

🎯 카메라 선택 및 타겟 지정​

이 페이지의 모든 명령은 카메라 ID(1–99)에 따라 동작합니다. 카메라를 지정하는 방법은 두 가지입니다:

  1. CAMx 로 카메라를 선택 — 이후 명령이 해당 카메라에 적용되며, 피드백 프레임에도 반영됩니다. 사이드바에서 카메라를 클릭하는 것과 동일하게 Middle Control 의 선택된 카메라가 변경됩니다.
  2. 끝에 @Cx 를 추가하여 특정 명령만 타겟 지정 — 선택을 변경하지 않고 카메라 x 에 명령이 전달됩니다.
명령어설명
CAM3카메라/gimbal 3 선택 — 이후 명령이 해당 카메라에 적용됩니다
REC_START@C2카메라 2에서 녹화 시작, 선택 변경 없음
AUTOFOCUS@C5카메라 5에서 오토포커스 트리거, 선택 변경 없음
P500@C1카메라 1에 팬 명령 전송, 선택 변경 없음
팁

타겟 명령을 사용하면 멀티 카메라 동작이 간편합니다 — REC_START@C1, REC_START@C2, REC_START@C3 을 연속으로 전송하여 카메라 1, 2, 3에서 동시에 녹화를 시작하세요.

🕹️ Gimbal & PTZ 제어​

가변 속도​

지정한 속도로 축을 구동합니다 — 해당 축에 0 을 전송할 때까지 계속 이동합니다:

명령어설명
Pxx팬 속도, xx 는 -2048에서 +2048 사이 (INT16)
Txx틸트 속도, xx 는 -2048에서 +2048 사이 (INT16)
Rxx롤 속도, xx 는 -2048에서 +2048 사이 (INT16)
Zxx줌 속도, xx 는 -2048에서 +2048 사이 (INT16)
정지하려면 0을 전송하세요

P500 은 팬 이동을 시작하고 P0 은 정지합니다. 안전장치: TCP 연결이 끊어졌을 때 축이 여전히 이동 중이라면, Middle Control 이 자동으로 해당 축을 정지시킵니다.

버튼 명령 및 프리셋에 사용되는 속도 설정:

명령어설명
PTSxx팬/틸트 속도 설정, xx 는 1에서 100 사이 (INT8)
ZSxx줌 속도 설정, xx 는 1에서 100 사이 (INT8)

절대 위치​

단일 명령으로 gimbal 을 정확한 위치로 이동합니다. 프레임 형식은 다음과 같습니다:

aGLOB;aPxx;aTxx;aRxx;aZxx;ss
항목설명
aGLOB프레임의 시작 부분에 반드시 포함되어야 합니다
aPxx절대 팬 위치, 1/10도 단위 (INT16)
aTxx절대 틸트 위치, 1/10도 단위 (INT16)
aRxx절대 롤 위치, 1/10도 단위 (INT16)
aZxx절대 줌 위치, 0에서 4096 사이 (INT16)
ss전환 시간(초)

예시: 5초에 걸쳐 팬 20°, 롤 2°, 틸트 7.5°, 줌 중간 범위로 이동:

aGLOB;aP200;aR20;aT75;aZ2500;5

현재 전환 속도를 사용하여 단일 축만 전송할 수도 있습니다:

명령어설명
aPxx / aTxx / aRxx해당 축을 xx 위치로 이동, 1/10도 단위
aZxx줌을 xx 위치로 이동, 0에서 4096 사이

버튼 및 유틸리티​

버튼 누름처럼 동작합니다:

명령어설명
PAN_L / PAN_RGimbal 을 왼쪽 / 오른쪽으로 팬
TILT_U / TILT_DGimbal 을 위 / 아래로 틸트
ROLL_L / ROLL_RGimbal 을 왼쪽 / 오른쪽으로 롤
정지 명령이 필요합니다

위의 각 이동 명령 이후, 최소 70ms 지연 후 대응하는 정지 명령을 반드시 전송해야 합니다:

이동정지 명령
PAN_L / PAN_RPAN_IDLE
TILT_U / TILT_DTILT_IDLE
ROLL_L / ROLL_RROLL_IDLE

정지 명령 전에 연결이 끊어지면, Middle Control 이 자동으로 이동을 정지시킵니다.

명령어설명
ZOOM+ / ZOOM-한 단계씩 줌 인 / 아웃
SPEED+ / SPEED-팬/틸트 속도 증가 / 감소
ZSPEED+ / ZSPEED-줌 속도 증가 / 감소

Gimbal 유틸리티:

명령어설명
RECENTERGimbal 을 중앙으로 복귀
ACTIVETRACKActive Track 활성화 / 비활성화
GIMBALSLEEP / GIMBALWAKEGimbal 슬립 / 웨이크
GIMBALAUTOCALIBGimbal 자동 교정(Autotune) 시작
MOTORAUTOCALIB포커스 모터 자동 교정 시작

🎥 카메라 제어​

사용 가능 여부는 카메라 브랜드와 연결 방식에 따라 다릅니다(일부 명령은 Sony 전용이거나 ATEM 링크가 필요합니다).

절대값​

카메라 값을 직접 설정합니다:

명령어설명
aFxx포커스, xx 는 0.0에서 1.0 사이 (FLOAT)
aIxx조리개, xx = f-숫자 (FLOAT) — 가장 가까운 지원 f-스톱으로 조정됨 (약 f/1.2에서 f/22)
aWBxx화이트 밸런스, xx 는 2500에서 10000 켈빈 사이 (INT16 — 정수만 가능)
aTINTxx틴트, xx 는 -100에서 +100 사이 (INT8)
aISOxxISO / 게인(dB), xx 는 -12에서 +36 사이 (INT8)
aSHUTxx셔터, xx = 분모 (INT16 — 예: 1/50s의 경우 aSHUT50)
NDxx / NDCLEARND 필터, xx = 분모: ND4 = 1/4, ND16, ND64, ND256, ND1024 (내장 ND 가 있는 모든 브랜드의 표준 래더); Sony 가변 ND 바디에서는 2 – 4096 범위의 임의 값 사용 가능; NDCLEAR (또는 ND0) 는 필터를 해제합니다. 피드백 프레임에서는 aND 로 읽힙니다

ATEM 스위처를 통해 제어되는 카메라의 색상 보정 값:

명령어설명
aSATxx채도, xx 는 0에서 100 사이
aCONTxx대비, xx 는 0에서 100 사이
aBLACKLEVxx블랙 레벨(리프트 루마), xx 는 -2.0에서 +2.0 사이
aMIDLEVxx미드 레벨(감마 루마), xx 는 -4.0에서 +4.0 사이
aWHITELEVxx화이트 레벨(게인 루마), xx 는 0에서 16.0 사이

켈빈/틴트 대신 레드/블루 게인을 사용하는 VISCA 카메라:

명령어설명
aRGAINxx레드 게인, xx 는 0에서 255 사이
aBGAINxx블루 게인, xx 는 0에서 255 사이

단계 및 토글​

명령 1회당 1단계 변경:

명령어설명
FOCUS+ / FOCUS-포커스 인 / 아웃 — 앱의 포커스 버튼과 동일하게 동작합니다: 명령 1회 = 미세 1단계; 연속 명령(버튼 유지, 인코더 빠르게 회전)은 점점 빨라지다가 마지막 명령 후 200ms 뒤에 정지합니다
FOCUS+0.002 / FOCUS-0.002렌즈 이동 범위의 정확히 그 비율만큼 포커스 인 / 아웃, 램프 없음 (0 < size ≤ 1; FOCUS+0.01 은 4.0.4 이전 기본 명령의 단계값)
IRIS+ / IRIS-조리개 증가 / 감소
WB+ / WB-화이트 밸런스 증가 / 감소
ISO+ / ISO-ISO 증가 / 감소
TINT+ / TINT-틴트 증가 / 감소
SHUTTER+ / SHUTTER-셔터 증가 / 감소
ND+ / ND-ND 필터 증가 / 감소
SHARP+ / SHARP-선명도 증가 / 감소
CONT+ / CONT-대비 증가 / 감소 (ATEM)
SAT+ / SAT-채도 증가 / 감소 (ATEM)
BLEV+ / BLEV-블랙 레벨 증가 / 감소 (ATEM)

버튼을 누르는 동안 포커스 이동​

누르고 유지하는 버튼(Stream Deck, 컨트롤러 키)의 경우, 누를 때 시작 명령을, 놓을 때 정지 명령을 전송하세요 — 포커스가 마우스로 앱의 포커스 버튼을 누르고 있을 때와 똑같이 움직입니다: 미세한 첫 단계 후 점점 빨라집니다.

명령어설명
FOCUS_IN / FOCUS_OUT포커스 인 / 아웃 이동 시작 (FOCUS+ / FOCUS- 와 동일한 방향)
FOCUS_IDLE정지

FOCUS_IDLE 전에 연결이 끊어지면 Middle Control 이 자동으로 이동을 정지시킵니다. 정지 명령 없이 10초가 경과하면 유지 상태도 해제됩니다. 세 명령 모두 @C<n> 카메라 접미사를 지원합니다.

자동 모드 및 모니터링 토글:

명령어설명
AUTOFOCUS오토포커스 트리거
AUTOIRIS자동 조리개 트리거
AUTOSHUTTER자동 셔터 토글
AUTOGAIN자동 게인 / ISO 토글
AUTOWB자동 화이트 밸런스 토글
COLORBARS컬러 바 표시
ZEBRA제브라 가이드 표시
FALSECOLORS폴스 컬러 가이드 표시
FOCUSPEAKING포커스 피킹 토글
STATUSVIEW카메라 HDMI 출력에 상태 뷰 표시
DIGITAL_ZOOM디지털 줌 토글 (Sony)
RESETCCUCCU / 색상 보정 값 초기화

메뉴 내비게이션 (Sony)​

명령어설명
BTN_MENU메뉴 버튼 누름
BTN_OKOK 버튼 누름
BTN_LEFT / BTN_RIGHT / BTN_UP / BTN_DOWN방향 버튼 누름
MULTISEL_LEFT / MULTISEL_RIGHT / MULTISEL_UP / MULTISEL_DOWNMultiSelector 이동
MULTISEL_PRESSMultiSelector 누름
CUSTOM_C1 … CUSTOM_C6커스텀 기능 C1 … C6 트리거

녹화​

명령어설명
REC_START녹화 시작(현재 선택된 카메라)
REC_STOP녹화 정지(현재 선택된 카메라)
REC_START_ALL모든 카메라에서 녹화 시작
REC_STOP_ALL모든 카메라에서 녹화 정지

피드백 프레임은 REC_LIST[…] 에 현재 녹화 중인 카메라 목록을 표시합니다.

📌 프리셋​

명령어설명
PRESET1 … PRESET12현재 선택된 카메라의 프리셋 1 … 12 트리거
PRESET1@C5 … PRESET12@C5카메라 5의 프리셋 1 … 12 트리거 (Middle Control 의 프리셋 5.1 – 5.12)
SPRESET1@C5 … SPRESET12@C5카메라 5의 프리셋 1 … 12 저장 (Middle Control 의 프리셋 5.1 – 5.12)

프리셋 재생 제어:

명령어설명
STOPPRESET진행 중인 프리셋 이동 정지 (특정 카메라를 정지하려면 @Cx 추가)
PRES_Dxx프리셋 전환 시간 설정, xx 는 초 단위
PRES_Exx프리셋 전환 이징 설정, xx 는 0(선형)에서 100 사이 — PRES_D 와 마찬가지로 모든 카메라에 동일하게 적용 (APC-R 펌웨어 2.0 이상)

🔁 자동화​

자동화 페이지의 자동화를 시작, 정지, 조정합니다. 모든 명령은 @Cx 타겟 지정을 지원합니다.

카메라 쉐이크

명령어설명
SHAKE-START / SHAKE-STOP카메라 쉐이크 시작 / 정지
SHAKE-SPEEDxx쉐이크 속도, xx 는 1에서 100 사이
SHAKE-AMPLxx쉐이크 진폭, xx 는 1에서 100 사이

줌 루프

명령어설명
ZLOOP-START / ZLOOP-STOP줌 루프 시작 / 정지
ZLOOP-SPEEDxx줌 속도, xx 는 1에서 100 사이
ZLOOP-DURATIONxx줌 이동 시간, xx 는 초 단위 (0.1 – 60)
ZLOOP-RESTDURATIONxx루프 간 일시 정지, xx 는 초 단위 (0.1 – 15)

프리셋 시퀀스

명령어설명
PRESETSEQ-START / PRESETSEQ-STOP프리셋 시퀀스 시작 / 정지
PRESETSEQ-BANKx활성 시퀀스 뱅크 선택, x 는 1에서 7 사이
PRESETSEQ-SPEEDxx시퀀스 전환 속도, xx 는 초 단위 (0.1 – 15)
PRESETSEQ-RESTDURATIONxx각 프리셋에서의 대기 시간, xx 는 초 단위 (0.1 – 15)

피드백 프레임은 선택된 카메라의 각 자동화 실시간 상태를 보고합니다: SHAKE_RUN, ZLOOP_RUN, PRESETSEQ_RUN(실행 중일 때 1), PRESETSEQ_BANK(활성 뱅크).

🖥️ Live View & Multi View​

Middle Control 이 실행 중인 컴퓨터에서 모니터링 창을 열거나 닫습니다:

명령어설명
LIVEVIEW_OPEN / LIVEVIEW_CLOSE현재 선택된 카메라의 Live View 창 열기 / 닫기 (먼저 CAMx 로 카메라를 선택하세요)
MULTIVIEW_OPEN / MULTIVIEW_CLOSEMulti View 창 열기 / 닫기 (Middle Control Pro 전용 — 없으면 무시됨)

📡 실시간 피드백​

Middle Control 은 동일한 TCP 연결을 통해 약 초당 4회 실시간 상태 프레임을 전송합니다. 프레임은 현재 선택된 카메라를 반영합니다. 이를 통해 gimbal 과 카메라의 현재 상태를 읽을 수 있어, 피드백 디스플레이나 반응형 워크플로우를 구축하는 데 유용합니다.

노트

카메라 값 피드백은 Middle Control 이 ATEM 스위처 또는 유선 LAN 을 통해 카메라에 연결되어 있을 때 사용할 수 있습니다. Gimbal 각도는 APC-R 이 카메라에 연결되어 있을 때 포함됩니다.

TCP Feedback Frame — example
{CAM5;REC1;AF0;DZOOM0;aWB5600;aF0.45;aI6.5;aUI5.4;aTINT10;aISO12;aSHUT1/50;aSAT50;aCONT50;aBLACKLEV0.4;SHAKE_RUN0;ZLOOP_RUN0;PRESETSEQ_RUN1;BRANG_RUN0;PRESETSEQ_BANK1;aPAN523;aTILT124;aROLL890;aZOOM3992;PTS85;ZS24;PRES_D8.0;PRES_ACTIVE0;PRES_E50;REC_LIST[5];CAM_CON_LIST[1,2,5];APCR_CON_LIST[5]}

각 프레임은 \n 으로 끝나는 한 줄입니다: {CAM<id> 로 시작하여 ; 로 구분된 토큰이 이어지고 } 로 닫힙니다. 토큰 순서:

토큰의미
CAM선택된 카메라 ID
REC / AF / DZOOM선택된 카메라의 녹화 / 오토포커스 / 디지털 줌 상태 (1 또는 0)
aWB화이트 밸런스(켈빈)
aF포커스 위치, 0.0 – 1.0
aI / aUI조리개 f-숫자(스톱 고정 / 비고정)
aTINT틴트(부호 있음)
aISO게인(dB)
aSHUT셔터(분모, 예: 50 또는 1/50)
aNDND 필터(분모 형식, 4 = 1/4, 16, 64 …); 필터가 해제되어 있거나 카메라에 ND 가 없는 경우 -
aSAT / aCONT / aBLACKLEV채도, 대비, 블랙 레벨 (ATEM 연결 카메라)
SHAKE_RUN / ZLOOP_RUN / PRESETSEQ_RUN선택된 카메라에서 해당 자동화가 실행 중이면 1, 아니면 0 (BRANG_RUN 은 예약됨, 항상 0)
PRESETSEQ_BANK활성 프리셋 시퀀스 뱅크, 1 – 7
aPAN / aTILT / aROLLGimbal 각도, 1/10도 단위 (APC-R 연결 시)
aZOOM줌 모터 위치, 0 – 4096 (APC-R 연결 시)
PTS / ZS현재 팬/틸트 속도 및 줌 속도 설정
PRES_D프리셋 전환 시간(초)
PRES_ACTIVE프리셋 이동이 실행 중이면 1, 아니면 0
PRES_E프리셋 전환 이징, 0 – 100 (펌웨어 2.0 이상의 APC-R 이 연결되지 않은 카메라의 경우 -)
REC_LIST[…]현재 녹화 중인 카메라 ID
CAM_CON_LIST[…]현재 연결된 카메라 ID
APCR_CON_LIST[…]APC-R gimbal 이 연결된 카메라 ID
위치가 아닌 토큰 이름으로 파싱하세요

카메라 브랜드와 연결 방식에 따라 일부 토큰이 프레임에 없을 수 있으며, 사용할 수 없는 값은 -(대시)로 전송됩니다. 모든 토큰이 항상 존재하고 숫자라고 가정하지 말고, 두 경우 모두 처리할 수 있도록 파서를 구현하세요.

최종 수정: 에