# `BB.Camera.Hub`
[🔗](https://github.com/beam-bots/bb_camera/blob/main/lib/bb/camera/hub.ex#L5)

The one capture a camera has, shared by everyone watching it.

One hub per camera, started and linked by the driver in its `init/1`. It
registers itself in the robot's own `Registry` under `{:camera, name}`, so
consumers find it the same way they find anything else in a robot.

## What it is for

A camera has one physical capture no matter how many things want to watch it,
and image data is large enough that the usual answer - publish and let
subscribers sort it out - stops working. A 1080p MJPEG stream is tens of
megabytes a second; put that through a fan-out registry with no backpressure
and a single slow consumer becomes an unbounded mailbox and then a dead node.
So frames do not go on `BB.PubSub` at all. They come through here, and here
there are bounds at both ends:

* **Ingress** - `deliver/2` is a synchronous call. The driver blocks until
  the hub has taken the frame, so at most one frame per driver is ever in
  flight and the hub's mailbox cannot grow faster than it drains.
* **Buffer** - the hub keeps exactly one frame, the latest. A new frame
  replaces the previous one whether or not anybody read it.
* **Egress** - a consumer gets a frame only when it has asked for one, one at
  a time, and only one strictly newer than the last it received.

That last clause is what makes a `next`-in-a-loop consumer - an HTTP MJPEG
route, say - run at the camera's frame rate rather than spinning: there is
nothing to return until the camera produces something new.

The interface is deliberately source-agnostic. A driver reading a V4L2 device
through a subprocess, one calling into a platform capture framework from a
NIF, and one generating frames arithmetically all meet it the same way: they
hand over a `BB.Camera.Frame` and wait for the hub to take it.

## Lifecycle is driver-confirmed

The hub asks the driver to start capturing when the first consumer arrives
and to stop when the last one leaves, but it does not assume either worked. A
driver confirms with `capture_started/2` or reports `capture_failed/2`, and
only then is `BB.Message.Camera.BeginCapture` published. A camera whose
device fails to open never claims to be capturing, and every consumer waiting
on it is told rather than left on a stream that will not resume.

Because those confirmations are asynchronous, the hub tracks capture as a
state machine - `:idle`, `:starting`, `:capturing`, `:stopping` - rather than
a boolean. A consumer arriving while a stop is still in flight does not race
it: the restart is held until the stop is confirmed, and the confirmation is
attributed to the session it belongs to, so a new consumer is never told that
a capture it was never part of has ended.

A capture failure is not retried automatically. Subscribers are told, and the
hub returns to `:idle`; a driver whose device is missing would otherwise be
restarted in a tight loop for as long as anyone was watching.

## How fast it is really going

Every frame passes through `deliver/2`, so the hub is the one place that can
measure a camera's real rate without each driver being asked to. While
capture is running it counts frames over a window and publishes
`BB.Message.Camera.CaptureState` at the end of each one, carrying what was
asked for alongside what the frames actually did. The same pair is stamped
onto every frame.

The window is counted, not smoothed, so a capture that has stalled reports
`0.0` rather than the rate it used to manage.

## Bounding what happens before the hub

`deliver/2` bounds what crosses into `bb_camera`. It cannot bound what
accumulates between an external source and the BEAM. An Erlang port offers no
ingress flow control - `Port.open`'s `busy_limits_msgq` does not provide one
for port-to-owner data - and a native capture callback delivering frames into
a process mailbox has the same problem. A driver has to bound that itself: a
capped output rate, a drain-only owner process, hard buffer and frame-size
caps, an explicit overload trip.

Nor does closing a port stop the program behind it. Neither `Port.close/1`,
killing the port's owner, nor the owner crashing will end the spawned
process; it is reparented and carries on. This usually goes unnoticed because
the program dies of `SIGPIPE` on its next write to the closed pipe - which is
exactly what does not happen to a camera that has wedged. A driver that
spawns anything needs an explicit reaper; `terminate/2` is not enough.

# `capture_failed`

```elixir
@spec capture_failed(GenServer.server(), struct()) :: :ok
```

Report that capture failed.

Publishes `BB.Message.Camera.EndCapture` with `reason: :error` and hands the
error to every subscriber of the session that failed. The hub does not
restart capture by itself afterwards.

# `capture_started`

```elixir
@spec capture_started(GenServer.server(), BB.Camera.StreamInfo.t() | nil) :: :ok
```

Confirm that capture is running, optionally with the format it's really
running at.

Until this is called the camera is not capturing as far as anything else is
concerned. Passing a `StreamInfo` is the same as calling
`update_stream_info/2` first, and is how a driver reports the geometry it
negotiated rather than the one it asked for.

Each confirmation starts a new session: the frame counter returns to zero,
every subscriber's idea of what it has already seen is cleared, and the hub
forgets the sequence it last saw. That last part is what lets a driver choose
- restart its sequence at zero for each session, or carry one counter across
restarts because its capture backend does. Both are accepted; what the hub
insists on is only that the sequence strictly increases *within* a session.

# `capture_state`

```elixir
@spec capture_state(GenServer.server()) :: :idle | :starting | :capturing | :stopping
```

The hub's capture state: `:idle`, `:starting`, `:capturing` or `:stopping`.

# `capture_stopped`

```elixir
@spec capture_stopped(GenServer.server(), atom()) :: :ok
```

Report that capture has stopped cleanly.

When the hub was the one that asked - because the last consumer left - it
uses its own reason for the published event rather than the one given here,
so a driver never has to work out why it was asked to stop.

# `capturing?`

```elixir
@spec capturing?(GenServer.server()) :: boolean()
```

Whether the driver has confirmed capture is running.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `deliver`

```elixir
@spec deliver(GenServer.server(), BB.Camera.Frame.t(), timeout()) ::
  :ok | {:error, struct()}
```

Hand a frame over, blocking until the hub has taken it.

Synchronous by design. This is the only ingress bound that exists, and
wrapping it in a `Task` to "avoid blocking capture" reintroduces precisely
the unbounded queue it is here to prevent. The hub does nothing with a frame
beyond storing it and passing it to whoever has asked, so the call returns
promptly; a timeout means the hub is wedged, which is a crash rather than a
dropped frame.

Returns `{:error, %BB.Error.Invalid.Camera.StaleFrame{}}` if the sequence
doesn't strictly increase, and `{:error, %BB.Error.State.Camera.NotCapturing{}}`
if capture hasn't been confirmed started. Both are bugs in the driver, and
neither takes the hub down with it.

# `start_link`

```elixir
@spec start_link(keyword()) :: GenServer.on_start()
```

Start a hub for the camera the calling driver serves.

Call this from the driver's `init/1`. The default `:driver` is the calling
process, resolved here rather than in the hub's own `init/1` - where `self()`
would be the hub.

The hub links to the driver and monitors it. The link covers a crash; the
monitor covers a clean exit, which a link would not propagate, and which
would otherwise leave a hub registered for a camera that no longer exists.

## Options

* `:bb` (`t:map/0`) - Required. The `%{robot:, path:}` injected into the driver's options

* `:stream_info` (struct of type `BB.Camera.StreamInfo`) - Required. What the camera is expected to produce

* `:driver` (`t:pid/0`) - The process to drive capture, defaults to the process calling `start_link/1`

* `:publish_rate` (`t:term/0`) - How often `BB.Message.Camera.CaptureState` is published, in hertz -
  a `Localize.Unit` or a plain number. Defaults to
  `1`.  
  `:external` instead of a rate means the hub closes no window of its own
  and publishes only when sent `{:tick, monotonic_ns}`, taking that
  timestamp as the end of the window. Hand it a real
  `System.monotonic_time(:nanosecond)` unless you mean to measure against
  something else.

# `update_stream_info`

```elixir
@spec update_stream_info(GenServer.server(), BB.Camera.StreamInfo.t()) :: :ok
```

Replace the live stream format.

Call it when the first real frame reveals the actual geometry, or when a
change to the camera's options alters it. Each subscriber is told as
`{:bb_camera, ref, {:stream_info, info}}` immediately before the first frame
the new format describes.

The buffered frame is discarded, because it was encoded under the old format
and there is no longer an honest way to describe it: announcing the new
format and then handing over the old frame would be worse than dropping one
frame from a stream whose policy is already to drop frames.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
