> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/services/rtsp-simulator.md).

# RTSP 시뮬레이터

카메라 없이 추론 파이프라인을 테스트할 수 있도록 업로드한 비디오 파일을 루프되는 RTSP 소스로 스트리밍합니다.

RTSP Simulator는 업로드한 동영상 파일을 실시간 RTSP 스트림으로 변환하는 엣지 컨테이너 서비스입니다. 실제 카메라를 설치하기 전에 디바이스에서 추론 파이프라인을 구축하고 테스트하거나, 알려진 클립을 Workflow에 다시 재생할 때 사용할 수 있습니다.

웹 인터페이스나 REST API를 통해 `.mp4` 파일을 업로드하거나 Deployment Manager에서 파일을 업로드할 수 있습니다. 서비스는 파일을 RTSP 호환 형식으로 트랜스코딩하고, 중지할 때까지 계속 반복 재생하여 결과를 스트리밍합니다.

{% hint style="info" %}
RTSP Simulator는 Enterprise 고객 전용으로 제공됩니다. [자세한 내용은 Roboflow 영업팀에 문의하세요.](https://roboflow.com/sales) 자세히 알아보세요.
{% endhint %}

## 연결 정보

다음 항목을 `<device-ip>` Deployment Manager의 디바이스 페이지에 표시된 IP 주소로 바꾸세요.

<table data-search="false"><thead><tr><th>용도</th><th>주소</th></tr></thead><tbody><tr><td>RTSP 스트림</td><td><code>rtsp://&#x3C;device-ip>:8554/stream</code></td></tr><tr><td>웹 UI, REST API 및 Swagger 문서</td><td><code>http://&#x3C;device-ip>:8080</code></td></tr></tbody></table>

<table data-search="false"><thead><tr><th>포트</th><th>프로토콜</th><th>용도</th></tr></thead><tbody><tr><td>8080</td><td>HTTP</td><td>웹 UI, REST API 및 Swagger 문서는 다음 위치에 있습니다: <code>/docs</code></td></tr><tr><td>8554</td><td>RTSP(TCP)</td><td>비디오 스트림 출력입니다. UDP 전송은 비활성화되어 있으며, UDP를 선호하는 클라이언트는 TCP 인터리브 방식으로 전환해 협상합니다.</td></tr></tbody></table>

여러 클라이언트가 동시에 스트림을 읽을 수 있습니다.

## 비디오 형식

웹 UI, CLI 및 API는 `.mp4` 파일만 허용합니다. 업로드된 파일은 모든 RTSP 클라이언트에서 스트림을 사용할 수 있도록 자동으로 트랜스코딩됩니다.

* 코덱: H.264, Baseline 프로파일
* 픽셀 형식: yuv420p
* 오디오: 제거됨, 비디오만
* 최대 파일 크기: 기본값 5GB

## Roboflow 동영상 사용

로컬 네트워크에서 디바이스에 연결할 수 없는 경우 Deployment Manager에서 동영상을 설정하세요. 디바이스가 동영상을 다운로드해 스트리밍합니다.

{% stepper %}
{% step %}

## 설정 열기

디바이스의 Configuration 탭에서 RTSP Simulator 카드의 "Configure"(톱니바퀴 아이콘)를 선택합니다.
{% endstep %}

{% step %}

## 업로드

"Video source"에서 "Roboflow video"를 선택한 다음, "Upload Video"를 선택하고 `.mp4` 또는 `.mov` 파일을 선택합니다. 동영상은 Workspace의 Asset Library에 저장됩니다.
{% endstep %}

{% step %}

## 저장

필요한 경우 변환 및 스트리밍 설정을 변경하세요. 사이트가 Secure Gateway를 통해 Roboflow에 연결되는 경우, "Secure Gateway (optional)"에 주소를 입력합니다. 창에서 "Save Configuration"을 선택한 다음 Configuration 탭에서 "Save Configuration"을 선택합니다. 디바이스가 새 구성을 적용하면 RTSP Simulator 서비스를 재시작하고, 동영상을 다운로드한 뒤 스트리밍을 시작합니다.
{% endstep %}
{% endstepper %}

동영상을 설정하고 Stream이 시뮬레이터를 가리키도록 한 번에 설정하려면 Add Stream 양식에서 [테스트 동영상을 스트리밍하세요.](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/setting-up/stream-a-test-video.md) 디바이스에 시뮬레이터가 없는 경우 이 작업으로 시뮬레이터도 추가됩니다.

카드에는 동영상 이름, RTSP URL, 다운로드 및 스트리밍 상태가 표시됩니다. Roboflow 동영상이 설정되어 있는 동안 로컬 웹 UI에 "Managed from Roboflow"가 표시되고, 로컬 웹 UI와 CLI 제어 기능이 잠기며, `/upload`, `/play`, `/stop`, `/delete`및 `POST /stream-settings` 은 다음을 반환합니다: `409`. 로컬 업로드로 돌아가려면 "로컬 업로드"를 선택하고 저장하세요.

## 웹 인터페이스 사용

브라우저에서 `http://<device-ip>:8080` 을 엽니다.

{% stepper %}
{% step %}

## 업로드

페이지로 `.mp4` 파일을 드래그하세요. 파일이 업로드되고 스트리밍 형식으로 변환됩니다.
{% endstep %}

{% step %}

## 재생

"재생"을 선택하면 스트리밍이 시작됩니다. 동영상이 무한 반복되며 RTSP 서버에 게시됩니다.
{% endstep %}

{% step %}

## 연결

추론 파이프라인, Deployment Manager 스트림 또는 RTSP 클라이언트에서 다음 주소로 연결하세요: `rtsp://<device-ip>:8554/stream`.
{% endstep %}

{% step %}

## 중지

"중지"를 선택하면 스트림이 종료되고 업로드된 동영상이 삭제됩니다.
{% endstep %}
{% endstepper %}

배포에서 시뮬레이션된 스트림을 사용하려면 카메라를 추가하는 것과 같은 방식으로 디바이스에 스트림 소스로 추가하세요. 다음을 참조하세요: [스트림 추가](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/setting-up/add-a-stream.md).

## CLI 사용

헤드리스 환경이나 SSH 전용 환경에서는 `rtsp-cli` 도구가 디바이스에서 대화형 터미널 인터페이스를 제공합니다.

```bash
docker exec -it rtsp-simulator rtsp-cli
```

웹 UI 없이 동영상을 가져오려면 먼저 입력 디렉터리에 동영상을 복사한 다음 CLI를 실행하고 다음 키를 누르세요: `I`.

```bash
scp video.mp4 user@<device-ip>:/var/lib/rfdm/rtsp-simulator/data/input/
```

<table data-search="false"><thead><tr><th>키</th><th>명령</th><th>설명</th></tr></thead><tbody><tr><td><code>I</code></td><td>가져오기</td><td>다음 디렉터리에서 동영상을 선택하고 변환합니다: <code>/data/input/</code></td></tr><tr><td><code>P</code></td><td>재생</td><td>RTSP 스트리밍 시작</td></tr><tr><td><code>S</code></td><td>중지</td><td>스트리밍을 중지하고 변환된 파일 삭제</td></tr><tr><td><code>D</code></td><td>삭제</td><td>동영상 파일 삭제</td></tr><tr><td><code>C</code></td><td>설정</td><td>스트림 설정 조정(비트 전송률, 버퍼, 지연)</td></tr><tr><td><code>R</code></td><td>새로고침</td><td>상태 표시 새로 고침</td></tr><tr><td><code>Q</code></td><td>종료</td><td>CLI 종료</td></tr></tbody></table>

## 스트림 테스트

스트림이 실시간으로 전송되는지 확인하려면 RTSP 플레이어를 사용해 연결하세요.

{% tabs %}
{% tab title="VLC" %}

```bash
vlc rtsp://<device-ip>:8554/stream
```

{% endtab %}

{% tab title="ffplay" %}
스트림은 TCP로만 제공되므로, ffplay가 UDP를 먼저 시도하도록 두지 말고 TCP 전송을 강제하세요.

```bash
ffplay -rtsp_transport tcp rtsp://<device-ip>:8554/stream
```

{% endtab %}
{% endtabs %}

## HTTP API

모든 엔드포인트는 JSON을 반환합니다. 대화형 Swagger 문서는 다음 주소에서 제공합니다. `http://<device-ip>:8080/docs`. 모든 온디바이스 서비스 API에 공통으로 적용되는 규칙은 [서비스](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/services.md#using-the-apis) 를 참조하세요.

{% hint style="warning" %}
이 API에는 인증이 없으며, 실행 중인 스트림을 중지하고 업로드된 동영상을 삭제할 수 있습니다. 8080 포트에 접근할 수 있는 모든 대상이 이 두 작업을 수행할 수 있습니다.
{% endhint %}

### 일반적인 흐름

다음 경로를 사용해 동영상을 업로드하고 `/upload`다음 경로로 스트림을 시작한 뒤 `/play`다음 경로로 상태를 확인하고 `/status`다음 경로로 스트림을 중지합니다. `/stop`.

{% hint style="warning" %}
/play `/status` 에서 반환되는 `rtsp_url` 및 `/play` 는 항상 `localhost`를 가리킵니다. 서비스가 자체 관점에서 URL을 보고하기 때문입니다. 기기에서 실행되는 소비자만 이 URL을 그대로 사용할 수 있습니다. 다른 곳에서는 기기 주소로 바꾸세요: `rtsp://<device-ip>:8554/stream`.

포트는 `RTSP_PORT`이며, 기본값은 `8554` 이지만 기기별로 설정할 수 있습니다. 기본값이라고 가정하지 말고 `rtsp_port` 값을 `/info` 에서 확인하세요.
{% endhint %}

`/stop` 은 디스크 공간을 확보하기 위해 원본 파일과 변환된 파일도 모두 삭제하므로, 다음에 `/play`.

### 업로드

를 실행하기 전에 새로 업로드해야 합니다. 지원되는 형식은 `.mp4` 도 허용되며, 업로드가 시작되기 전에 실행 중인 스트림이 중지됩니다. 선택적 `settings` 부분은 트랜스코딩 중 적용되는 변환 설정을 담은 JSON 문자열입니다. 변환된 파일에 설정이 반영되므로 나중에 설정을 변경하려면 다시 업로드해야 합니다.

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/upload" method="post" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

### 스트리밍

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/play" method="post" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/stop" method="post" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

`/delete` 는 스트림 실행 여부와 관계없이 동영상 파일을 삭제하며, 스트림이 실행 중이면 먼저 중지합니다.

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/delete" method="post" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

### 상태

`streaming` 은 `components.mediamtx.healthy` (스트리밍 서버)와 `components.ffmpeg_process.running` (트랜스코딩 및 게시 프로세스)가 모두 true일 때 true입니다. `components.stream` 항목은 이 상태의 조건이 아닙니다. `components.stream.source_ready` 는 시작 중에 잠시 false일 수 있으며, 이때 `streaming` 가 이미 true로 표시되는 것은 정상입니다. 구성 요소별 상태를 확인하면 스트림 오류가 발생한 부분을 가장 빠르게 찾을 수 있습니다. 무엇이든 다시 시작하기 전에 `components` 를 확인해 어느 부분에 문제가 있는지 살펴보세요.

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/status" method="get" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

`/info` 는 사용 가능한 디스크 공간과 최대 업로드 크기를 포함해 서비스가 실행 중인 제한을 표시합니다. 대용량 파일을 업로드하기 전에 확인하는 것이 좋습니다.

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/info" method="get" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

### 스트림 설정 엔드포인트

재생 설정은 업로드 설정과 다릅니다. 스트리밍 시 적용되며, 다시 업로드하지 않아도 세션 간에 변경할 수 있습니다. 설정을 업데이트하면 현재 실행 중인 스트림이 아니라 다음 `/play`부터 적용됩니다.

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/stream-settings" method="get" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/a3f00c5f2efc8e280da1039b61807567944d8671" path="/stream-settings" method="post" %}
[edge-rtsp-simulator.yaml](https://1826078061-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-1608d6873191fab7e4d614a21aa77a56bab11279%2Fedge-rtsp-simulator.yaml?alt=media)
{% endopenapi %}

## 구성

### 환경 변수

기기의 Configuration 탭에서 서비스에 다음 값을 설정하세요. 자세한 내용은 [기기 구성 업데이트](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager/making-changes/update-device-configuration.md).

<table data-search="false"><thead><tr><th>변수</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td><code>MAX_FILE_SIZE</code></td><td><code>5368709120</code></td><td>최대 업로드 크기(바이트 단위, 5GB)</td></tr><tr><td><code>RTSP_PORT</code></td><td><code>8554</code></td><td>RTSP 서버 포트</td></tr><tr><td><code>WEB_PORT</code></td><td><code>8080</code></td><td>웹 UI 및 API 포트</td></tr><tr><td><code>LOG_LEVEL</code></td><td><code>INFO</code></td><td>로그 상세 수준: <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>또는 <code>ERROR</code></td></tr></tbody></table>

### 업로드 설정

이 설정은 변환 중에 적용되므로 변경하려면 동영상을 다시 업로드해야 합니다.

<table data-search="false"><thead><tr><th>설정</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td><code>target_fps</code></td><td>원본</td><td>목표 프레임 속도(1~120). 원본을 유지하려면 생략하세요</td></tr><tr><td><code>crf_quality</code></td><td><code>23</code></td><td>품질 수준(0~51, 18은 높음, 23은 중간, 28은 낮음)</td></tr><tr><td><code>max_width</code></td><td>원본</td><td>다운스케일링 시 최대 너비(320~7680). 원본을 유지하려면 생략하세요</td></tr></tbody></table>

### 스트림 설정

이 설정은 재생 중에 적용되며, CLI 설정 메뉴 또는 다음 `/stream-settings` 엔드포인트를 통해 스트리밍 세션 간에 변경할 수 있습니다.

<table data-search="false"><thead><tr><th>설정</th><th>기본값</th><th>설명</th></tr></thead><tbody><tr><td><code>max_bitrate_kbps</code></td><td><code>5000</code></td><td>최대 비트 전송률(kbps, 100~100,000)</td></tr><tr><td><code>buffer_size_kb</code></td><td><code>3000</code></td><td>버퍼 크기(KB, 100~50,000)</td></tr><tr><td><code>max_delay_ms</code></td><td><code>500</code></td><td>최대 지연 시간(밀리초, 50~5,000)</td></tr></tbody></table>
