From e19f02edbfeccc874d73d7a33c203600089a2f23 Mon Sep 17 00:00:00 2001
From: Dmitry Sergeev <mrjitten@protonmail.com>
Date: Thu, 27 Aug 2026 09:07:48 +0300
Subject: [PATCH] define video playback contracts

---
 internal/playback/video.go | 40 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 internal/playback/video.go

diff --git a/internal/playback/video.go b/internal/playback/video.go
new file mode 100644
index 0000000..16500b8
--- /dev/null
+++ b/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
+}