RTSP addresses
How an RTSP address is built, what OpticWatch needs from it, and how to fix one that does not connect.
RTSP (Real Time Streaming Protocol) is how an IP camera serves live video over the network. OpticWatch needs one thing from each camera: an RTSP address that delivers video. If a video player such as VLC can play the address from the OpticWatch computer's network, OpticWatch can usually monitor it.
How an RTSP address is built
rtsp://username:[email protected]:554/stream-path| Part | Example | What it is |
|---|---|---|
| Scheme | rtsp:// | Always rtsp://, or rtsps:// for cameras that offer encrypted RTSP. |
| Username and password | username:password@ | A camera account allowed to view the stream. Leave the part out if the camera needs no sign-in. |
| Address | 192.168.1.100 | The camera's IP address, or a hostname the OpticWatch computer can resolve. |
| Port | :554 | The camera's RTSP port. 554 is the standard and is used when the port is left out. |
| Stream path | /stream-path | Which stream to open. It differs between manufacturers, and often between models. |
Finding the stream path
There is no single path that works for every camera. Find yours in the camera's manual, the manufacturer's support site, or the camera's own web interface, usually under network or streaming settings. Many cameras offer more than one stream, such as a main stream and a lower-resolution sub-stream, each with its own path. OpticWatch checks whichever stream address you give it.
If you do not know the path but the camera supports ONVIF, ONVIF setup reads the available streams from the camera and fills in the address for you.
Passwords with special characters
Some characters have a meaning inside an address, so in the username or password they must be written in encoded form. The most common are:
| Character | Write it as |
|---|---|
@ | %40 |
: | %3A |
/ | %2F |
# | %23 |
? | %3F |
% | %25 |
For example, the password p@ss:word is written p%40ss%3Aword, giving rtsp://viewer:p%40ss%[email protected]:554/stream-path.
What OpticWatch does with the address
Each check opens the stream over TCP, confirms it contains a video stream with a codec, resolution and frame rate, and closes it. Nothing is recorded. A healthy camera usually answers in two to three seconds. A check that gets no answer within the camera's Probe timeout (10 seconds by default) counts as failed.
When a check fails
The camera page shows the reason for a failed check in words, with a short code. These are all the reasons OpticWatch reports:
| Reason | What to check |
|---|---|
The RTSP server rejected the supplied credentials.AUTH_FAILED | The username or password is wrong, or contains special characters that are not encoded (see below). Check that the camera account is allowed to view streams. |
The camera refused the connection.CONNECTION_REFUSED | The camera is reachable but nothing accepts RTSP on that port. Check the port number and that RTSP is enabled on the camera. |
The camera could not be reached.CONNECTION_TIMEOUT | No answer from that address. Check the IP address, that the camera is powered and connected, and that no firewall or VLAN blocks the OpticWatch computer from reaching it. |
The camera hostname could not be resolved.DNS_ERROR | The address uses a name the OpticWatch computer cannot look up. Use the camera's IP address, or fix the name in your DNS. |
The camera did not respond before the probe timeout.PROBE_TIMEOUT | The camera answered too slowly. Check its load and network; if it is simply slow to start a stream, raise the camera's probe timeout. |
The endpoint did not provide a usable video stream.NO_VIDEO_STREAM | The address answers but the path is wrong for this camera, or the stream carries no video. Check the stream path for your camera model. |
The RTSP server returned an error.RTSP_ERROR | Often a wrong path. Check the camera's manual for the correct stream path. |
The camera address is not a valid RTSP URL.INVALID_URL | The address must start with rtsp:// or rtsps://. Check for typos and unencoded special characters. |
OpticWatch also refuses addresses that no camera can have, such as multicast addresses and cloud metadata services, and reports ADDRESS_NOT_ALLOWED for them.
Test an address from the OpticWatch computer
To see exactly what the camera answers, run the same tool OpticWatch uses, from inside OpticWatch, in the OpticWatch folder. Replace the address with your camera's, keeping the single quotes:
docker compose exec api ffprobe -rtsp_transport tcp -i 'rtsp://username:[email protected]:554/stream-path'If this shows stream details, the address works. If it shows an error, the message tells you whether the problem is the network, the credentials or the path. The command only reads from the camera and changes nothing. Your terminal keeps a history of typed commands, including the password in this address, so use it on a computer you trust.