Protocol: nabto.rtsp/1

The nabto.rtsp/1 protocol manages RTSP media sessions through Cambridge. It allows clients to create, control and tear down RTSP streams from configured RTSP services, with the media delivered over the WebRTC peer connection.

Open a datachannel with the protocol "nabto.rtsp/1". The datachannel label can be picked arbitrarily:

const channel = pc.createDataChannel("rtsp", {
    protocol: "nabto.rtsp/1",
});

rtsp.listServices

Lists the RTSP services configured on the device (defined in services.rtsp configuration tables).

Request

{
  "jsonrpc": "2.0",
  "method": "rtsp.listServices",
  "id": "1234"
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "services": [
      {
        "name": "camera1",
        "description": "Front door camera"
      }
    ]
  },
  "id": "1234"
}

Each entry contains:

Field	Type	Description
`name`	string	Service name, used in the `service` parameter of `rtsp.createSession`
`description`	string	Human-readable description from the configuration

rtsp.createSession

Establishes an RTSP session with a configured RTSP service. Cambridge performs the RTSP DESCRIBE and SETUP handshake, then adds the resulting media tracks to the WebRTC peer connection. This triggers a WebRTC renegotiation, so the client must be prepared to handle an incoming offer after the response is received.

Request

{
  "jsonrpc": "2.0",
  "method": "rtsp.createSession",
  "params": {
    "service": "camera1",
    "target": "/stream",
    "mediaStreamId": "custom-stream-id",
    "digestAuthentication": {
      "username": "admin",
      "password": "secret"
    },
    "backchannel": {
      "mediaStreamId": "custom-stream-id-2"
    },
    "constraints": {
      "audio": true,
      "video": true
    }
  },
  "id": "5678"
}

Parameters

Parameter	Required	Type	Description
`service`	Yes	string	RTSP service name from the device configuration
`target`	Yes	string	RTSP path on the camera. Supports URL query parameters, e.g., `/stream?playback_time=1769504700` for playback
`mediaStreamId`	No	string	Custom WebRTC media stream identifier for the incoming tracks
`digestAuthentication`	No	object	Credentials with `username` and `password` fields. Overrides the service-level digest authentication from the configuration
`backchannel`	No	object	Enables ONVIF backchannel for 2-way audio. Contains a `mediaStreamId` field for the outgoing audio track
`constraints`	No	object	Allows specifying constraints on the RTSP stream

Response

{
  "jsonrpc": "2.0",
  "result": {
    "session": "session-uuid-1234"
  },
  "id": "5678"
}

Field	Type	Description
`session`	string	Unique session identifier used in subsequent `rtsp.play`, `rtsp.pause` and `rtsp.teardown` calls

After receiving the createSession response, the client must handle an incoming WebRTC renegotiation offer from Cambridge. The new media tracks (video and optionally audio) will be added to the peer connection as part of this renegotiation. If you are using the Nabto WebRTC client SDKs with Perfect Negotiation, this is handled automatically.

rtsp.play

Sends an RTSP PLAY command to start media streaming for an established session.

Request

{
  "jsonrpc": "2.0",
  "method": "rtsp.play",
  "params": {
    "session": "session-uuid-1234",
    "target": "/stream"
  },
  "id": "9012"
}

Parameters

Parameter	Required	Type	Description
`session`	Yes	string	Session ID from the `createSession` response
`target`	No	string	RTSP path; defaults to the target used in `createSession`

Response

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "9012"
}

rtsp.pause

Sends an RTSP PAUSE command to halt media streaming without closing the session.

Request

{
  "jsonrpc": "2.0",
  "method": "rtsp.pause",
  "params": {
    "session": "session-uuid-1234"
  },
  "id": "3456"
}

Parameters

Parameter	Required	Type	Description
`session`	Yes	string	Session ID from the `createSession` response

Response

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "3456"
}

rtsp.teardown

Sends an RTSP TEARDOWN command to close the session and remove the associated media tracks from the WebRTC peer connection.

Request

{
  "jsonrpc": "2.0",
  "method": "rtsp.teardown",
  "params": {
    "session": "session-uuid-1234"
  },
  "id": "7890"
}

Parameters

Parameter	Required	Type	Description
`session`	Yes	string	Session ID from the `createSession` response

Response

{
  "jsonrpc": "2.0",
  "result": {},
  "id": "7890"
}

Typical Session Sequence

A typical RTSP streaming session follows this sequence:

Discover services. Call rtsp.listServices to find available RTSP services.
Create session. Call rtsp.createSession with the desired service and stream path. Wait for the response and handle the subsequent WebRTC renegotiation.
Start playback. Call rtsp.play to begin receiving media.
Control playback. Use rtsp.pause and rtsp.play as needed to pause and resume.
End session. Call rtsp.teardown to close the session and clean up media tracks.