# `BB.Camera.FFmpeg.Backend.MuonTrap`
[🔗](https://github.com/beam-bots/bb_camera_ffmpeg/blob/main/lib/bb/camera/ffmpeg/backend/muontrap.ex#L5)

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 `execvp`s 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.

---

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