# `BB.Camera.Membrane.Source`
[🔗](https://github.com/beam-bots/bb_camera/blob/main/lib/bb/camera/membrane/source.ex#L6)

A `Membrane.Source` that reads from a BB camera.

Membrane's demand maps one-to-one onto `BB.Camera.request/1`, so a pipeline
exerts real backpressure on the camera and nothing accumulates outside it.
The element asks the hub for a frame for each buffer the pipeline demands,
and the hub holds one frame regardless, so a pipeline that falls behind sees
current frames rather than a growing backlog.

    import Membrane.ChildrenSpec

    child(:camera, %BB.Camera.Membrane.Source{robot: MyRobot, camera: :eye})
    |> child(:sink, %Membrane.Testing.Sink{})

## Format

The output pad carries `Membrane.JPEG`, the standard format struct, so
downstream Membrane JPEG elements interoperate without a shim. The element
re-emits it whenever the camera renegotiates its geometry - the camera tells
consumers before the first frame encoded the new way, so the format a
downstream element holds always matches the buffer it is about to receive.

`pixel_format` comes from `stream_info.metadata[:pixel_format]` and is `nil`
when the driver doesn't report chroma subsampling, which `Membrane.JPEG`
permits.

## Timestamps

`pts` is nanoseconds since the first frame of this element's session, not
raw monotonic time - `System.monotonic_time/1` is routinely a large negative
number, and a pipeline that starts its timeline there is one subtraction away
from nonsense. The untouched capture timestamps are preserved in
`metadata.bb_camera` for anything that needs to correlate a buffer with the
rest of the robot's telemetry.

## Formats it refuses

Constructing the element against a camera whose format this package won't
carry fails at setup rather than at the first buffer. See
`BB.Camera.Format` - the short version is that an interframe codec cannot
survive the frame-dropping this interface is built on, so it is refused
rather than corrupted.

## Element options

Passed via struct `t:BB.Camera.Membrane.Source.t/0`

- `robot`  

  ```
  module()
  ```
  
  ***Required***  
  The robot module the camera is declared on

- `camera`  

  ```
  atom()
  ```
  
  ***Required***  
  The camera's sensor name

- `end_of_stream_on_capture_end?`  

  ```
  boolean()
  ```
  
  Default value: `true`  
  Whether a cleanly ended capture ends the stream. With `false`,
  the element stays in place and resumes if capture restarts.

## Pads

### `:output`

Accepted formats:
```
%Membrane.JPEG{}
```

Direction: | `:output`
Availability: | `:always`
Flow control: | `:manual`
Demand unit: | `nil`

# `t`

```elixir
@type t() :: %BB.Camera.Membrane.Source{
  camera: atom(),
  end_of_stream_on_capture_end?: boolean(),
  robot: module()
}
```

Struct containing options for `BB.Camera.Membrane.Source`

# `options`

```elixir
@spec options() :: keyword()
```

Returns description of options available for this module

---

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