Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

RTSP Module API Manual

Overview

media.rtspserver.RtspServer provides a high-level wrapper for Sensor -> VENC -> RTSP. The current default configuration is H.265, 1280 x 720, 512 Kbit/s, with audio disabled, to reduce encoding and network resource consumption. The underlying multimedia.rtsp_server object can also be used by the application to manage the encoder and media sending itself.

The example script is located at resources/examples/02-Media/rtsp_server.py. It includes the same camera streaming mode as the high-level wrapper, and adds LAN/Wi-Fi configuration, error checking, and configurable parameters.

Important

The RTSP service itself is not responsible for networking. Before calling start(), the application must first connect to LAN, Wi-Fi STA, or Wi-Fi AP, and select the corresponding default network device.

RtspServer

Constructor

from media.rtspserver import RtspServer
import multimedia as mm

server = RtspServer(
    session_name="test",
    port=8554,
    video_type=mm.multi_media_type.media_h265,
    enable_audio=False,
    width=1280,
    height=720,
    bit_rate=512,
    gop_len=30,
)

Parameter	Description	Default
session_name	RTSP session name, also the URL path	"test"
port	RTSP listening port	8554
video_type	mm.multi_media_type.media_h265 or media_h264	media_h265
enable_audio	Declare audio in the RTSP Session	False
width	Encoding width; automatically rounded up to 16 internally	1280
height	Encoding height	720
bit_rate	VENC CBR target bit rate, in Kbit/s, range 100 to 20000	512
gop_len	Number of frames in a GOP	30

When video_type is not H.264/H.265, or when bit_rate is out of range, the constructor raises ValueError.

start()

server.start()

Initializes the RTSP service and Session, creates the Sensor/VENC pipeline, starts encoding, and sends video in a background thread. When you need to directly check the return status of port binding and Session creation, use the multimedia.rtsp_server API below, or use the RtspServer class in the accompanying example.

stop()

server.stop()

Stops the background streaming thread, stops VENC and Sensor, destroys the media pipeline, and closes the RTSP service. This method should be called before the application exits to release hardware resources.

get_rtsp_url()

url = server.get_rtsp_url()

Returns the RTSP URL of the current session. For example, when the network address is 192.168.1.108, the default URL is:

rtsp://192.168.1.108:8554/test

Usage Example

The following example uses low bit rate H.265; if the client does not support H.265, you can switch to H.264.

import network
import multimedia as mm
from media.rtspserver import RtspServer

# Only showing LAN configuration; see resources/examples/02-Media/rtsp_server.py for Wi-Fi connection method.
lan = network.LAN()
lan.ifconfig("dhcp")
network.set_default_dev("u0")

server = RtspServer(
    session_name="camera",
    video_type=mm.multi_media_type.media_h265,
    width=1280,
    height=720,
    bit_rate=512,
    gop_len=30,
)

started = False
try:
    server.start()
    started = True
    print(server.get_rtsp_url())
    # Keep the script running and clients can connect.
finally:
    if started:
        server.stop()

Audio and Compatibility

The default is enable_audio=False. The accompanying RtspServer wrapper and example only set up the video capture, encoding, and sending pipeline; simply setting enable_audio to True will not automatically capture or send audio.

H.265 is generally more efficient at low bit rates, but some RTSP clients have weaker compatibility. When prioritizing compatibility with VLC, older NVRs, or browser plugins, you can use:

video_type=mm.multi_media_type.media_h264

Performance Recommendations

• 512 Kbit/s is suitable for the default preview and resource-constrained scenarios. For higher image quality, gradually increase bit_rate while observing the encoding and Wi-Fi load.

• Reducing the resolution is usually more effective than just reducing the bit rate; for example, you can choose 640 x 360 or 800 x 480 when the network is weak.

• A shorter gop_len can shorten the wait time for key frames for new clients, but it increases the key frame overhead. For real-time low bit rate scenarios, it is usually kept at 30; when building your own VENC streaming pipeline, you can combine it with Encoder.RequestIDR() to shorten the first frame wait.

Underlying multimedia.rtsp_server API

When you need to manage the camera, VENC, or audio yourself, you can directly use the native RTSP object:

import multimedia as mm

server = mm.rtsp_server()

The constructor has already created the object; usually there is no need to call rtspserver_create() again. All methods with session_name use the name specified when the Session was created.

Lifecycle

Method	Return Value	Description
rtspserver_init(port)	Status code	Initializes and listens on the RTSP port. 0 indicates success.
rtspserver_createsession(name, video_type, enable_audio)	Status code	Creates an RTSP Session; video_type uses mm.multi_media_type.media_h264, media_h265, or other types supported by the underlying layer.
rtspserver_getrtspurl(name)	str	Returns the RTSP URL of the Session; raises RuntimeError if the Session does not exist.
rtspserver_start()	None	Starts the RTSP service.
rtspserver_stop()	None	Stops the RTSP service.
rtspserver_destroysession(name)	Status code	Destroys the specified Session.
rtspserver_deinit()	None	Deinitializes the service.
rtspserver_destroy()	None	Releases the object; safe to call repeatedly.

A typical manual flow is as follows:

import multimedia as mm

session = "camera"
server = mm.rtsp_server()
if server.rtspserver_init(8554) != 0:
    raise RuntimeError("RTSP port bind failed")
if server.rtspserver_createsession(
        session, mm.multi_media_type.media_h265, False) != 0:
    server.rtspserver_deinit()
    raise RuntimeError("RTSP session creation failed")

try:
    server.rtspserver_start()
    print(server.rtspserver_getrtspurl(session))
    # After getting encoded data from VENC, call rtspserver_sendvideodata().
finally:
    server.rtspserver_stop()
    server.rtspserver_deinit()
    server.rtspserver_destroy()

Media Sending

Method	Return Value	Description
rtspserver_sendvideodata(name, data, size, timestamp)	Status code	Sends encoded video data from memory.
rtspserver_sendaudiodata(name, data, size, timestamp)	Status code	Sends encoded audio data.
rtspserver_sendvideodata_byphyaddr(name, phy_addr, size, timestamp)	Status code	Sends encoded video data from a physical address.
rtspserver_sendaudiodata_byphyaddr(name, phy_addr, size, timestamp)	Status code	Sends encoded audio data from a physical address.

data/phy_addr, size, and timestamp must match the VENC or audio encoder output. The native RTSP service is not responsible for PCM or raw image encoding. New video clients usually need to receive the parameter set and key frame to start decoding; H.264 requires SPS/PPS, H.265 requires VPS/SPS/PPS.

The high-level RtspServer and accompanying rtsp_server.py example only set up the video capture, encoding, and sending pipeline. Although the underlying API supports rtspserver_sendaudiodata(), the application must implement audio capture, encoding, and timestamp management itself.

For information about underlying encoding parameters and IDR requests, please refer to the VENC Module API.