Publishing into the node

A node normally connects to a camera and pulls its stream. A camera whose source is publisher works the other way round: a publisher — an encoder, ffmpeg, a camera that can push its stream — connects to the node and pushes the stream into it over RTSP. The published stream is recorded and served over RTSP, HLS and WebRTC like any other camera's.

Configuration

security:
  users:
    - user: publisher
      pass: "argon2:$argon2id$..."
      permissions:
        - action: publish
          path: camera_042

cameras:
  camera_042:
    source: publisher
    record: true
    audio: true

sub: publisher takes the camera's substream the same way, published at /<camera>/sub.

Publishing writes into the camera's archive, so it always takes a user with publish on the camera — even when security.users is empty and everything else is open.

Publishing

The publisher pushes to rtsp://<node>:<rtsp.port>/<camera>:

ffmpeg -re -i input.mp4 -c copy -f rtsp -rtsp_transport tcp \
  rtsp://publisher:secret@node:8554/camera_042

• Transport: TCP (interleaved). A SETUP asking for UDP is answered 461; ffmpeg then moves to TCP by itself.
• Codecs: video H.264 or H.265, sound AAC or G.711. A sound track in another codec is left out.
• The sound is kept in step with the picture by the publisher's RTCP Sender Reports, even when it starts before the first keyframe.

While publishing

• One publisher at a time: while it sends video, another is refused with 455, and the node's log names both. A publisher that sends no video for 5 seconds is let go, and the next one is taken.
• The recording starts with the publication and ends with it: a pause between publications is a gap in the archive, as a camera reconnecting is.
• With nobody publishing, RTSP and HLS viewers of the camera are refused, and the recording waits.

Answers

Status	When
401	no user with publish on the camera, or a wrong password
404	no such camera
405	the camera's source is not publisher
455	somebody else publishes the camera
461	SETUP asked for UDP
503	in a cluster: the node does not record (no recorder role), or the cluster could not be asked who publishes the camera

In a cluster

Recorder nodes stand behind a TCP balancer, and a publisher may reach any of them. The node it reaches records the camera, and viewers on any node get it. When the publisher comes back through another node, that one records, and the archive is assembled across them.

• One publisher across the whole cluster: while a node holds the camera's publication, every other node refuses with 455. A node that is gone gives it up.
• Only nodes with the recorder role take publishers; send the balancer to them alone.
• /api/health/ready answers without a password and tells the balancer which nodes can take traffic.

The balancer passes the publisher's address on with the PROXY protocol, so the node sees it rather than the balancer's. On every node, the balancer is trusted to send that address:

rtsp:
  trustedProxies: ["10.0.0.5"]

From the addresses in rtsp.trustedProxies a connection must start with a PROXY header (v1 or v2); users' ips and the log go by the address in it. From anyone else the header is never read.

More in the integrators' section

Limits

• TCP only: UDP does not pass a TCP balancer, and every publisher we know of can use TCP.