안녕하세요. 아이서티 김산 선임입니다.
api ver2.0 전달 드립니다.
 
1. 먼저 알려드릴 것
- Web Server DB 구조가 변경됐습니다. 기존 납품한 Web Server DB 데이터는 삭제해도 되니, 마이그레이션 없이 다시 생성하여 적용 부탁드립니다.
- ONVIF·RTP는 Media Server 적용·검증 예정이며, 진행 과정에서 API 문서가 일부 수정될 수 있습니다.
- Media Server WSS 접속 시 별도 인증서 설치는 필요 없습니다. Web Server·AI Server에서 해당 WSS 연결의 서버 인증서 검증을 생략하도록 설정해 주세요. 암호화 통신과 토큰 인증은 유지됩니다.
2. 중요 변경 사항
- ONVIF
Media Server에서 ONVIF 검색·인증·스트림 정보 조회를 처리합니다. Web Server가 선택한 MEDIA에 카메라 ID/PW를 전달하면 해당 MEDIA의 네트워크에서 검색하며, 실패한 장치는 수정한 ID/PW로 개별 재확인할 수 있습니다.
ONVIF 사용 여부를 켜고 끄는 설정은 없으며, 등록된 카메라에 자동으로 연결을 시도합니다. ONVIF 연결 실패가 RTSP 영상 수신·녹화를 중단시키지는 않습니다.
NVR처럼 한 IP에 여러 채널이 있는 장치는 영상 소스(VideoSource)별로 검색 결과를 구분합니다. 같은 소스의 main/sub는 하나로 묶으며, 선택한 채널의 videoSourceToken을 등록할 때 onvifVideoSourceToken으로 전달합니다. 다채널 장치에서 채널을 특정하지 못하면 임의의 채널에 PTZ·이미징 명령을 보내지 않고 ONVIF_CHANNEL_UNRESOLVED 오류를 반환합니다.
PTZ는 연속 이동을 사용하며(pan·tilt·zoom을 모두 0으로 보내면 정지), 주야간·포커스 제어는 이미징 API로 제공합니다. 실제 사용 가능한 기능은 카메라 지원 여부에 따릅니다.
ONVIF 오류 코드가 추가됐습니다(ONVIF_BUSY, ONVIF_CONFIGURATION_CHANGED, ONVIF_STOP_FAILED, ONVIF_OPERATION_CANCELLED, ONVIF_CHANNEL_UNRESOLVED). Web Server는 이 코드들을 HTTP 409와 원래 코드 그대로 전달합니다.
- RTP timestamp
시간 계산식은 유지됩니다.
absoluteMs = startWallTimeMs + rtpTimestamp × 1000 / rtpClockRate
원본 PTS 간격을 유지하고, startWallTimeMs는 기준 프레임의 Plus 수신 시각에서 해당 송출 RTP 시간을 뺀 값으로 제공합니다. 첫 RTP timestamp를 0으로 강제하지 않습니다.
B프레임은 전달·디코딩 순서와 화면 표시 순서가 다릅니다. 따라서 전달되는 RTP timestamp가 중간에 감소할 수 있으며, 이를 무조건 오류나 wrap으로 판단하면 안 됩니다. 압축 영상의 전달 순서를 유지하고, 디코딩·재인코딩 없이 원본 표시 시각 관계를 보존하는 방향입니다.
AI는 실제 분석한 프레임의 RTP 시각을, Client는 실제 표시한 프레임의 RTP 시각을 사용하여 같은 프레임의 분석 결과와 영상을 맞춰야 합니다. RTSP·WebRTC 간 일치 여부는 구현 후 함께 검증하며, wrap·재연결 시 시간 기준을 구분하는 계약은 추가 협의 예정입니다.
3. 변경 사항
- camera-tests.create·get·close 추가: 등록 전 영상 연결 테스트. MEDIA당 동시 1개, 최대 60초. 테스트 READY 후 10초 내 WebRTC 미연결 시 종료. 시청 종료 시 close 호출 필요.
- cameras.discover·probe 추가: ONVIF 검색·인증 및 개별 재확인.
- cameras.capabilities.get·refresh, cameras.onvif.status.get 추가: 지원 기능·연결 상태 조회.
- ptz.move(전부 0이면 정지), imaging.* 제어 API 정의. PTZ 프리셋·홈은 Media Server 확장 action(ptz.home.*, ptz.presets.*)만 정의되어 있고 Web Server 중계 API는 미정.
- onvifVideoSourceToken 추가(검색 결과는 videoSourceToken): 다채널 장치의 제어 대상 구분.
- configRevision 추가: 카메라 설정 반영 여부 확인 및 오래된 요청의 덮어쓰기 방지.
- 녹화 스케줄·스트리밍 설정의 revision은 Web Server가 소유. MEDIA는 받은 번호를 저장하고 낮은 번호는 무시. 스케줄 put은 전체 교체(목록에 없는 카메라는 24시간 녹화).
- 카메라·그룹 ID 전역화 및 Web Server 공통 관리.
- 카메라 등록과 MEDIA·AI 배정 분리. 복수 MEDIA 배정 및 AI 공급 MEDIA 지정.
- 카메라 그룹 필수, 소속 카메라가 있는 그룹 삭제 제한.
- 카메라 IP 중복 허용, 삭제되지 않은 카메라 이름 전역 중복 금지(앞뒤 공백·대소문자 무시).
- 매니저 모드의 Plus 설정 변경 제한. Web Server 저장값을 재접속·주기 동기화로 반영.
- 관리자 한 계정 고정(관리자 그룹 소속). 운영자 그룹별 기능 권한·카메라 배정(그룹 소속 운영자 전원에게 적용).
- 로그인 오류 분리: AUTH_FAILED(아이디·비밀번호 오류), ACCOUNT_DISABLED(비밀번호는 맞지만 비활성화된 계정).
- Streaming Server → Media Server, REC → MEDIA 명칭 변경.
- playback-sessions.* → recplay-sessions.*, exports.* → recexports.* 변경.
세부 요청·응답과 오류 처리 조건은 최신 API 문서를 기준으로 적용 부탁드립니다.

……………………………………………………………………………………………………………………………………………..
(주)아이서티 김산 선임
서울지점 : [04788] 서울특별시 성동구 광나루로 130, 서울숲IT캐슬 1201호
대전본점 : [34129] 대전광역시 유성구 가정로 218, 302-2-3호, (가정동, 융합기술연구생산센터)
전화번호 : +82. 2. 446. 8084 / +82 01. 2664. 3887
펙스번호 : +82. 2. 458. 8085
E-mail: qkfcl9987@icerti.com
Home: www.icerti.com / www.onnarasign.com/