> For the complete documentation index, see [llms.txt](https://docs.giraffecctv.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giraffecctv.com/cloud/api/rtsp-service.md).

# 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="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2Fgit-blob-ac4e77c5ccd7c3ecc04520586444e6eb64248ba2%2Fcloud-api-rtsp-service-overview-diagram-02.svg?alt=media" 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="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2FHMGEie93MvU3lUMwEgdY%2Fimage.png?alt=media&amp;token=60c0ed7f-80b2-4558-9af5-9bc93ec6c6bf" alt="System Auth Token setting" 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

Go to **Settings → Systems**, select the system and open **Cameras**. Open the camera's **Settings**, then its **RTSP** tab to copy the URL for the stream you need.

<figure><img src="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2FlW763BDtvho8ItdUvtsA%2Fimage.png?alt=media&amp;token=29f10d95-a760-4d5f-a03b-b250e2142c90" alt="Camera RTSP tab showing stream URLs" width="526"><figcaption></figcaption></figure>

RTSP URLs contain authentication credentials. Keep copied URLs private and use placeholders when sharing examples or screenshots.

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 -rtsp_transport tcp 'rtsps://system-xxx:token_here@rtsp.onvp.io:322/camera/123/2'
```

{% endcode %}

## 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="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2FttZjt9IiLXv3cMts0hcf%2Fimage.png?alt=media&amp;token=76133160-c539-4633-92e4-cf188ee8eef6" alt="" width="563"><figcaption></figcaption></figure>

Paste the RTSP URL into the **URL** box, then select **Open** to start the stream.

<figure><img src="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2F9MoVjLJJogY819H0iWcQ%2Fimage.png?alt=media&amp;token=154923ae-98b5-44a6-9e24-a1af7533fa50" alt="VLC Open Network dialog with the URL field" width="563"><figcaption></figcaption></figure>

<figure><img src="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2F5jOIdUMhDYwmkFdN5ecs%2Fimage.png?alt=media&amp;token=0a5bfe3f-a4f0-40f4-a6b4-4343389c86fa" 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="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2FGOpzOEde9WVaOWHBkvRY%2Fimage.png?alt=media&amp;token=411ee9dd-32ef-4874-b724-bd7a66c94375" 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 %}

## Stream security

Use **RTSPS** to encrypt the connection between your player or ARC and the Giraffe RTSP proxy. It protects both authentication and video carried over that connection. Use TCP transport and port **322**.

Plain **RTSP** on port **554** does not encrypt this connection. RTSPS protects the client-to-proxy connection; it does not provide camera-to-player end-to-end encryption.

## AWS private link / VPN Tunnel

For private network access to the RTSP proxy, you can use AWS PrivateLink. A single PrivateLink connection can be used for any camera you are authorised to access on the Giraffe platform. Private connectivity is separate from stream encryption; use RTSPS to encrypt the client-to-proxy connection.

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

<figure><img src="https://2701567920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZS3YRsoEs7DBwWBJpaD%2Fuploads%2FHrvYArMKSFLbXYugIpBa%2FRTSP%20Private%20Link%20(1).svg?alt=media&amp;token=0537d131-c2de-4865-96aa-169bb8f85988" 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.
