# 🚀 우분투 서버 웹 스트리밍 최적화 작업 요청서

## 1. 현재 상황 요약
- **목표**: Python FastAPI + WebSocket 기반으로 카메라 RTSP/SRT 스트림을 브라우저에 실시간 전송하는 서버 최적화.
- **현상**: 웹 서버 구동 및 카메라 PTZ 제어 기능은 완벽히 정상 작동하나, **카메라 영상 프레임이 극도로 느리고 끊기는 현상**이 발생함.
- **원인 가설**:
  1. 서버의 CPU 성능이 낮아 OpenCV 디코딩 및 JPEG 인코딩 연산에서 병목이 발생함.
  2. FFMPEG 연결 지연이나 디코딩 패키지 미비로 인해 `VideoCapture` 루프에서 블로킹이 발생함.
  3. WebSocket 대역폭 부족 혹은 base64 인코딩 오버헤드가 누적됨.

---

## 2. 에이전트 미션 및 지침

아래 단계에 따라 서버 상태를 분석하고 점검하여 코드를 최적화해 주세요.

### [1단계] 시스템 리소스 & 병목 지점 파악
1. 현재 서버에서 실행 중인 `web_server.py` 프로세스의 CPU 사용량을 확인합니다.
   ```bash
   top -b -n 1 | grep python
   ```
2. 만약 CPU 사용량이 100%에 임박해 있다면, 디코딩/인코딩 오버헤드를 낮추는 작업이 최우선입니다.

### [2단계] OpenCV FFMPEG 최적화 파라미터 적용
RTSP 연결 시 네트워크 지연 대기를 최소화하도록 OpenCV 빌트인 FFMPEG 파라미터를 추가 적용해 주세요.
- **적용할 부분**: `web_server.py` 내의 `cv2.VideoCapture` 설정
- **변경안**:
  `cv2.VideoCapture(url, cv2.CAP_FFMPEG)`를 호출한 직후 아래 옵션들을 세팅하여 버퍼 대기 시간을 최소화합니다.
  ```python
  cap = cv2.VideoCapture(url, cv2.CAP_FFMPEG)
  # 하드웨어 디코딩 가속 혹은 버퍼 오버런 방지 옵션 추가
  cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)  # 버퍼 크기 최소화 (실시간성 확보)
  ```

### [3단계] 캡처 & 인코딩 루프 최적화 (스레드 분리)
현재 캡처 루프 내에서 디코딩과 JPEG 인코딩이 싱글 스레드로 묶여 있어 프레임 드랍이 일어날 수 있습니다. 
- **수정 방향**:
  - 카메라에서 프레임을 읽어오는 동작(`cap.read()`)은 별도 루프로 빠르게 돌려 최신 프레임 1장만 계속 변수에 업데이트합니다.
  - 전송 스레드(혹은 코루틴)는 일정 주기(예: 0.05초 = 20FPS)로 이 변수에서 이미지만 가져와 JPEG로 인코딩 후 WebSocket 브라우저로 쏩니다.
  - 이를 통해 네트워크 지연이나 인코딩 지연이 카메라 캡처 파이프라인을 멈추게 하지 않도록 차단(Decoupling)합니다.

### [4단계] 최적화 코드 작성 및 배포
`web_server.py` 내부의 `StreamManager` 클래스의 프레임 캡처 및 전송 로직을 개선하고, 아래 명령어로 배포 및 모니터링을 진행해 주세요.
```bash
# PM2 재시작
pm2 restart camera-web

# 에러 및 실행 로그 관찰
pm2 logs camera-web
```