From 40c62f74faeae1f4306e22c2288e7d012957550b Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Thu, 12 Nov 2026 21:09:25 +0530 Subject: [PATCH] Add configurable RTSP transport (tcp, udp, auto) The agent hard-coded TCP (interleaved) for every camera connection, so cameras and networks that only work well over UDP could not be used and there was no way to let the client negotiate the transport. Add an optional capture.ipcamera.rtsp_transport setting, also available as AGENT_CAPTURE_IPCAMERA_RTSP_TRANSPORT, with these values: - tcp (default, also used when unset): unchanged behaviour - udp: force RTP over UDP - auto: let gortsplib try UDP first and fall back to TCP Unknown values log a warning and fall back to TCP so a typo cannot break an existing deployment. The setting is applied to the main, sub and backchannel clients and to both camera verification paths (HTTP and MQTT). The Settings page gets a transport dropdown next to the RTSP URLs and the verify request forwards the selected value, so unsaved choices can be tested. The README documents the new variable. Tests cover the transport-to-protocol mapping and the environment override. Signed-off-by: Asish Kumar --- README.md | 1 + machinery/src/capture/gortsplib.go | 36 +++++++++++++++++++++---- machinery/src/capture/gortsplib_test.go | 33 +++++++++++++++++++++++ machinery/src/capture/main.go | 3 ++- machinery/src/components/kerberos.go | 3 +++ machinery/src/config/main.go | 5 ++++ machinery/src/config/main_test.go | 12 +++++++++ machinery/src/models/api_response.go | 2 ++ machinery/src/models/config.go | 4 +++ machinery/src/routers/mqtt/main.go | 5 +++- ui/public/locales/en/translation.json | 5 ++++ ui/src/api/agent.js | 3 +++ ui/src/pages/Settings/Settings.jsx | 28 +++++++++++++++++++ 13 files changed, 133 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 424b78b..841b2d8 100644 --- a/README.md +++ b/README.md @@ -375,6 +375,7 @@ See [RTSPS and TLS certificates](README-RTSPS-TLS.md) for the complete Bosch UI, | `AGENT_TIMETABLE` | A (weekly) time table to specify when to make recordings "start1,end1,start2,end2;start1.. | "" | | `AGENT_REGION_POLYGON` | A single polygon set for motion detection: "x1,y1;x2,y2;x3,y3;... | "" | | `AGENT_CAPTURE_IPCAMERA_RTSP` | Full-HD RTSP or RTSPS endpoint for the target camera. | "" | +| `AGENT_CAPTURE_IPCAMERA_RTSP_TRANSPORT` | Transport for the RTSP streams: "tcp", "udp" or "auto" (UDP first, falls back to TCP). | "tcp" | | `AGENT_CAPTURE_IPCAMERA_SUB_RTSP` | RTSP or RTSPS sub-stream endpoint used for livestreaming (WebRTC). | "" | | `AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE` | PEM CA bundle appended to the system roots for RTSPS camera certificate verification. | "" | | `AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE` | Disable RTSPS camera certificate verification; use only when a trusted CA cannot be installed. | "false" | diff --git a/machinery/src/capture/gortsplib.go b/machinery/src/capture/gortsplib.go index a19a534..1dde048 100644 --- a/machinery/src/capture/gortsplib.go +++ b/machinery/src/capture/gortsplib.go @@ -50,6 +50,33 @@ const ( rtspsInsecureEnv = "AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE" ) +// RTSP transport options for the camera connection. +const ( + RTSPTransportTCP = "tcp" + RTSPTransportUDP = "udp" + RTSPTransportAuto = "auto" +) + +// rtspProtocol maps the configured RTSP transport onto the gortsplib client +// protocol. An empty value keeps the historical default (TCP). "auto" returns +// nil, which lets gortsplib try UDP first and fall back to TCP when the camera +// or the network does not support it. Unknown values fall back to TCP. +func rtspProtocol(transport string) *gortsplib.Protocol { + var protocol gortsplib.Protocol + switch strings.ToLower(strings.TrimSpace(transport)) { + case "", RTSPTransportTCP: + protocol = gortsplib.ProtocolTCP + case RTSPTransportUDP: + protocol = gortsplib.ProtocolUDP + case RTSPTransportAuto: + return nil + default: + log.Warn("capture.golibrtsp.rtspProtocol(): unknown RTSP transport \"" + transport + "\", falling back to tcp") + protocol = gortsplib.ProtocolTCP + } + return &protocol +} + func rtspsTLSConfig() (*tls.Config, error) { if os.Getenv(rtspsInsecureEnv) == "true" { return &tls.Config{InsecureSkipVerify: true}, nil // #nosec G402 -- explicit opt-in for cameras with self-signed certificates @@ -97,6 +124,8 @@ func sanitizeRTSPError(err error, rawURL string) error { type Golibrtsp struct { RTSPClient Url string + // Transport selects the RTSP transport: "tcp" (default), "udp" or "auto". + Transport string Client gortsplib.Client clientStarted bool @@ -544,11 +573,10 @@ func (g *Golibrtsp) Connect(ctx context.Context, ctxOtel context.Context) (err e return fmt.Errorf("configure RTSPS TLS: %w", err) } - protocol := gortsplib.ProtocolTCP g.health = newStreamHealth() g.Client = gortsplib.Client{ RequestBackChannels: false, - Protocol: &protocol, + Protocol: rtspProtocol(g.Transport), TLSConfig: tlsConfig, // Route gortsplib's packet-loss / decode-error reporting through our // structured logger with stream context (replaces its plain stdout @@ -826,11 +854,9 @@ func (g *Golibrtsp) ConnectBackChannel(ctx context.Context, ctxRunAgent context. return fmt.Errorf("configure RTSPS TLS: %w", err) } - // Transport TCP - protocol := gortsplib.ProtocolTCP g.Client = gortsplib.Client{ RequestBackChannels: true, - Protocol: &protocol, + Protocol: rtspProtocol(g.Transport), TLSConfig: tlsConfig, } // parse URL diff --git a/machinery/src/capture/gortsplib_test.go b/machinery/src/capture/gortsplib_test.go index 432bd9e..32460eb 100644 --- a/machinery/src/capture/gortsplib_test.go +++ b/machinery/src/capture/gortsplib_test.go @@ -12,6 +12,7 @@ import ( "strings" "testing" + "github.com/bluenviron/gortsplib/v5" "github.com/bluenviron/mediacommon/pkg/codecs/h264" ) @@ -247,3 +248,35 @@ func TestH264FrameNumTrackerHonorsPermittedGaps(t *testing.T) { func testH264Slice(naluType h264.NALUType, frameNum uint32) []byte { return []byte{0x60 | byte(naluType), 0xE0 | byte(frameNum&0x1F)} } + +func TestRTSPProtocol(t *testing.T) { + tcp := gortsplib.ProtocolTCP + udp := gortsplib.ProtocolUDP + tests := []struct { + transport string + want *gortsplib.Protocol + }{ + {transport: "", want: &tcp}, + {transport: "tcp", want: &tcp}, + {transport: " TCP ", want: &tcp}, + {transport: "udp", want: &udp}, + {transport: "UDP", want: &udp}, + {transport: "auto", want: nil}, + {transport: "Auto", want: nil}, + {transport: "bogus", want: &tcp}, + } + for _, test := range tests { + t.Run(test.transport, func(t *testing.T) { + got := rtspProtocol(test.transport) + if test.want == nil { + if got != nil { + t.Fatalf("rtspProtocol(%q) = %v, want nil (auto)", test.transport, *got) + } + return + } + if got == nil || *got != *test.want { + t.Fatalf("rtspProtocol(%q) = %v, want %v", test.transport, got, *test.want) + } + }) + } +} diff --git a/machinery/src/capture/main.go b/machinery/src/capture/main.go index 958487b..df0aaf9 100644 --- a/machinery/src/capture/main.go +++ b/machinery/src/capture/main.go @@ -858,7 +858,8 @@ func VerifyCamera(c *gin.Context) { // Currently only support H264 encoded cameras, this will change. // Establishing the camera connection without backchannel if no substream rtspClient := &Golibrtsp{ - Url: rtspUrl, + Url: rtspUrl, + Transport: cameraStreams.RTSPTransport, } err := rtspClient.Connect(ctx, ctxVerifyCamera) diff --git a/machinery/src/components/kerberos.go b/machinery/src/components/kerberos.go index 7a26e41..3e1d1ee 100644 --- a/machinery/src/components/kerberos.go +++ b/machinery/src/components/kerberos.go @@ -207,6 +207,7 @@ func RunAgent(parent context.Context, configDirectory string, configuration *mod // Establishing the camera connection without backchannel if no substream rtspUrl := mainRTSP rtspClient = captureDevice.SetMainClient(rtspUrl) + rtspClient.Transport = config.Capture.IPCamera.RTSPTransport run.SetMainClient(rtspClient) if rtspUrl != "" { err := rtspClient.Connect(run.Context(), ctxRunAgent) @@ -316,6 +317,7 @@ func RunAgent(parent context.Context, configDirectory string, configuration *mod // For the sub stream we will not enable backchannel. subStreamEnabled = true rtspSubClient = captureDevice.SetSubClient(subRtspUrl) + rtspSubClient.Transport = config.Capture.IPCamera.RTSPTransport run.SetSubClient(rtspSubClient) @@ -436,6 +438,7 @@ func RunAgent(parent context.Context, configDirectory string, configuration *mod // Try to create backchannel communication.HasBackChannel.Store(false) rtspBackChannelClient = captureDevice.SetBackChannelClient(rtspUrl) + rtspBackChannelClient.Transport = config.Capture.IPCamera.RTSPTransport run.SetBackchannelClient(rtspBackChannelClient) err = rtspBackChannelClient.ConnectBackChannel(run.Context(), ctxRunAgent) if err == nil { diff --git a/machinery/src/config/main.go b/machinery/src/config/main.go index d64558c..433be4c 100644 --- a/machinery/src/config/main.go +++ b/machinery/src/config/main.go @@ -369,6 +369,11 @@ func applyAgentEnvVars(configuration *models.Configuration, prefix string, apply case "AGENT_CAPTURE_IPCAMERA_RTSP": configuration.Config.Capture.IPCamera.RTSP = value break + + case "AGENT_CAPTURE_IPCAMERA_RTSP_TRANSPORT": + configuration.Config.Capture.IPCamera.RTSPTransport = value + break + case "AGENT_CAPTURE_IPCAMERA_SUB_RTSP": configuration.Config.Capture.IPCamera.SubRTSP = value break diff --git a/machinery/src/config/main_test.go b/machinery/src/config/main_test.go index 3c4e772..f0615b0 100644 --- a/machinery/src/config/main_test.go +++ b/machinery/src/config/main_test.go @@ -104,6 +104,18 @@ func TestApplyAgentEnvVarsVaultCustomHeaders(t *testing.T) { } } +func TestApplyAgentEnvVarsRTSPTransport(t *testing.T) { + t.Setenv("AGENT_CAPTURE_IPCAMERA_RTSP_TRANSPORT", "udp") + configuration := &models.Configuration{} + initConfigPointers(&configuration.Config) + + applyAgentEnvVars(configuration, "", false) + + if got := configuration.Config.Capture.IPCamera.RTSPTransport; got != "udp" { + t.Fatalf("RTSPTransport = %q, want udp", got) + } +} + func intPointer(value int) *int { return &value } diff --git a/machinery/src/models/api_response.go b/machinery/src/models/api_response.go index bb18fc2..c693b18 100644 --- a/machinery/src/models/api_response.go +++ b/machinery/src/models/api_response.go @@ -18,6 +18,8 @@ type OnvifCredentials struct { type CameraStreams struct { RTSP string `json:"rtsp"` SubRTSP string `json:"sub_rtsp"` + // RTSPTransport is optional: "tcp" (default), "udp" or "auto". + RTSPTransport string `json:"rtsp_transport,omitempty"` } // DiscoveredDevice describes a device found on the local network during a diff --git a/machinery/src/models/config.go b/machinery/src/models/config.go index d04004d..bba365b 100644 --- a/machinery/src/models/config.go +++ b/machinery/src/models/config.go @@ -93,6 +93,10 @@ type IPCamera struct { Height int `json:"height"` FPS string `json:"fps"` + // RTSPTransport selects the transport used for RTSP media: "tcp" + // (default), "udp" or "auto" (UDP first, falling back to TCP). + RTSPTransport string `json:"rtsp_transport,omitempty" bson:"rtsp_transport,omitempty"` + SubRTSP string `json:"sub_rtsp"` SubWidth int `json:"sub_width"` SubHeight int `json:"sub_height"` diff --git a/machinery/src/routers/mqtt/main.go b/machinery/src/routers/mqtt/main.go index 41154fd..a799195 100644 --- a/machinery/src/routers/mqtt/main.go +++ b/machinery/src/routers/mqtt/main.go @@ -860,7 +860,10 @@ func HandleVerifyStream(mqttClient mqtt.Client, hubKey string, payload models.Pa ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) defer cancel() - rtspClient := &capture.Golibrtsp{Url: rtspUrl} + rtspClient := &capture.Golibrtsp{ + Url: rtspUrl, + Transport: configuration.Config.Capture.IPCamera.RTSPTransport, + } errConnect := rtspClient.Connect(ctx, ctx) if errConnect != nil { errMsg = errConnect.Error() diff --git a/ui/public/locales/en/translation.json b/ui/public/locales/en/translation.json index 6123693..6185538 100644 --- a/ui/public/locales/en/translation.json +++ b/ui/public/locales/en/translation.json @@ -103,6 +103,11 @@ "only_h264": "Currently only H264/H265 RTSP streams are supported.", "rtsp_url": "RTSP URL", "rtsp_h264": "A H264/H265 RTSP connection to your camera.", + "rtsp_transport": "RTSP transport", + "rtsp_transport_select": "Select RTSP transport", + "rtsp_transport_tcp": "TCP (reliable, default)", + "rtsp_transport_udp": "UDP (low latency)", + "rtsp_transport_auto": "Auto (UDP, fall back to TCP)", "sub_rtsp_url": "Sub RTSP URL (used for livestreaming)", "sub_rtsp_h264": "A secondary RTSP connection to the low resolution of your camera.", "onvif": "ONVIF", diff --git a/ui/src/api/agent.js b/ui/src/api/agent.js index 7ab8665..c895533 100644 --- a/ui/src/api/agent.js +++ b/ui/src/api/agent.js @@ -134,11 +134,14 @@ export function doVerifyCamera(streamType, config, onSuccess, onError) { const cameraStreams = { rtsp: '', sub_rtsp: '', + rtsp_transport: '', }; if (config) { cameraStreams.rtsp = config.capture.ipcamera.rtsp; cameraStreams.sub_rtsp = config.capture.ipcamera.sub_rtsp; + cameraStreams.rtsp_transport = + config.capture.ipcamera.rtsp_transport || ''; } const endpoint = API.post(`camera/verify/${streamType}`, cameraStreams); diff --git a/ui/src/pages/Settings/Settings.jsx b/ui/src/pages/Settings/Settings.jsx index 35e17f1..b10c31e 100644 --- a/ui/src/pages/Settings/Settings.jsx +++ b/ui/src/pages/Settings/Settings.jsx @@ -1074,6 +1074,34 @@ export class Settings extends React.Component { ) } /> + + this.onUpdateDropdown( + 'capture.ipcamera', + 'rtsp_transport', + value[0], + config.capture.ipcamera + ) + } + /> {config.capture.ipcamera &&