@spec args(String.t(), String.t()) :: [String.t()]

The argument vector probe/2 runs, for a caller that spawns the subprocess itself.

/info wants probe/2: it is answering a request and can block on the collect. AudioProxy.Peaks.Render cannot — it is a GenServer that has to stay answerable to cancel/1 while the probe runs, so it spawns the same argv through AudioProxy.Ffmpeg.Render and folds the chunks in handle_info/2. Both routes must ask ffprobe the same question, or the two callers would drift on flags; this function is that shared answer.

protocols is the -protocol_whitelist set, from AudioProxy.Ffmpeg.Command.protocols/1, and it is an argument rather than an option for exactly the reason above: a caller that builds its own argv would otherwise be the one route that reads a source unrestricted, which is the hole the whitelist exists to close. It binds the input because it precedes it.

input is passed through as a single argv element, and is last, so nothing after it can be read as a flag.

iex> AudioProxy.Ffprobe.args("s3://b/k.wav", "https,tls,tcp") |> List.last()
"s3://b/k.wav"

iex> AudioProxy.Ffprobe.args("/srv/a.wav", "file") |> Enum.take(-3)
["-protocol_whitelist", "file", "/srv/a.wav"]

@spec contract(
  map(),
  keyword()
) :: {:ok, info()} | {:error, :undecodable_source}

Maps ffprobe's decoded JSON to the §4 contract.

A pure function — this is what the per-container fixtures pin. Options:

• :size — the object size AudioProxy.Source.stat/1 reported, which wins over ffprobe's own.

Returns {:error, :undecodable_source} when the probe found no audio stream: ffprobe parsed something, but nothing this proxy can serve.

iex> probe = %{
...>   "format" => %{"format_name" => "wav", "duration" => "3.5", "size" => "672044"},
...>   "streams" => [%{
...>     "codec_type" => "audio", "codec_name" => "pcm_s16le",
...>     "sample_rate" => "48000", "channels" => 2, "bits_per_sample" => 16
...>   }]
...> }
iex> AudioProxy.Ffprobe.contract(probe)
{:ok, %{format: "wav", duration: 3.5, sample_rate: 48000, channels: 2,
        bit_depth: 16, size: 672044}}

@spec executable(String.t() | nil) :: {:ok, String.t()} | {:error, error_reason()}

Resolves the ffprobe binary, or {:error, :probe_failed}.

Public for the same reason args/1 is: a caller that spawns the subprocess itself still has to find it, and finding it twice in two ways is how the two paths end up disagreeing about which binary ran.

@spec has_video?(map()) :: boolean()

Whether a probe found a genuine video stream.

The question the audio-only policy turns on, and it is not simply "is there a stream whose codec_type is video". Virtually every tagged mp3, flac and m4a carries its cover art as exactly such a stream, and refusing those would refuse most of a real catalogue. Two exemptions, in the order they are checked:

• attached_pic disposition — ffmpeg's own word for "this is cover art, not a video track". Authoritative where present.
• A single-frame image codec — mjpeg/png/… with nb_frames of 1, for containers whose disposition data is missing or ambiguous.

Anything else with a video codec_type is video. The fallback direction is deliberate: an unrecognized codec, an absent frame count, a disposition map that says nothing all reject. Failing closed here costs a client a 415 on an odd file; failing open makes the proxy a video transcoder.

Two limits worth knowing. The image-codec list is not every still-image decoder ffmpeg carries, only names that cannot also be a video stream — see the list itself for why widening it is the risky direction. And the attached_pic exemption trusts a flag that lives in the container, i.e. in bytes the requester may control: a crafted file can wear it. What that buys is bounded by the layer underneath rather than by this function — every argv carries -vn -sn -dn, so the video stream is never mapped and the render is an audio-only encode either way.

iex> AudioProxy.Ffprobe.has_video?(%{"streams" => [
...>   %{"codec_type" => "audio", "codec_name" => "mp3"},
...>   %{"codec_type" => "video", "codec_name" => "mjpeg",
...>     "disposition" => %{"attached_pic" => 1}}
...> ]})
false

iex> AudioProxy.Ffprobe.has_video?(%{"streams" => [
...>   %{"codec_type" => "video", "codec_name" => "h264"}
...> ]})
true

@spec probe(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, error_reason()}

Runs ffprobe against input and returns its decoded JSON.

input is whatever AudioProxy.Source.ffmpeg_input/1 produced — a path or a presigned URL — and is passed through as a single argv element.

Options:

• :protocols — required. The -protocol_whitelist set, from AudioProxy.Ffmpeg.Command.protocols/1. Required rather than defaulted for the same reason AudioProxy.Ffmpeg.Command.build/3 requires its type:: this is a subprocess that reads the source, so a caller with no protocol set to offer has no business starting one. There is deliberately no "unrestricted" spelling — an omitted key raises, which fails a refactor's tests rather than silently reopening file: and concat: to whatever the source redirects to.
• :executable — the binary to run. Defaults to ffprobe from PATH.
• :timeout — milliseconds. Defaults to AP_PROBE_TIMEOUT.

@spec timeout(keyword()) :: pos_integer()

The probe deadline in milliseconds — AP_PROBE_TIMEOUT as the subprocess sees it.