# WARA-PS Video Server RTMP API 1.0.4 documentation

* Specification ID: `urn:waraps.api-video-server`
* License: [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
* Default content type: [video/x-flv](https://www.iana.org/assignments/media-types/video/x-flv)
* Support: [waraps.org](https://portal.waraps.org/)
* Email support: [info@waraps.org](mailto:info@waraps.org)

### Overview
The WARA-PS video server receives live video streams and makes those streams available to clients that need to watch an agent camera feed.

The current video server integration uses RTMP. A publisher sends video to the video server using a stream name.

### Quick Start
Two roles share the same stream name -- typically the agent's name: a **publisher** sends RTMP/FLV video to the publish URL (port 1935), and any number of **watchers** connect to the watch URL (port 1936) for that same stream name. See the ffmpeg examples below to try both ends locally.

### RTMP Publish URL

```text
rtmp://ome.waraps.org:1935/app/{stream_name}
```

For agent video, use the agent name as the stream name. Example for `SimUSV1`:

```text
rtmp://ome.waraps.org:1935/app/SimUSV1
```

### RTMP Watch URL

```text
rtmp://ome.waraps.org:1936/app/{stream_name}
```

Example for `SimUSV1`:

```text
rtmp://ome.waraps.org:1936/app/SimUSV1
```

### Publish Video With ffmpeg
Publish a looping MP4 file:

```bash
ffmpeg -stream_loop -1 -re -i demo.mp4 -c:v libx264 -preset veryfast -tune zerolatency -c:a aac -b:a 128k -pix_fmt yuv420p -f flv "rtmp://ome.waraps.org:1935/app/SimUSV1"
```

Publish a generated test pattern when no camera or video file is available:

```bash
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 -f lavfi -i sine=frequency=1000:sample_rate=44100 -c:v libx264 -preset veryfast -tune zerolatency -c:a aac -b:a 128k -pix_fmt yuv420p -f flv "rtmp://ome.waraps.org:1935/app/SimUSV1"
```

### Watch Video
Watch the RTMP stream with ffplay:

```bash
ffplay "rtmp://ome.waraps.org:1936/app/SimUSV1"
```

### Stream Naming
The path after `/app/` is the stream name. For agent video, use the same agent name that identifies the agent in WARA-PS.

## Table of Contents

* [Servers](#servers)
  * [publish](#publish-server)
  * [watch](#watch-server)
* [Operations](#operations)
  * [SEND app/{stream_name}](#send-appstream_name-operation)
  * [RECEIVE app/{stream_name}](#receive-appstream_name-operation)

## Servers

### `publish` Server

* URL: `rtmp://ome.waraps.org:1935/`
* Protocol: `rtmp`

RTMP video server publish endpoint


### `watch` Server

* URL: `rtmp://ome.waraps.org:1936/`
* Protocol: `rtmp`

RTMP video server watch endpoint


## Operations

### SEND `app/{stream_name}` Operation

*Publish a video stream to the video server*

* Operation ID: `publishVideo`

RTMP stream path. Publish to rtmp://ome.waraps.org:1935/app/{stream_name}. Watch from rtmp://ome.waraps.org:1936/app/{stream_name}.

Publish RTMP/FLV video to rtmp://ome.waraps.org:1935/app/{stream_name}.

#### Parameters

| Name | Type | Description | Value | Constraints | Notes |
|---|---|---|---|---|---|
| stream_name | string | Stream name used in the RTMP path. For agent video, use the agent name. | examples (`"SimUSV1"`, `"MiniUAV1"`) | - | **required** |


#### Message Video Stream `video-stream`

* Message ID: `videoStream.message`
* Content type: [video/x-flv](https://www.iana.org/assignments/media-types/video/x-flv)

Continuous RTMP/FLV stream.

##### Payload

| Name | Type | Description | Value | Constraints | Notes |
|---|---|---|---|---|---|
| (root) | string | Continuous RTMP/FLV video stream encoded by the publisher. | - | format (`binary`) | - |

> Examples of payload

_SimUSV1 RTMP publish URL_

Publish SimUSV1 video

```json
"rtmp://ome.waraps.org:1935/app/SimUSV1"
```


_SimUSV1 RTMP watch URL_

Watch SimUSV1 video

```json
"rtmp://ome.waraps.org:1936/app/SimUSV1"
```



### RECEIVE `app/{stream_name}` Operation

*Watch a video stream from the video server*

* Operation ID: `watchVideo`

RTMP stream path. Publish to rtmp://ome.waraps.org:1935/app/{stream_name}. Watch from rtmp://ome.waraps.org:1936/app/{stream_name}.

Watch the RTMP stream with ffplay or another RTMP-capable player using the same stream URL.

#### Parameters

| Name | Type | Description | Value | Constraints | Notes |
|---|---|---|---|---|---|
| stream_name | string | Stream name used in the RTMP path. For agent video, use the agent name. | examples (`"SimUSV1"`, `"MiniUAV1"`) | - | **required** |


#### Message Video Stream `video-stream`

* Message ID: `videoStream.message`
* Content type: [video/x-flv](https://www.iana.org/assignments/media-types/video/x-flv)

Continuous RTMP/FLV stream.

##### Payload

| Name | Type | Description | Value | Constraints | Notes |
|---|---|---|---|---|---|
| (root) | string | Continuous RTMP/FLV video stream encoded by the publisher. | - | format (`binary`) | - |

> Examples of payload

_SimUSV1 RTMP publish URL_

Publish SimUSV1 video

```json
"rtmp://ome.waraps.org:1935/app/SimUSV1"
```


_SimUSV1 RTMP watch URL_

Watch SimUSV1 video

```json
"rtmp://ome.waraps.org:1936/app/SimUSV1"
```