BB.Camera.Media (bb_camera v0.1.1)

Copy Markdown View Source

Reading frames from a camera with a loop of your own.

The same mechanism as BB.Camera.subscribe/3 and friends, shaped for code that would rather block than handle messages - an HTTP route writing chunks to a browser being the obvious case:

{:ok, session} = BB.Camera.Media.open(MyRobot, :eye, format: :jpeg)

Stream.repeatedly(fn -> BB.Camera.Media.next(session, 2_000) end)
|> Enum.reduce_while(conn, fn
  {:ok, frame}, conn -> {:cont, write_part(conn, frame)}
  {:error, _}, conn -> {:halt, conn}
end)

BB.Camera.Media.close(session)

next/2 returns a frame strictly newer than the one it last returned, so a loop like that one runs at the camera's frame rate rather than spinning: the bound is the camera, not the processor. Frames produced while you weren't asking are dropped rather than queued, which is why a consumer that stalls costs the camera nothing and a browser that falls behind sees a current picture rather than an ever-lengthening backlog.

Every failure mode is an {:error, _} return rather than a hang: a timeout, a capture that ended, a capture that failed, a camera process that died. Any of them is a safe signal to stop streaming.

Summary

Functions

Close the session, releasing the consumer.

Wait for the next frame.

Open a session on a camera's capture.

What the camera was producing when this session opened.

Functions

close(session)

@spec close(BB.Camera.Media.Session.t()) :: :ok

Close the session, releasing the consumer.

Capture stops when the last session on a camera closes.

next(session, timeout \\ 5000)

@spec next(BB.Camera.Media.Session.t(), timeout()) ::
  {:ok, BB.Camera.Frame.t()} | {:error, struct()}

Wait for the next frame.

Returns a frame strictly newer than the last one this session returned, immediately if one is already waiting.

On timeout the outstanding demand is cancelled at the hub before returning, and any frame that arrived while the timeout was being processed is picked up rather than stranded in the caller's mailbox. A timeout before any frame has ever arrived is the signal to answer 503 rather than commit to a stream the camera isn't producing.

open(robot, camera, opts \\ [])

@spec open(module(), atom(), keyword()) ::
  {:ok, BB.Camera.Media.Session.t()} | {:error, struct()}

Open a session on a camera's capture.

Options

  • :format - assert the camera produces this format. A consumer that can only render JPEG should say format: :jpeg and be told so here, rather than find out from the bytes.
  • :owner - the process the session belongs to, defaulting to the caller. The hub monitors it, so a disconnected browser or a crashed route releases the capture.

stream_info(session)

What the camera was producing when this session opened.

A frame carries its own format, width and height, which is what to describe a frame with; this is the camera's advertised format, captured once. A camera that renegotiates mid-capture will produce frames that disagree with it, and the frames are the truth.