domain

type AVCodec uint8

type AVPacket struct {
	Codec         AVCodec
	Data          []byte
	PTSms         uint64
	DTSms         uint64
	KeyFrame      bool
	Discontinuity bool
}

type AudioCodec string

type AudioConfig struct {
	Codec AudioCodec `json:"codec" yaml:"codec"`

	// Bitrate is the audio bitrate in kbps. Typical: 128 (stereo), 192 (high quality).
	Bitrate int `json:"bitrate" yaml:"bitrate"`

	// SampleRate is the output sample rate in Hz. Typical: 44100, 48000.
	SampleRate int `json:"sample_rate" yaml:"sample_rate"`

	// Channels: 1 = mono, 2 = stereo, 6 = 5.1 surround.
	Channels int `json:"channels" yaml:"channels"`

	// Language is the ISO 639-1 code embedded in HLS/DASH metadata, e.g. "en", "vi".
	Language string `json:"language" yaml:"language"`

	// Normalize applies EBU R128 loudness normalization (-23 LUFS).
	// Useful for broadcast compliance.
	Normalize bool `json:"normalize" yaml:"normalize"`
}

type AudioTranscodeConfig struct {
	// Copy copies origin audio without re-encoding.
	Copy bool `json:"copy" yaml:"copy"`

	Codec AudioCodec `json:"codec" yaml:"codec"`

	// Bitrate is the audio bitrate in kbps.
	Bitrate int `json:"bitrate" yaml:"bitrate"`

	// SampleRate is output sample rate in Hz.
	SampleRate int `json:"sample_rate" yaml:"sample_rate"`

	// Channels: 1 = mono, 2 = stereo, 6 = 5.1.
	Channels int `json:"channels" yaml:"channels"`

	// Language is ISO 639-1 code, e.g. "en", "vi".
	Language string `json:"language" yaml:"language"`

	// Normalize applies EBU R128 loudness normalization.
	Normalize bool `json:"normalize" yaml:"normalize"`
}

type CopyShapeError struct {
	StreamCode StreamCode
	Reason     string
}

type DVRGap struct {
	From     time.Time     `json:"from" yaml:"from"`         // wall time gap started
	To       time.Time     `json:"to" yaml:"to"`             // wall time recording resumed
	Duration time.Duration `json:"duration" yaml:"duration"` // To - From
}

type DVRIndex struct {
	StreamCode    StreamCode `json:"stream_code" yaml:"stream_code"`
	StartedAt     time.Time  `json:"started_at" yaml:"started_at"`
	LastSegmentAt time.Time  `json:"last_segment_at,omitempty" yaml:"last_segment_at,omitempty"`

	SegmentCount   int   `json:"segment_count" yaml:"segment_count"`
	TotalSizeBytes int64 `json:"total_size_bytes" yaml:"total_size_bytes"`

	// Gaps is the list of known signal-loss / server-restart interruptions.
	Gaps []DVRGap `json:"gaps,omitempty" yaml:"gaps,omitempty"`
}

type DecoderConfig struct {
	// Name is the FFmpeg decoder name.
	// "" = let FFmpeg choose automatically.
	// Examples: "h264_cuvid", "h264_qsv".
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
}

type ErrorEntry struct {
	Message string    `json:"message"`
	At      time.Time `json:"at"`
}

type Event struct {
	ID         string         `json:"id"` // UUID for idempotent delivery
	Type       EventType      `json:"type"`
	StreamCode StreamCode     `json:"stream_code"`
	OccurredAt time.Time      `json:"occurred_at"`
	Payload    map[string]any `json:"payload,omitempty"` // event-specific fields
}

type EventType string

type GlobalConfig struct {
	Server     *config.ServerConfig     `json:"server,omitempty" yaml:"server,omitempty"`
	Listeners  *config.ListenersConfig  `json:"listeners,omitempty" yaml:"listeners,omitempty"`
	Ingestor   *config.IngestorConfig   `json:"ingestor,omitempty" yaml:"ingestor,omitempty"`
	Buffer     *config.BufferConfig     `json:"buffer,omitempty" yaml:"buffer,omitempty"`
	Transcoder *config.TranscoderConfig `json:"transcoder,omitempty" yaml:"transcoder,omitempty"`
	Publisher  *config.PublisherConfig  `json:"publisher,omitempty" yaml:"publisher,omitempty"`
	Manager    *config.ManagerConfig    `json:"manager,omitempty" yaml:"manager,omitempty"`
	Hooks      *config.HooksConfig      `json:"hooks,omitempty" yaml:"hooks,omitempty"`
	Sessions   *config.SessionsConfig   `json:"sessions,omitempty" yaml:"sessions,omitempty"`
	Watermarks *config.WatermarksConfig `json:"watermarks,omitempty" yaml:"watermarks,omitempty"`
	Log        *config.LogConfig        `json:"log,omitempty" yaml:"log,omitempty"`
}

type HWAccel string

type Hook struct {
	ID     HookID   `json:"id" yaml:"id"`
	Name   string   `json:"name" yaml:"name"`
	Type   HookType `json:"type" yaml:"type"`
	Target string   `json:"target" yaml:"target"` // HTTP(S) URL or absolute file path
	Secret string   `json:"secret" yaml:"secret"` // HMAC-SHA256 signing secret (HTTP only)

	// EventTypes filters which events trigger delivery. Empty = all events.
	EventTypes []EventType `json:"event_types,omitempty" yaml:"event_types,omitempty"`

	// StreamCodes filters delivery by stream code.
	// Only and Except are mutually exclusive; Only takes precedence when both are set.
	// Omitting the field (nil) means all streams are included.
	StreamCodes *StreamCodeFilter `json:"stream_codes,omitempty" yaml:"stream_codes,omitempty"`

	// Metadata holds user-defined key-value pairs merged into every event payload
	// delivered by this hook. Useful for tagging events with custom context
	// (e.g. environment, tenant ID, region) without modifying the server config.
	Metadata map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	Enabled bool `json:"enabled" yaml:"enabled"`

	// MaxRetries is the number of delivery attempts before giving up.
	// 0 means use the server default (3). For HTTP hooks this caps retries
	// inside a single batch flush; events that still fail are re-queued
	// for the next flush regardless of MaxRetries.
	MaxRetries int `json:"max_retries" yaml:"max_retries"`

	// TimeoutSec is the per-attempt delivery timeout in seconds.
	// 0 means use the server default (10s).
	TimeoutSec int `json:"timeout_sec" yaml:"timeout_sec"`

	// BatchMaxItems caps the number of events bundled into one HTTP POST
	// body. 0 = use HooksConfig.BatchMaxItems, then DefaultHookBatchMaxItems.
	// Ignored for File hooks (they always write one event per line).
	BatchMaxItems int `json:"batch_max_items,omitempty" yaml:"batch_max_items,omitempty"`

	// BatchFlushIntervalSec is the maximum time a batch may sit before being
	// flushed even when below BatchMaxItems. 0 = use HooksConfig default,
	// then DefaultHookBatchFlushIntervalSec.
	BatchFlushIntervalSec int `json:"batch_flush_interval_sec,omitempty" yaml:"batch_flush_interval_sec,omitempty"`

	// BatchMaxQueueItems caps the per-hook in-memory queue (pending +
	// re-queued failures). When exceeded, the OLDEST events are dropped
	// with a warning log so the queue never grows unbounded against an
	// unreachable target. 0 = use HooksConfig default, then
	// DefaultHookBatchMaxQueueItems.
	BatchMaxQueueItems int `json:"batch_max_queue_items,omitempty" yaml:"batch_max_queue_items,omitempty"`
}

type HookID string

type HookType string

type Input struct {
	// URL is the source endpoint. See the package doc for supported formats.
	URL string `json:"url" yaml:"url"`

	// Priority determines failover order. Lower value = higher priority.
	// The Stream Manager always prefers the lowest-priority alive input.
	Priority int `json:"priority" yaml:"priority"`

	// Headers are arbitrary HTTP headers sent with every request for HTTP/HLS inputs.
	// Common uses:
	//   "Authorization": "Bearer <token>"
	//   "Authorization": "Basic <base64(user:pass)>"
	//   "X-Custom-Token": "secret"
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`

	// Params are extra URL query parameters merged into the source URL before
	// connecting. Used for protocols that carry credentials or options in the
	// query string (SRT ?passphrase=, S3 ?access_key= / ?secret_key=, etc.).
	//   "passphrase": "my-srt-passphrase"
	//   "access_key": "AKID..."   (S3)
	//   "secret_key": "wJal..."   (S3)
	Params map[string]string `json:"params,omitempty" yaml:"params,omitempty"`

	// Program selects a single MPEG-TS program when the source is a
	// multi-program transport stream (MPTS) — common in DVB headend feeds
	// where one multicast carries many channels. When > 0, the ingest
	// pipeline rewrites the PAT to advertise only the chosen program and
	// drops PMT / ES packets belonging to other programs, producing a
	// clean SPTS for downstream HLS / DASH / push consumers.
	//
	// Zero (default) disables filtering — the entire stream is forwarded
	// unchanged. Currently applies to UDP only; HLS / SRT / File ingest
	// are SPTS by convention so the filter is not wired for those (extend
	// reader.go if a real MPTS file/SRT use case arises). Ignored for
	// RTSP / RTMP, which are single-program by protocol design.
	Program int `json:"program,omitempty" yaml:"program,omitempty"`

	// Pids is an explicit allowlist of TS PIDs to keep — every other PID
	// is dropped at ingest. Used when the source PSI is unreliable (legacy
	// encoders with malformed PAT/PMT) or when the operator wants to cherry-
	// pick a subset (e.g. drop a teletext PID, keep only one of N audio
	// languages). The filter is purely PID-level: no PAT/PMT rewrite, no
	// CRC recompute. Operators must include every PID needed for playback
	// (typically PID 0 for PAT, the PMT PID, and the desired ES PIDs).
	//
	// Layers with Program when both are set: Program runs first (auto-
	// detect ES PIDs + rewrite PAT to single-program), then Pids further
	// restricts the output. Empty (default) disables the filter.
	//
	// Currently applies to UDP only — same rationale as Program.
	Pids []int `json:"pids,omitempty" yaml:"pids,omitempty"`

	// Net controls reconnect and timeout behaviour.
	Net InputNetConfig `json:"net,omitempty" yaml:"net,omitempty"`

	// Alive is a runtime-only field updated by the Stream Manager health checker.
	// Not persisted to storage.
	Alive bool `json:"-" yaml:"-"`
}

type InputNetConfig struct {
	// TimeoutSec is the per-protocol operation budget the reader applies
	// when this input is opened. Semantics differ by protocol:
	//
	//   - HLS:  HTTP request timeout (entire round-trip incl. body) for
	//           the playlist GET. Segment GETs derive from this — typically
	//           4× the playlist budget, floored at the segment default.
	//   - RTMP: TCP dial timeout (handshake budget).
	//   - RTSP: dial + initial read timeout (until first packet).
	//   - SRT:  connection / handshake timeout.
	//
	// Zero uses the reader's per-protocol default
	// (DefaultHLSPlaylistTimeoutSec for HLS; DefaultRTMPTimeoutSec /
	// DefaultRTSPTimeoutSec for the rest).
	TimeoutSec int `json:"timeout_sec,omitempty" yaml:"timeout_sec,omitempty"`

	// InsecureTLS disables TLS certificate verification for HTTPS pulls
	// (HLS playlist + segment GETs). Default false — leave secure-by-default
	// for production. Use only when the source uses a self-signed,
	// expired, or otherwise-invalid certificate that you trust at the
	// network level (private VLAN, fixed IP allowlist).
	InsecureTLS bool `json:"insecure_tls,omitempty" yaml:"insecure_tls,omitempty"`
}

type InterlaceMode string

type MediaTrackInfo struct {
	Kind        MediaTrackKind `json:"kind"`
	Codec       string         `json:"codec"`            // "h264" | "h265" | "aac" | "mp2a"
	Width       int            `json:"width,omitempty"`  // video only
	Height      int            `json:"height,omitempty"` // video only
	BitrateKbps int            `json:"bitrate_kbps"`
}

type MediaTrackKind string

type MixerShapeError struct {
	StreamCode StreamCode
	Reason     string
}

type OutputProtocols struct {
	// HLS enables Apple HTTP Live Streaming (m3u8 + segments over HTTP).
	// Compatible with browsers, iOS, Android, Smart TVs.
	HLS bool `json:"hls" yaml:"hls"`

	// DASH enables MPEG-DASH packaging over HTTP.
	// Required for Widevine/PlayReady DRM.
	DASH bool `json:"dash" yaml:"dash"`

	// RTSP opens an RTSP listener for pull clients (VLC, broadcast tools).
	RTSP bool `json:"rtsp" yaml:"rtsp"`

	// RTMP opens an RTMP publish endpoint for legacy players/CDNs.
	RTMP bool `json:"rtmp" yaml:"rtmp"`

	// SRT opens an SRT listener port for contribution-quality pull.
	SRT bool `json:"srt" yaml:"srt"`

	// MPEGTS exposes raw MPEG-TS over chunked HTTP at /<code>/mpegts —
	// the lowest-latency relay path between Open-Streamer instances (and
	// any HTTP client that can consume chunked TS, e.g. ffmpeg / VLC).
	// Latency is bounded only by network RTT and one buffer-hub chunk
	// (typically 50–200 ms vs 4–10 s for HLS / DASH).
	//
	// No goroutine is started per-stream; the endpoint subscribes to the
	// playback buffer on demand. Disabling the flag turns the endpoint
	// into a 404 for that stream so operators can opt out per-stream
	// without changing the global router.
	MPEGTS bool `json:"mpegts" yaml:"mpegts"`
}

type PlaySession struct {
	// ID uniquely identifies the session across the server's lifetime. For
	// segment protocols (HLS/DASH) it is the deterministic fingerprint hash
	// (so reconnects within the idle window collapse onto one session); for
	// connection-bound protocols (RTMP/SRT/RTSP) it is a random UUID.
	ID string `json:"id"`

	// StreamCode is the foreign key to Stream.Code.
	StreamCode StreamCode `json:"stream_code"`

	// Protocol is the wire protocol used to deliver this session.
	Protocol SessionProto `json:"proto"`

	// IP is the remote peer address (no port). For HTTP-based protocols this
	// is the X-Forwarded-For head when present, otherwise the RemoteAddr.
	IP string `json:"ip"`

	// UserAgent is the browser/player User-Agent (HTTP) or the equivalent
	// flashVer field for RTMP. May be empty.
	UserAgent string `json:"user_agent,omitempty"`

	// Referer is the HTTP Referer when present (HLS/DASH only).
	Referer string `json:"referer,omitempty"`

	// QueryString is the raw query of the FIRST request that opened the
	// session (HLS/DASH) — useful when token/abr-variant info is encoded there.
	QueryString string `json:"query_string,omitempty"`

	// Token is the value of `?token=` from the first request, when present.
	// When set, NamedBy is SessionNamedByToken.
	Token string `json:"token,omitempty"`

	// UserName is a human label. Resolved from token claims if available,
	// otherwise the fingerprint hash short form. Empty when no identity could
	// be resolved.
	UserName string `json:"user_name,omitempty"`

	// NamedBy records how UserName was resolved.
	NamedBy SessionNamedBy `json:"named_by,omitempty"`

	// Country is an ISO 3166-1 alpha-2 country code from the configured
	// GeoIP resolver, or "" when GeoIP is disabled / lookup failed.
	Country string `json:"country,omitempty"`

	// Bytes is the cumulative bytes sent to this client since session open.
	// HLS/DASH: sum of segment + manifest response bodies. RTMP/SRT: write
	// bytes from the publisher's outbound pipeline.
	Bytes int64 `json:"bytes"`

	// Secure is true when the underlying transport was TLS / SRTS / RTMPS.
	Secure bool `json:"secure"`

	// DVR is true when playback originated from the DVR window (timeshift),
	// false for live edge. Open-Streamer's DVR delivery is not yet routed
	// through here so this is currently always false; field reserved.
	DVR bool `json:"dvr"`

	// OpenedAt is the time the first activity for this session was observed.
	OpenedAt time.Time `json:"opened_at"`

	// StartedAt is when the first byte of media was delivered (segment data
	// for HLS/DASH, first frame after RTMP play handshake). Zero before
	// media flows.
	StartedAt time.Time `json:"started_at,omitempty"`

	// UpdatedAt is the time of the most recent activity. Idle reaper closes
	// sessions whose UpdatedAt is older than (now - idle_timeout).
	UpdatedAt time.Time `json:"updated_at"`

	// ClosedAt is set when the session ends. nil while active.
	ClosedAt *time.Time `json:"closed_at,omitempty"`

	// CloseReason explains why the session ended. Empty while active.
	CloseReason SessionCloseReason `json:"close_reason,omitempty"`
}

type PushDestination struct {
	// URL is the destination ingest endpoint.
	// Supported schemes:
	//   rtmp://  — plain TCP, default port 1935 (e.g. rtmp://a.rtmp.youtube.com/live2/{key})
	//   rtmps:// — TLS-wrapped RTMP, default port 443 (e.g. rtmps://live-api-s.facebook.com:443/rtmp/{key})
	URL string `json:"url" yaml:"url"`

	// Enabled controls whether this destination is active.
	Enabled bool `json:"enabled" yaml:"enabled"`

	// TimeoutSec is the connection/write timeout in seconds.
	TimeoutSec int `json:"timeout_sec" yaml:"timeout_sec"`

	// RetryTimeoutSec is the delay between retry attempts in seconds.
	RetryTimeoutSec int `json:"retry_timeout_sec" yaml:"retry_timeout_sec"`

	// Limit is the maximum number of retry attempts. 0 = unlimited.
	Limit int `json:"limit" yaml:"limit"`

	// Comment is a human-readable note for this destination.
	Comment string `json:"comment" yaml:"comment"`

	// Status is a runtime-only field updated by the publisher.
	// Not persisted to storage.
	Status PushStatus `json:"status,omitempty" yaml:"-"`
}

type PushStatus string

type Recording struct {
	ID         RecordingID     `json:"id" yaml:"id"`
	StreamCode StreamCode      `json:"stream_code" yaml:"stream_code"`
	StartedAt  time.Time       `json:"started_at" yaml:"started_at"`
	StoppedAt  *time.Time      `json:"stopped_at,omitempty" yaml:"stopped_at,omitempty"`
	Status     RecordingStatus `json:"status" yaml:"status"`

	// SegmentDir is the absolute path to the directory holding TS files,
	// playlist.m3u8, and index.json.
	SegmentDir string `json:"segment_dir" yaml:"segment_dir"`
}

type RecordingID string

type RecordingStatus string

type ResizeMode string

type SessionCloseReason string

type SessionNamedBy string

type SessionProto string

type Stream struct {
	// Code is the unique key chosen by the user ([a-zA-Z0-9_]).
	Code StreamCode `json:"code" yaml:"code"`

	Name        string   `json:"name" yaml:"name"`
	Description string   `json:"description" yaml:"description"`
	Tags        []string `json:"tags" yaml:"tags"`

	// StreamKey is used to authenticate RTMP/SRT push ingest.
	StreamKey string `json:"stream_key" yaml:"stream_key"`

	// Status is the runtime lifecycle state.
	// It is never persisted — always computed from the coordinator's in-memory
	// state and overlaid by the API layer before returning responses to clients.
	Status StreamStatus `json:"-" yaml:"-"`

	// Disabled when true excludes the stream from server bootstrap and rejects pipeline Start.
	Disabled bool `json:"disabled" yaml:"disabled"`

	// Inputs are the available ingest sources ordered by Priority.
	// The Stream Manager monitors health and switches between them on failure.
	Inputs []Input `json:"inputs" yaml:"inputs"`

	// Transcoder controls encoding/decoding settings.
	// nil means no transcoding for this stream.
	Transcoder *TranscoderConfig `json:"transcoder,omitempty" yaml:"transcoder,omitempty"`

	// Protocols defines which delivery protocols are opened for this stream.
	// The server opens a listener/packager for each enabled protocol.
	// Protocol-level config (ports, segment duration, CDN URL) lives in server config.
	Protocols OutputProtocols `json:"protocols" yaml:"protocols"`

	// Push is the list of external destinations the server actively pushes to.
	// Each entry defines one push target (YouTube, Facebook, Twitch, CDN relay, etc.).
	Push []PushDestination `json:"push" yaml:"push"`

	// DVR overrides the global DVR settings for this specific stream.
	// If nil, the global config is used (when DVR is enabled globally).
	DVR *StreamDVRConfig `json:"dvr,omitempty" yaml:"dvr,omitempty"`

	// Watermark is an optional text or image overlay applied before encoding.
	Watermark *WatermarkConfig `json:"watermark,omitempty" yaml:"watermark,omitempty"`

	// Thumbnail controls periodic screenshot generation for preview images.
	Thumbnail *ThumbnailConfig `json:"thumbnail,omitempty" yaml:"thumbnail,omitempty"`
}

type StreamCode string

type StreamCodeFilter struct {
	// Only delivers events only for streams in this list.
	Only []StreamCode `json:"only,omitempty" yaml:"only,omitempty"`
	// Except delivers events for all streams except those in this list.
	Except []StreamCode `json:"except,omitempty" yaml:"except,omitempty"`
}

type StreamDVRConfig struct {
	Enabled bool `json:"enabled" yaml:"enabled"`

	// RetentionSec is the retention window in seconds.
	// 0 = keep forever.
	RetentionSec int `json:"retention_sec" yaml:"retention_sec"`

	// SegmentDuration overrides the global segment length in seconds.
	// 0 = use default (4s).
	SegmentDuration int `json:"segment_duration" yaml:"segment_duration"`

	// StoragePath overrides the default DVR root directory for this stream.
	// "" = use "./dvr/{streamCode}".
	StoragePath string `json:"storage_path" yaml:"storage_path"`

	// MaxSizeGB caps total disk usage. Oldest segments pruned when exceeded.
	// 0 = no limit.
	MaxSizeGB float64 `json:"max_size_gb" yaml:"max_size_gb"`
}

type StreamLookup func(StreamCode) (*Stream, bool)

type StreamStatus string

type ThumbnailConfig struct {
	Enabled bool `json:"enabled" yaml:"enabled"`

	// IntervalSec generates one thumbnail every N seconds.
	IntervalSec int `json:"interval_sec" yaml:"interval_sec"`

	// Width and Height of the output thumbnail in pixels.
	// 0 = match source resolution.
	Width  int `json:"width" yaml:"width"`
	Height int `json:"height" yaml:"height"`

	// Quality is the JPEG quality (1–31, lower = better). Default: 5.
	Quality int `json:"quality" yaml:"quality"`

	// OutputDir is relative to the publisher HLS directory.
	// E.g. "thumbnails" → written to {hls_dir}/{stream_code}/thumbnails/thumb.jpg
	OutputDir string `json:"output_dir" yaml:"output_dir"`
}

type TranscoderConfig struct {
	// Mode selects the FFmpeg process topology. Empty = TranscoderModeMulti.
	Mode TranscoderMode `json:"mode,omitempty" yaml:"mode,omitempty"`

	Video   VideoTranscodeConfig   `json:"video" yaml:"video"`
	Audio   AudioTranscodeConfig   `json:"audio" yaml:"audio"`
	Decoder DecoderConfig          `json:"decoder" yaml:"decoder"`
	Global  TranscoderGlobalConfig `json:"global" yaml:"global"`

	// ExtraArgs are raw FFmpeg arguments appended after the generated command.
	// Use with caution — may conflict with generated arguments.
	ExtraArgs []string `json:"extra_args,omitempty" yaml:"extra_args,omitempty"`

	// Watermark is a runtime-only field populated by the coordinator from
	// Stream.Watermark before each transcoder.Start. Not persisted on the
	// transcoder section (json/yaml "-") so the API surface keeps
	// Stream.Watermark as the single source of truth.
	Watermark *WatermarkConfig `json:"-" yaml:"-"`
}

type TranscoderGlobalConfig struct {
	// HW selects the acceleration backend.
	HW HWAccel `json:"hw" yaml:"hw"`

	// FPS sets output framerate. 0 = source/default.
	FPS int `json:"fps" yaml:"fps"`

	// GOP sets keyframe interval in frames. 0 = encoder default.
	GOP int `json:"gop" yaml:"gop"`

	// DeviceID selects hardware device index.
	DeviceID int `json:"deviceid" yaml:"deviceid"`
}

type TranscoderMode string

type VODMount struct {
	Name    VODName `json:"name" yaml:"name"`
	Storage string  `json:"storage" yaml:"storage"`
	Comment string  `json:"comment,omitempty" yaml:"comment,omitempty"`
}

type VODName string

type VideoCodec string

type VideoProfile struct {
	// Width and Height define the output resolution.
	// Set to 0 to keep the source dimensions (Width=0 & Height=0 = no scaling).
	Width  int `json:"width" yaml:"width"`
	Height int `json:"height" yaml:"height"`

	// Bitrate is the target video bitrate in kbps. 0 = encoder auto.
	Bitrate int `json:"bitrate" yaml:"bitrate"`

	// MaxBitrate caps the peak bitrate in kbps (CBR/VBR ceiling). 0 = no cap.
	MaxBitrate int `json:"max_bitrate" yaml:"max_bitrate"`

	// Framerate is the output frame rate (fps). 0 = match source.
	Framerate float64 `json:"framerate" yaml:"framerate"`

	// KeyframeInterval is the GOP size in seconds.
	// Must match or be a multiple of the HLS/DASH segment duration.
	KeyframeInterval int `json:"keyframe_interval" yaml:"keyframe_interval"`

	Codec VideoCodec `json:"codec" yaml:"codec"`

	// Preset controls the encoder speed/quality tradeoff.
	// libx264: "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "veryslow"
	// NVENC:   "p1" (fastest) .. "p7" (highest quality)
	Preset string `json:"preset" yaml:"preset"`

	// Profile controls the H.264/H.265 encoding profile.
	// "baseline" | "main" | "high" (H.264); "main" | "main10" (H.265)
	Profile string `json:"profile" yaml:"profile"`

	// Level controls the H.264/H.265 encoding level.
	// Common: "3.1", "4.0", "4.1", "4.2", "5.0", "5.1"
	Level string `json:"level" yaml:"level"`

	// Bframes is the number of consecutive B-frames the encoder may emit.
	// nil = encoder default; 0 = explicit none (low-latency live);
	// 2-3 = typical VOD; NVENC HW B-ref pyramid is auto-enabled when >0.
	Bframes *int `json:"bframes,omitempty" yaml:"bframes,omitempty"`

	// Refs is the number of reference frames. nil = encoder default.
	// Higher = better compression at cost of CPU/latency. NVENC has its own caps.
	Refs *int `json:"refs,omitempty" yaml:"refs,omitempty"`

	// SAR is the output Sample Aspect Ratio, "N:M". "" = inherit from source.
	// Use "1:1" for square pixels (web); "16:11", "59:54" etc. for anamorphic.
	SAR string `json:"sar,omitempty" yaml:"sar,omitempty"`

	// ResizeMode chooses how the source is fitted to Width/Height.
	// "" defaults to ResizeModePad.
	ResizeMode ResizeMode `json:"resize_mode,omitempty" yaml:"resize_mode,omitempty"`
}

type VideoTranscodeConfig struct {
	// Copy copies origin video without re-encoding.
	Copy bool `json:"copy" yaml:"copy"`

	// Interlace selects the deinterlace pre-filter applied before scaling.
	// Applies once per FFmpeg subprocess (i.e. per profile in the ABR ladder).
	// "" disables the filter; use ResizeModeProgressive to assert progressive source.
	Interlace InterlaceMode `json:"interlace,omitempty" yaml:"interlace,omitempty"`

	// Profiles defines ABR renditions when re-encoding.
	Profiles []VideoProfile `json:"profiles,omitempty" yaml:"profiles,omitempty"`
}

type WatermarkAsset struct {
	// ID is the immutable filesystem-safe identifier (also the on-disk basename).
	ID WatermarkAssetID `json:"id" yaml:"id"`

	// Name is the human display label shown in UIs. Defaults to the upload's
	// original filename when the operator doesn't override.
	Name string `json:"name" yaml:"name"`

	// FileName is the original filename at upload time, preserved for
	// audit / download responses. Includes extension (e.g. "logo.png").
	FileName string `json:"file_name" yaml:"file_name"`

	// ContentType is the MIME type sniffed at upload time
	// (e.g. "image/png", "image/jpeg"). Used for Content-Type on /raw GET.
	ContentType string `json:"content_type" yaml:"content_type"`

	// SizeBytes is the on-disk size of the image. Sidecar JSON is excluded.
	SizeBytes int64 `json:"size_bytes" yaml:"size_bytes"`

	// UploadedAt is the wall-clock UTC time the asset was first stored.
	UploadedAt time.Time `json:"uploaded_at" yaml:"uploaded_at"`
}

type WatermarkAssetID string

type WatermarkConfig struct {
	Enabled bool          `json:"enabled" yaml:"enabled"`
	Type    WatermarkType `json:"type" yaml:"type"`

	// Text is the string to render. Supports strftime directives for live timestamps.
	// E.g. "LIVE %{localtime:%H:%M:%S}"
	Text string `json:"text" yaml:"text"`

	// FontFile is the path to a .ttf/.otf font file.
	// "" = FFmpeg default font.
	FontFile string `json:"font_file" yaml:"font_file"`

	// FontSize in pixels. Default: 24.
	FontSize int `json:"font_size" yaml:"font_size"`

	// FontColor in FFmpeg color syntax. E.g. "white", "#FFFFFF", "white@0.8".
	FontColor string `json:"font_color" yaml:"font_color"`

	// AssetID, when set, references a WatermarkAsset uploaded via the
	// /watermarks API. Coordinator resolves it to an on-disk file path
	// before passing the config to the transcoder. Takes precedence over
	// ImagePath when both are set.
	AssetID WatermarkAssetID `json:"asset_id,omitempty" yaml:"asset_id,omitempty"`

	// ImagePath is the absolute path to a watermark image (PNG with alpha
	// recommended). Use this for assets pre-staged on the host outside the
	// /watermarks library. Mutually exclusive with AssetID.
	ImagePath string `json:"image_path,omitempty" yaml:"image_path,omitempty"`

	// Opacity controls transparency: 0.0 = fully transparent, 1.0 = fully opaque.
	Opacity float64 `json:"opacity" yaml:"opacity"`

	// Position selects how the (X, Y) of the overlay are computed:
	//   - top_left/top_right/bottom_left/bottom_right/center: convenience
	//     anchors. OffsetX/Y act as inward padding from the chosen edge
	//     (Center ignores offsets).
	//   - custom: X / Y below are used as raw FFmpeg expressions —
	//     pixel ints ("100"), expressions ("main_w-overlay_w-50"), or
	//     time-aware fades ("if(gt(t,5),10,-100)") all work.
	Position WatermarkPosition `json:"position" yaml:"position"`

	// OffsetX and OffsetY are pixel offsets from the chosen position edge.
	// Ignored when Position == custom.
	OffsetX int `json:"offset_x" yaml:"offset_x"`
	OffsetY int `json:"offset_y" yaml:"offset_y"`

	// X / Y are raw FFmpeg coordinate expressions used only when Position
	// == custom. Empty string defaults to "0". The exact variables exposed
	// depend on the filter:
	//   - drawtext (text watermark): w/h = frame size, tw/th = text size
	//   - overlay (image watermark):  W/H = main video size, w/h = overlay size
	X string `json:"x,omitempty" yaml:"x,omitempty"`
	Y string `json:"y,omitempty" yaml:"y,omitempty"`

	// Resize, when true, makes the watermark render at a consistent on-screen
	// ratio across every rendition in an ABR ladder. The largest profile
	// renders the asset at its NATIVE pixel size (operators design at the top
	// rendition); smaller profiles shrink the asset by the ratio of their
	// width to the largest profile's width. Pixel-scale fields (FontSize for
	// text, OffsetX/OffsetY for both) shrink with the same factor so corner
	// padding and glyph height stay visually proportional.
	//
	// When false (default), the watermark uses native pixel dimensions and
	// fixed offsets on every profile — appearing larger on lower-resolution
	// renditions because they cover fewer pixels of frame.
	Resize bool `json:"resize,omitempty" yaml:"resize,omitempty"`
}

type WatermarkPosition string

type WatermarkType string