rtsp – RTSP Streaming

[中文]

The rtsp module serves H.264 NAL units over RTSP so a client such as VLC or ffplay can view the camera stream over the network. Pair it with h264 – H.264 Encoding. It is available on ESP32-P4 builds.

Capture, Encode, and Stream

import network, sensor, h264, rtsp, time
from machine import Pin

WIDTH, HEIGHT, FPS = 320, 240, 30

lan = network.LAN(
    mdc=Pin(31),
    mdio=Pin(52),
    reset=Pin(51),
    phy_addr=1,
    phy_type=network.PHY_IP101,
)
lan.active(True)

for _ in range(100):
    if lan.isconnected():
        break
    time.sleep_ms(100)
if not lan.isconnected():
    raise OSError("Ethernet connection failed")

sensor.reset()
sensor.set_pixformat(sensor.RGB565)
sensor.set_framesize(sensor.QVGA)
sensor.skip_frames(time=1000)

enc = h264.H264Encoder(WIDTH, HEIGHT, fps=FPS, bitrate=3_000_000)
server = rtsp.RTSPServer(WIDTH, HEIGHT, fps=FPS, listen_port=8554)

print("rtsp://%s:8554/" % lan.ifconfig()[0])
try:
    while True:
        server.send(enc.encode(sensor.snapshot()))
finally:
    server.stop()
    enc.close()

The Ethernet pin mapping above is for the ESP32-P4X-Function-EV-Board with its IP101 RMII PHY; use the network configuration appropriate for another product board. The width, height, and frame rate advertised by RTSPServer must match the encoder configuration.

Client and Queue Behavior

Open the printed URL with ffplay rtsp://<board-ip>:8554/ or an RTSP-capable player. send() queues one encoded frame and does not wait for a client; when no client is connected or the client is too slow, frames may be dropped so the capture loop is not blocked. max_frame_len can be increased when high-resolution or high-bitrate encoded frames exceed the default limit.

Shutdown

Always call server.stop() before releasing network or encoder resources. A try/finally block ensures cleanup also occurs when the script is interrupted or an exception is raised.

Classes

class rtsp.RTSPServer(width, height, *, fps=..., listen_port=..., max_frame_len=...)

Minimal RTSP server that streams H.264 video over the network. Create it once Wi-Fi is up, then push encoded NAL units from an h264.H264Encoder with send(). Clients connect to rtsp://<board-ip>:<listen_port>/. Only video (no audio) is served.

Start the RTSP server and advertise the given stream format.

Parameters:

width – advertised video width in pixels.
height – advertised video height in pixels.
fps – advertised frame rate, used for SDP and pacing.
listen_port – TCP port the RTSP service binds to.
max_frame_len – max accepted encoded frame size in bytes; 0 uses width*height as a safe ceiling.

send(nal)

Queue one encoded H.264 frame (Annex-B NAL units) for delivery. Frames are sent in order; if the client is slow or absent the frame is dropped rather than blocking the caller. Frames larger than max_frame_len are ignored.

Parameters:: nal – encoded frame bytes from h264.H264Encoder.encode().

stop(): Stop the server, join its task, and free queued frames.