注意

这是最新开发分支配套的文档，可能包含已发布版本中尚未提供的功能。如果您要查看特定版本的文档，请使用左侧的下拉菜单并选择所需要的版本。

RTSP 模块 API 手册

概述

media.rtspserver.RtspServer 提供 Sensor -> VENC -> RTSP 的高层封装。当前默认配置为 H.265、1280 x 720、512 Kbit/s，音频关闭，以降低编码和网络资源占用。底层 multimedia.rtsp_server 对象也可用于由应用自行管理编码器和媒体发送。

示例脚本位于 resources/examples/02-Media/rtsp_server.py。它包含与高层封装相同的摄像头推流模式，并增加了 LAN/Wi-Fi 配置、错误检查和可配置参数。

重要

RTSP 服务本身不负责联网。调用 start() 前，应用必须先连接 LAN、Wi-Fi STA 或 Wi-Fi AP，并选择对应的默认网络设备。

RtspServer

构造函数

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,
)

参数	含义	默认值
session_name	RTSP 会话名称，也是 URL 路径	"test"
port	RTSP 监听端口	8554
video_type	mm.multi_media_type.media_h265 或 media_h264	media_h265
enable_audio	在 RTSP Session 中声明音频	False
width	编码宽度；内部自动向上按 16 对齐	1280
height	编码高度	720
bit_rate	VENC CBR 目标码率，单位 Kbit/s，范围 100 到 20000	512
gop_len	GOP 帧数	30

当 video_type 不是 H.264/H.265，或 bit_rate 超出范围时，构造函数抛出 ValueError。

start()

server.start()

初始化 RTSP 服务和 Session，创建 Sensor/VENC 管道，启动编码并在后台线程中发送视频。需要直接检查端口绑定和 Session 创建的返回状态时，请使用下方的 multimedia.rtsp_server API，或使用随附示例的 RtspServer 类。

stop()

server.stop()

停止后台推流线程，停止 VENC 和 Sensor，销毁媒体链路并关闭 RTSP 服务。应用退出前应调用该方法释放硬件资源。

get_rtsp_url()

url = server.get_rtsp_url()

返回当前会话的 RTSP URL。例如，网络地址为 192.168.1.108 时，默认 URL 是：

rtsp://192.168.1.108:8554/test

使用示例

以下示例使用低码率 H.265；如果客户端不支持 H.265，可切换为 H.264。

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

# 仅展示 LAN 配置；Wi-Fi 连接方式见 resources/examples/02-Media/rtsp_server.py。
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())
    # 保持脚本运行，客户端即可连接。
finally:
    if started:
        server.stop()

音频和兼容性

默认 enable_audio=False。随附的 RtspServer 封装和示例只建立视频采集、编码和发送链路；仅把 enable_audio 设为 True 不会自动采集或发送音频。

H.265 在低码率下通常效率更高，但部分 RTSP 客户端的兼容性较弱。优先兼容 VLC、旧 NVR 或浏览器插件时，可使用：

video_type=mm.multi_media_type.media_h264

性能建议

• 512 Kbit/s 适合默认的预览和资源受限场景。更高画质应逐步增大 bit_rate，同时观察编码和 Wi-Fi 负载。

• 降低分辨率通常比只降低码率更有效；例如网络较弱时可选择 640 x 360 或 800 x 480。

• 较短的 gop_len 可以缩短新客户端等待关键帧的时间，但会增加关键帧开销。实时低码率场景通常保持 30；自行搭建 VENC 推流链路时，可结合 Encoder.RequestIDR() 缩短首帧等待。

底层 multimedia.rtsp_server API

需要自行管理摄像头、VENC 或音频时，可直接使用原生 RTSP 对象：

import multimedia as mm

server = mm.rtsp_server()

构造函数已经创建对象；通常不需要再调用 rtspserver_create()。所有带 session_name 的方法都使用创建 Session 时指定的名称。

生命周期

方法	返回值	说明
rtspserver_init(port)	状态码	初始化并监听 RTSP 端口。0 表示成功。
rtspserver_createsession(name, video_type, enable_audio)	状态码	创建 RTSP Session；video_type 使用 mm.multi_media_type.media_h264、media_h265 或底层支持的类型。
rtspserver_getrtspurl(name)	str	返回 Session 的 RTSP URL；Session 不存在时抛出 RuntimeError。
rtspserver_start()	无	开始 RTSP 服务。
rtspserver_stop()	无	停止 RTSP 服务。
rtspserver_destroysession(name)	状态码	销毁指定 Session。
rtspserver_deinit()	无	反初始化服务。
rtspserver_destroy()	无	释放对象；重复调用安全。

典型的手动流程如下：

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))
    # 从 VENC 取得已编码数据后调用 rtspserver_sendvideodata()。
finally:
    server.rtspserver_stop()
    server.rtspserver_deinit()
    server.rtspserver_destroy()

媒体发送

方法	返回值	说明
rtspserver_sendvideodata(name, data, size, timestamp)	状态码	发送内存中的已编码视频数据。
rtspserver_sendaudiodata(name, data, size, timestamp)	状态码	发送已编码音频数据。
rtspserver_sendvideodata_byphyaddr(name, phy_addr, size, timestamp)	状态码	从物理地址发送已编码视频数据。
rtspserver_sendaudiodata_byphyaddr(name, phy_addr, size, timestamp)	状态码	从物理地址发送已编码音频数据。

data/phy_addr、size 和 timestamp 必须与 VENC 或音频编码器输出匹配。原生 RTSP 服务不负责 PCM 或原始图像编码。视频新客户端通常需要收到参数集和关键帧才能开始解码；H.264 需要 SPS/PPS，H.265 需要 VPS/SPS/PPS。

高层 RtspServer 和随附 rtsp_server.py 示例仅建立视频采集、编码和发送链路。底层 API 虽支持 rtspserver_sendaudiodata()，但应用必须自行实现音频采集、编码和时间戳管理。

有关底层编码参数和 IDR 请求，请参阅 VENC 模块 API。