define video playback contracts

internal/playback/video.go

@@ -0,0 +1,40 @@
+package playback
+
+import "context"
+
+// VideoFrame contains metadata and borrowed source payload.
+//
+// Payload is valid only until the next VideoReader.ReadVideo call or until the
+// reader is closed. Consumers must finish reading Payload before returning
+// control to the worker
+type VideoFrame struct {
+	Index   uint64
+	Width   uint32
+	Height  uint32
+	Stride  uint32
+	Size    uint32
+	Invalid bool
+	Payload []byte
+}
+
+// VideoReader reads frames from a video source.
+//
+// ReadVideo must not be called again until the previous frame's payload has
+// been consumed.
+type VideoReader interface {
+	ReadVideo(context.Context) (VideoFrame, error)
+	Close() error
+}
+
+// VideoReaderFactory opens a reader for the configured video feed.
+type VideoReaderFactory interface {
+	OpenVideo(context.Context, FeedConfig) (VideoReader, error)
+}
+
+// VideoSink consumes a borrowed video frame.
+//
+// ConsumeVideo must finish using frame.Payload before returning and must never
+// retain it for asynchronous use.
+type VideoSink interface {
+	ConsumeVideo(context.Context, VideoFrame) error
+}