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 a specific release, use the drop-down menu on the left.

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 usage. The underlying multimedia.rtsp_server object can also be used when the application manages the encoder and media sending itself.

The path of the example script in the development board firmware is /sdcard/examples/02-Media/rtsp_server.py, and the SDK source path is src/canmv/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. It is recommended to use libs.Network to complete interface selection and set the default uplink.

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 aligned 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	GOP frame count	30

When video_type is not H.264/H.265, or 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 port binding and Session creation return status, 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 link, 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 example below uses low-bitrate H.265; if the client does not support H.265, you can switch to H.264.

import multimedia as mm
from libs.Network import connect_network
from media.rtspserver import RtspServer

# Only the LAN configuration is shown here; for Wi-Fi connection, see /sdcard/examples/02-Media/rtsp_server.py.
lan, ip = connect_network("lan")

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 so clients can connect.
finally:
    if started:
        server.stop()

Audio and Compatibility

By default enable_audio=False. The bundled RtspServer wrapper and example only establish the video capture, encoding, and transmission pipeline; merely setting enable_audio to True will not automatically capture or transmit audio.

H.265 is generally more efficient at low bitrates, but has weaker compatibility with some RTSP clients. For better 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 resolution is usually more effective than only reducing bitrate; for example, you can choose 640 x 360 or 800 x 480 on weaker networks.

• A shorter gop_len can reduce the time new clients wait for a key frame, but increases key-frame overhead. For real-time low-bitrate scenarios, typically keep it 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 use the native RTSP object directly:

import multimedia as mm

server = mm.rtsp_server()

The constructor already creates the object; there is usually no need to call rtspserver_create() again. All methods that take 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 at the underlying level.
rtspserver_getrtspurl(name)	str	Returns the Session’s RTSP URL; throws 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 workflow 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 obtaining 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 in 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 output of the VENC or audio encoder. The native RTSP service is not responsible for PCM or raw image encoding. New video clients typically need to receive parameter sets and key frames before they can start decoding; H.264 requires SPS/PPS, and H.265 requires VPS/SPS/PPS.

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

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