feat: configurable input with SRT caller mode (INPUT_URL)

[svensson00]

Closes #9

Summary

Adds an optional INPUT_URL env var. When it is set to an srt:// URL the encoder dials that source in caller mode and pulls the MPEG-TS feed straight into the existing filter graph and HLS output, instead of listening for an RTMP publisher. When it is unset the behaviour is exactly today's RTMP listener, so this is fully backward compatible.

This covers the two workflows in the issue: SRT contribution, and container platforms where no inbound UDP port can be exposed (the encoder dials out rather than listening).

What changed

• src/encoder.ts
  • generateInput takes an optional inputUrl. When present it emits -i <inputUrl> (no RTMP -listen); when absent it emits the unchanged RTMP listener args.
  • EncoderOpts gains inputUrl?: string and inputDialTimeoutSec?: number. inputUrl is validated in the constructor: it must parse as a URL, use the srt: scheme, and include a host and port, otherwise the process fails fast at startup with a clear (secret-redacted) message.
  • The monitor loop no longer treats an ffmpeg exit as terminal error when caller-mode input is configured and the encoder never reached running. It re-dials while staying in starting, bounded by a dial deadline; on deadline it lands in error. The RTMP path is untouched.
• src/server.ts reads INPUT_URL and INPUT_DIAL_TIMEOUT into the encoder options.
• Tests and readme updated.

SRT protocol knobs (latency, passphrase, streamid, connect_timeout, mode, ...) travel as query parameters on the URL and are parsed by ffmpeg's srt reader directly. No srt option strings are hardcoded in this change, so the encoder does not need to track ffmpeg's srt option set.

Backward compatibility

With INPUT_URL unset, generateInput returns byte-identical args to before and the monitor's RTMP timeout branch is unchanged (stays stopped). A regression test pins the default RTMP listener args and the RTMP timeout-to-stopped behaviour.

Design choices flagged for maintainers

These came out of self-review; a different shape is fine, the capability is what matters.

1. Dial-deadline expiry lands in error for SRT caller mode, not stopped. Rationale: a source that never connects is an input failure, and a supervising process should be able to tell that apart from a clean stop. The pre-existing RTMP listener timeout still goes to stopped (unchanged). This is a deliberate divergence between the two input modes.
2. A default dial deadline of 300 s applies when no per-request timeout is given, overridable via INPUT_DIAL_TIMEOUT. Without a bound, a wrong passphrase / NXDOMAIN / bad port would re-dial every 5 s forever pinned at starting. Open to a different default or a dedicated max-attempts knob.
3. start() now clears stale HLS output before spawning (both input modes). This fixes a latent bug where a leftover index.m3u8 from a previous run could flip status to running before a connection exists (and, for caller mode, defeat the re-dial). It is a small behaviour change for the RTMP path too.
4. The unexpected-exit path now releases the pull-push fetcher (stopPullPush) before going to error, which it previously did not.
5. Drive-by: this.ffmpeg.exitCode = code || this.wantsToStop ? 0 : 1 was mis-parenthesized (every nonzero exit recorded 0); fixed to code || (this.wantsToStop ? 0 : 1).
6. Secret redaction covers three sinks: the constructor validation error, the spawnargs exit log, and the ffmpeg stderr passthrough. The last one matters because a failed srt dial echoes the full input URL (passphrase, streamid) in ffmpeg's stderr, and failed dials are the common caller-mode path. Note stderr data events are chunked, so a URL split across chunks could in theory evade redaction; the normal single-line case is covered.

Known and accepted (unchanged here): there is still no in-progress guard on start() (pre-existing, no double-spawn path exists via the API), and a DELETE during a re-dial gap reports starting until the next monitor tick (cosmetic lag).

Merge coordination

PR #12 (WebVTT subtitle passthrough) also changes generateInput in this repo. Whoever merges second must reconcile the generateInput signature so SRT input and subtitle passthrough compose; a naive merge of both branches will break the combination.

Dial-failure / retry semantics

ffmpeg's srt caller does not retry internally; on a failed dial it exits non-zero (see the probe below). The encoder re-dials on the next monitor tick (a natural ~5s backoff) while staying in starting, until either the source connects or the dial deadline is reached (then error).

Contract verification

Docker was used to probe the exact published image rather than coding option strings from generic ffmpeg docs.

Image probed: eyevinntechnology/live-encoding:latest
Digest: sha256:a77339d6cea4d35f85b972d23b29b37285a0ffb570f2cb0257b8c4d999dd8d13 (linux/amd64)

ffmpeg build in that image:

ffmpeg version 6.1.1 Copyright (c) 2000-2023 the FFmpeg developers
built with gcc 13.2.1 (Alpine 13.2.1_git20240309)
# /etc/alpine-release: 3.20.3
# ldd $(which ffmpeg): libsrt.so.1.5 => /usr/lib/libsrt.so.1.5

ffmpeg -protocols lists srt (and srtp), confirming the binary speaks srt:// natively with no image change.

ffmpeg -h protocol=srt confirms the knobs referenced in the issue are real AVOptions on this build (passed as URL query params):

-latency          receiver delay in microseconds
-passphrase       Crypto PBKDF2 Passphrase
-streamid         string up to 512 chars (also -srt_streamid)
-connect_timeout  Connect timeout in milliseconds (caller default 3000)
-mode             caller | listener | rendezvous (default caller)
-timeout, -listen_timeout, -transtype, -pbkeylen, -maxbw, ...

mode defaults to caller, so srt://host:port dials out as a caller with no extra option needed. Note the unit split surfaced by the probe and reflected in the readme: latency is microseconds, connect_timeout is milliseconds.

Dial-failure behaviour (feeds the retry design). Dialing a port with no listener inside the image:

$ ffmpeg -loglevel error -i "srt://127.0.0.1:9999" -f null -
[srt] Connection to srt://127.0.0.1:9999 failed: I/O error
Error opening input files: I/O error
exit_code=251   elapsed_ms=3

So the srt caller exits non-zero on dial failure and does not retry itself. A refused/absent local listener returns almost immediately; an unreachable (silently dropped) peer would instead wait up to connect_timeout. The retry-in-starting logic handles both cases, bounded by the dial deadline.

Testing

npm run typecheck, npm run lint (0 errors), npm test (20 passing) all pass locally. Tests cover caller-mode vs RTMP arg generation, INPUT_URL validation (scheme, host/port, secret redaction), the redaction helper, stderr passthrough redaction, and the dial lifecycle via a child_process spawn stub: single re-dial after a pre-running exit, dial-deadline expiry to error (not stopped), the default deadline engaging when no timeout is supplied, stale-index cleanup before spawn, and the RTMP timeout still landing in stopped.

An end-to-end live SRT test needs a reachable listener-mode source and is out of scope here; the arg generation, validation, dial-failure behaviour, and lifecycle transitions are verified as above.

Notes for maintainers

• Naming: INPUT_URL / INPUT_DIAL_TIMEOUT mirror the existing OUTPUT_URL. Happy to rename.
• Validation is restricted to srt:// since that is the requested case; broadening to other ffmpeg input URLs would be a one-line change to the scheme check.
• No image change is required; the published image already links libsrt (evidence above).

[svensson00]

CI note: the pretty check is red, but the only flagged file is docs/api.yaml, which this PR does not touch. It is byte-identical to main (introduced by commit ae507d2 "chore: generated api doc") and fails prettier --check under the repo's .prettierrc (singleQuote: true) independently of this change. The ts, lint and unittests checks all pass, and every file changed here passes prettier. I left docs/api.yaml untouched to keep this PR scoped; happy to reformat it or add it to .prettierignore in a separate change if you'd like.