BB.Camera.FFmpeg.Backend.MuonTrap (bb_camera_ffmpeg v0.1.0)

Copy Markdown View Source

Runs ffmpeg under MuonTrap, behind an Erlang port.

MuonTrap is a small C program that starts ffmpeg as its own child and stays between it and the BEAM. Three things follow from that, and they are why it is here:

  • ffmpeg cannot outlive its owner. MuonTrap watches its stdin. When the port closes — because its owner crashed, was killed, or the VM halted — MuonTrap sends ffmpeg SIGTERM, then SIGKILL after :stop_timeout_ms. A bare port gives no such guarantee: the program behind it is reparented to init and keeps running until a write fails, and an ffmpeg waiting for a camera never writes.
  • No pid is ever signalled from outside. MuonTrap is ffmpeg's parent, so it reaps it and cannot mistake a recycled pid for it.
  • Output is flow-controlled. MuonTrap forwards at most :stdio_window bytes before they are acknowledged with ack/2. That bounds what can queue in the reading process's mailbox, which a bare port cannot do.

No shell, ever

The port is opened with :spawn_executable and an explicit argument vector, and MuonTrap execvps ffmpeg with the arguments as given. No shell parses them.

stdin belongs to MuonTrap

The acknowledgements travel over MuonTrap's stdin, and ffmpeg inherits it. ffmpeg must therefore run with -nostdin: without it, ffmpeg reads the acknowledgement bytes as keyboard commands — 0x71 is q — and takes them away from MuonTrap, which then stops forwarding. open/3 refuses an argument vector without it.

It also means ffmpeg cannot be asked to stop with q. request_stop/1 sends MuonTrap SIGTERM instead, which passes it to ffmpeg and escalates to SIGKILL after :stop_timeout_ms.

stderr

ffmpeg's stderr is not captured. It stays attached to the VM's own, so an ffmpeg complaint about a busy device or an unsupported format appears on the console, where someone setting a camera up will see it.

Exit status

When ffmpeg exits by itself, MuonTrap exits with its status. When MuonTrap is told to stop, it exits 1 whatever ffmpeg did.

A private function

MuonTrap's public API has no way to stream binary output with flow control: MuonTrap.Daemon splits output into lines for Logger. This module opens the port itself and acknowledges through MuonTrap.Port.report_bytes_handled/2, which MuonTrap does not document. A change to it breaks compilation here, not the stream.