# RTSP Service

The Giraffe platform makes it straightforward to pull secure RTSP streams from the cameras without any port forwarding or static IP required.

## Overview

<figure><img src="/files/g0hiI2ot2TLNsYyqj4Rj" alt=""><figcaption></figcaption></figure>

## How to setup RTSP urls

Very little configuration is required to setup RTSP streaming for a device with a Giraffe Edge Controller.

#### Ensure the system auth token is enabled

In order to use the RTSP URLs from an Edge Controller, you must first enable the System Auth Token. This can be found on the **Settings** tab of the System Overview page.

<figure><img src="/files/M1aV37CgxbLljP6QwfKs" alt="" width="563"><figcaption></figcaption></figure>

The token is used to authenticate the RTSP request. If the token is changed, it will be necessary to update the RTSP URL.

An API key with the correct permissions can also be used to authenticate the RTSP request.

You must always provide the system ID as the 'username' part of the URL and the token as the 'password' part. The format of the 'username' part must be `system-xxx`where `xxx`is replaced by the system ID.

#### Get the RTSP urls

The RTSP URLs can be found on the individual camera pages. Each camera has both a HD and an SD stream available in both secure and insecure format.

<figure><img src="/files/WyQV4xd0BCVOJYeEMKmW" alt="" width="526"><figcaption></figcaption></figure>

Streams are proxied directly from the cameras and the encoding is not changed.

## Testing with FFmpeg

In order to test secure RTSP we recommend using FFmpeg.

Once you have FFmpeg installed on your system, run the following command in a terminal. Replace the RTSP URL with the one for your camera with the correct API key.

{% code overflow="wrap" %}

```
ffplay rtsps://system-xxx:token_here@rtsp.onvp.io/camera/123/2
```

{% endcode %}

<figure><img src="/files/QVx923KkP3I8kenWgwrM" alt="" width="563"><figcaption></figcaption></figure>

## Testing with VLC

In order to test the RTSP URLs, you can use a program like VLC Media Player.

{% hint style="info" %}
Please note that VLC media player does not support secure RTSP streams. Please use FFmpeg or Gstreamer instead.
{% endhint %}

Open VLC Media player, and then select **File** -> **Open Network**

<figure><img src="/files/uEWeqYCZylqwoVgnIw8I" alt="" width="563"><figcaption></figcaption></figure>

Enter the RTSP URL into the **URL** box:

<figure><img src="/files/hi2BsBYVeeQMLXoJrkBr" alt="" width="563"><figcaption></figcaption></figure>

When you select **Open** the stream should start to play:

<figure><img src="/files/i3oFj8PSUzV7KONBqbCG" alt="" width="563"><figcaption></figcaption></figure>

## Viewing RTSP session history

You can view all RTSP sessions for a camera on the RTSP tab:

<figure><img src="/files/moy64tpNdQ786nREPHLf" alt="" width="563"><figcaption></figcaption></figure>

* The Client ID is a unique identifier for each session. Every new RTSP session will have a different Client ID.
* The Client IP is the IP address of the RTSP client trying to view the stream. It will typically show the public IP address of the client. If you are coming via a Private Link, it will show a private IP address from one of our Network Load Balancers.
* The Status is either *Active*, *Ending* or *Ended*. The status will be *Ending* after you have pressed the End button, but before the stream has actually terminated.
* The Start and End columns show the timestamps when the stream started and ended. The Duration columns shows the total time for which the stream was being played for.
* The Data Transferred column shows how many bytes the RTSP service sent to the client in total. Please note - it does not include any bytes that may have been sent from the client back to the RTSP service, and there will be a little network / protocol overhead on top.
* The Proxy Host shows which of our RTSP servers the stream was coming from.
* If a stream is currently Active, you can terminate it by pressing the End button. Be aware that it may take up to 30 seconds before the stream terminates.

{% hint style="danger" %}
In order to prevent a client from immediately connecting again after you end their current session, it is important to reset the System Auth Token to a different value. If you don't do this, the client will be able to immediately reconnect again after you end their session.
{% endhint %}

## AWS private link / VPN Tunnel

The public RTSP URLs do not support encryption. RTSP is by it's very nature an insecure protocol and there is no mechanism to encrypt the RTP packets that carry the video frames. RTSPS only protects the authentication handshake during session setup.

If you want the communication to be encrypted end to end, you can connect to the RTSP proxy service via an AWS Private Link. A single Private Link connection can be used for any camera on the Giraffe Platform.

Private Link connections are multiplexed in the same way as normal streams and use the same authentication method.

<figure><img src="/files/3XPWQR6PRUpYlnX7VxeL" alt=""><figcaption></figcaption></figure>

In order to setup an AWS Private Link connection, please contact us. We have to manually configure the Private Link on our side. We will need to know the ID of your AWS account you want the Private Link to be terminated in.

You have complete control of the Private Link endpoint on your side and can configure the IP addressing as you see fit. The Private Link is a NAT device so there are no risks with overlapping IP ranges. Please see the [AWS Private Link](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) docs for more details.

If you do not have an AWS account but want to benefit from a VPN tunnel back to your infrastructure, please contact us. We can help you with the setup required at minimal cost.

## Troubleshooting

#### Authentication errors

If you are getting authentication errors, or a message pop up asking you to enter a password, please double check that the URL you are using is correct. Be aware that the URL will change if you regenerate the system auth token.

Also be aware that if a camera is replaced or moved to a different system, the URL will change (because the RTSP contains the camera unique ID in it).

If the Edge Controller is replaced, the URL will not change because it is based on the System ID.

#### RTSP redirects

The RTSP proxy service makes use of 302 Redirects in order to redirect clients to the correct server in order to multiplex the stream. Your RTSP client must support following redirects.

If your client doesn't support redirects, you can try using the `?redirect=false` parameter appended to the end of the URL. This will force the system into proxy mode rather than issuing a redirect.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giraffecctv.com/cloud/api/rtsp-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.