ffmpeg

type EncodeOptions struct {
	// PipeFormat, when non-empty, names the demuxer for stdin input
	// ("mpegts"); the caller feeds the source via WithStdin. Used to encode
	// from the local spool: pipes never report EOF until the writer closes,
	// which is what lets ffmpeg consume a still-growing stream.
	PipeFormat string

	// SourceURL is the network input, used when PipeFormat is empty.
	SourceURL *url.URL

	// SourceHeaders are HTTP headers ffmpeg sends when fetching SourceURL
	// (Referer, User-Agent, Cookie, etc. — needed for HLS behind proxies).
	SourceHeaders http.Header

	// SourceContentType is the MIME type of SourceURL. It selects the
	// container-specific input flags (see containerInputArgs). Only consulted
	// for a network source (PipeFormat empty).
	SourceContentType string

	// RWTimeoutMicros is the upstream I/O timeout in microseconds, passed to
	// ffmpeg's -rw_timeout for HTTP(S) input. Ignored for stdin input.
	RWTimeoutMicros int64

	// OutputFormat is ffmpeg's muxer name ("mpegts", "mp4", "hls"). "hls" writes
	// a playlist plus rolling fMP4 segments into the process working directory
	// (see WithWorkDir) rather than a single stream on pipe:1.
	OutputFormat string

	// VideoEncoder re-encodes the video; nil stream-copies it. The encoder
	// carries its own device setup, filters, and flags, so EncodeArgs never
	// branches on the encoder kind. When SubtitleTextFile is set the planner
	// must supply one: drawtext needs decoded frames, so copy is not possible.
	VideoEncoder *Encoder

	// VideoBitrate target when re-encoding video (e.g. "4M"). Ignored when
	// VideoEncoder is nil (copy).
	VideoBitrate string

	// VideoMaxrate is the VBV peak-rate cap (e.g. "4M"), and VideoBufsize the
	// VBV buffer (e.g. "8M"). Together they bound the instantaneous bitrate so a
	// complex scene can't spike past what the renderer decodes and buffers. Both
	// empty leaves the encoder in unbounded ABR. Ignored when VideoEncoder is
	// nil (copy).
	VideoMaxrate string
	VideoBufsize string

	// VideoMaxHeight caps the output height while preserving aspect ratio.
	// 0 keeps the source height. Ignored when VideoEncoder is nil (copy).
	VideoMaxHeight int

	// KeyframeIntervalSec caps the GOP length in seconds via force_key_frames,
	// so a renderer joining mid-stream resyncs within this bound regardless of
	// source fps. 0 leaves the encoder default. Ignored when VideoEncoder is
	// nil (copy): a copied bitstream keeps the source's keyframes.
	KeyframeIntervalSec int

	// AudioCodec is CodecCopy or an encoder name like "aac".
	AudioCodec string

	// AudioBitrate target when re-encoding (e.g. "256k"). Ignored for copy.
	AudioBitrate string

	// AudioSampleRate target when re-encoding (Hz). 0 keeps the source rate.
	AudioSampleRate int

	// AudioChannels target when re-encoding. 0 keeps the source layout. The
	// planner's audio resolver sets this: 2 to downmix to stereo (the floor every
	// renderer decodes), or the source layout capped at the codec's ceiling to
	// keep 5.1/7.1. Ignored for copy.
	AudioChannels int

	// SubtitleTextFile, when non-empty, burns the file's current contents
	// into every frame via drawtext with reload=1: ffmpeg re-opens the file
	// by path before each frame, so an external writer can swap the active
	// subtitle line live (atomic rename only — a failed read kills ffmpeg).
	// The file must exist before ffmpeg starts. Forces a video re-encode.
	// Enabling this routes -progress to fd 3: start the process
	// WithExtraPipe and follow Process.Extra.
	SubtitleTextFile string
}

type Encoder struct {
	Name     string      // -c:v value, e.g. "libx264", "hevc_videotoolbox"
	Codec    media.Codec // the abstract codec produced, independent of the name
	Hardware bool        // GPU-backed: trusted only after a real test encode
	InitArgs []string    // emitted before the input: hardware device setup
	Filters  []string    // appended to the -vf chain: e.g. the GPU upload
	Flags    []string    // encoder-specific -c:v flags: preset, pix_fmt, GOP
}

type Process struct {
	// Stdout is the primary output (pipe:1).
	Stdout io.ReadCloser

	// Extra is the fd-3 output (pipe:3) when started WithExtraPipe;
	// nil otherwise.
	Extra io.ReadCloser
	// contains filtered or unexported fields
}

type PullOptions struct {
	SourceURL         *url.URL
	SourceHeaders     http.Header
	SourceContentType string // MIME type of SourceURL; selects container-specific input flags
	RWTimeoutMicros   int64

	// Verbose selects -loglevel verbose (playlist/segment URLs, connection
	// lines) instead of the default warning level.
	Verbose bool

	// PCM additionally extracts mono s16le audio on fd 3 for the
	// transcriber; start the process WithExtraPipe.
	PCM bool
	// PCMSampleRate is the audio sample rate for the PCM output.
	PCMSampleRate int

	// Live selects live pacing (see pullReadrate constants) instead of VOD.
	Live bool
}

type StartOption func(*startConfig)