How to Set a Custom RTSP Stream Address for an ONVIF Profile

A practical guide to overriding the default RTSP stream address of an ONVIF Server profile using the <stream_uri> element. Point a profile to a live camera feed or a third-party media server, control whether encoder parameters are appended, and verify the change with GetStreamUri.

Overview

The ONVIF Server automatically generates an RTSP URL for each media profile. By default, when no <stream_uri> is specified in a profile, the server constructs the RTSP URL automatically using its own IP address and a hardcoded path suffix:

Default RTSP URL
# Standard RTSP
rtsp://<server-ip>:554/test.mp4

# HTTP transport (RtspOverHttp)
http://<server-ip>:80/test.mp4

This default is convenient for local testing, but it always serves the built-in test.mp4 source. To point an ONVIF profile at a specific RTSP stream source — for example a live camera feed, a real-time encoder, or a third-party media server — add a <stream_uri> element inside the <profile> section of the configuration file.

Configuration Files

The <stream_uri> element is supported in both ONVIF Server configuration formats:

File Purpose
onvif.cfg Minimal default configuration.
onvifrun.cfg Full-featured runtime configuration.

Both formats support the <stream_uri> element in the same way.

Step 1: Understand the Syntax

Add a <stream_uri> element inside the <profile> section. The element has one optional attribute and its text content is the complete RTSP URL.

onvif.cfg — Profile with Custom Stream URI
<profile>
    <Name>MyProfile</Name>
    <video_source>
        <width>1280</width>
        <height>720</height>
    </video_source>
    <video_encoder>
        <encoding>H264</encoding>
        <!-- Other encoder settings... -->
    </video_encoder>
    <stream_uri append_params="0">rtsp://192.168.3.27/live</stream_uri>
</profile>

Step 2: Understand the Attributes

Attribute Values Description
append_params 0 or 1 When 1, video/audio encoder parameters are appended as query string parameters (&ve=H264&w=1280&h=720&t=unicast&p=udp). When 0, the URI is used as-is.

Step 3: Common Examples

The text content of the <stream_uri> element is the complete, verbatim RTSP URL. Here are several typical configurations:

stream_uri Examples
<!-- Basic RTSP stream -->
<stream_uri append_params="0">rtsp://192.168.3.27/live</stream_uri>

<!-- RTSP stream with credentials -->
<stream_uri append_params="0">rtsp://admin:pass@10.0.0.5:8554/cam/realmonitor</stream_uri>

<!-- HTTP live stream (e.g. MJPEG) -->
<stream_uri append_params="0">http://192.168.1.100:8080/video.mjpg</stream_uri>

<!-- With encoder params appended -->
<stream_uri append_params="1">rtsp://192.168.3.27/live</stream_uri>

Note: The maximum length of the stream URI is 300 characters.

XML Escaping: Because the configuration file is XML, the & character in a URL must be escaped as &amp;. This commonly occurs when a stream URL already contains query-string parameters (e.g., an RTSP URL that uses ?token=abc&type=live).

Incorrect (the raw & breaks the XML parser):
<stream_uri append_params="0">rtsp://10.0.0.5/live?token=abc&type=live</stream_uri>

Correct (escape & as &amp;):
<stream_uri append_params="0">rtsp://10.0.0.5/live?token=abc&amp;type=live</stream_uri>

The escaped form is decoded back to & when the URI is returned by GetStreamUri.

Step 4: Configure Multiple Profiles with Different Streams

Each <profile> section can have its own <stream_uri>, allowing different profiles to point to different streams. This is useful for exposing HD and SD variants of the same source, or for serving different cameras through a single ONVIF Server.

onvif.cfg — Multiple Profiles with Custom Stream URIs
<profile>
    <Name>HD Stream</Name>
    <video_source><width>1920</width><height>1080</height></video_source>
    <video_encoder><encoding>H264</encoding><!-- Other settings... --></video_encoder>
    <stream_uri append_params="0">rtsp://192.168.3.27/live/hd</stream_uri>
</profile>

<profile>
    <Name>SD Stream</Name>
    <video_source><width>640</width><height>480</height></video_source>
    <video_encoder><encoding>H264</encoding><!-- Other settings... --></video_encoder>
    <stream_uri append_params="0">rtsp://192.168.3.27/live/sd</stream_uri>
</profile>

Step 5: Verify the Change

After modifying the configuration, restart the ONVIF Server. Then call GetStreamUri with the corresponding profile token to confirm that the custom stream address is returned.

Request (simplified)

GetStreamUri Request
<trt:GetStreamUri>
    <trt:StreamSetup>
        <tt:Stream>RTP-Unicast</tt:Stream>
        <tt:Transport><tt:Protocol>UDP</tt:Protocol></tt:Transport>
    </trt:StreamSetup>
    <trt:ProfileToken>ProfileToken_1</trt:ProfileToken>
</trt:GetStreamUri>

Response

GetStreamUri Response
<trt:MediaUri>
    <tt:Uri>rtsp://192.168.3.27/live</tt:Uri>
    <tt:InvalidAfterConnect>false</tt:InvalidAfterConnect>
    <tt:InvalidAfterReboot>false</tt:InvalidAfterReboot>
    <tt:Timeout>PT1M</tt:Timeout>
</trt:MediaUri>

The <tt:Uri> in the response should match the custom <stream_uri> you configured.

Troubleshooting

Issue Possible Cause Resolution
GetStreamUri returns the default rtsp://<server-ip>:554/test.mp4 The <stream_uri> element is not inside the <profile>, or the configuration was not reloaded. Verify the element is nested inside the correct <profile> block. Restart the ONVIF Server after editing the configuration.
Video fails to play after pointing to a custom stream The custom stream URL is unreachable, requires credentials that are missing, or contains an unsupported codec. Test the stream URL directly with VLC or ffplay. If the source requires authentication, embed credentials in the URL (e.g., rtsp://admin:pass@host/path). Confirm the codec is supported.
URI appears truncated or malformed The stream URI exceeds the 300-character maximum length. Shorten the URL or use a shorter path on the source server. Verify the URL has no spaces or XML-special characters (escape & as &amp;).
Encoder query parameters not appearing in the returned URI append_params is set to 0. Set append_params="1" on the <stream_uri> element to append &ve=H264&w=1280&h=720&t=unicast&p=udp.

Best Practices

  • Use append_params="0" by Default: Keep the URI verbatim unless the target media server specifically needs encoder parameters. Some servers reject URLs containing unexpected query strings.
  • Embed Credentials in the URL: If the source stream requires authentication, include the credentials directly in the URL (rtsp://user:pass@host:port/path) to avoid separate authentication configuration.
  • Give Profiles Descriptive Names: Use meaningful <Name> values (e.g., "HD Stream", "SD Stream", "Front Entrance") so the custom URIs are easy to identify from the profile token mapping.
  • Test the URL Independently: Before configuring it in the ONVIF Server, validate the stream URL with a generic RTSP client (VLC, ffplay). If the source cannot play there, it will not play through the ONVIF Server either.
  • Keep URLs Short and Clean: Stay well under the 300-character limit. Avoid spaces and XML-special characters in the URL; escape them if necessary.
  • Verify After Restart: Always restart the ONVIF Server after editing the configuration and confirm the change with GetStreamUri before relying on the new address.