VideoInterop (video_interop v0.1.0)

Framework-neutral video frame interoperability contract.

Version 0.1 describes owned BEAM binary storage, borrowed Linux DMA-BUF storage, optional acquire sync-file fences, producer leases, and ownership-aware consumer streams. Binary frames use implicit synchronization and no lease. File descriptor integers in Elixir are borrowed and local to one OS process. Native consumers must validate and duplicate every descriptor before retaining it asynchronously.

Summary

Functions

close_consumer(session)

Closes a consumer session with its implementation's idempotent close operation.

consume(session, frame)

Transfers a frame to an opened consumer session and consumes its holder.

open_consumer(consumer, format, opts \\ [])

Opens an ownership-aware consumer session for a validated format.

release(lease)

retain(frame, timeout \\ 5000)

validate(descriptor)

validate(frame, format)

Functions

close_consumer(session)

@spec close_consumer(VideoInterop.ConsumerSession.t()) :: :ok

Closes a consumer session with its implementation's idempotent close operation.

consume(session, frame)

@spec consume(VideoInterop.ConsumerSession.t(), VideoInterop.Frame.t()) ::
  :ok | {:error, term()}

Transfers a frame to an opened consumer session and consumes its holder.

On every normal return the caller must not release the supplied frame. A known caller-owned rejection is released here. A transferred rejection remains the consumer's responsibility. Contract violations raise with ownership unknown rather than guessing and risking double release.

open_consumer(consumer, format, opts \\ [])

@spec open_consumer(term(), VideoInterop.Format.t(), keyword()) ::
  {:ok, VideoInterop.ConsumerSession.t()} | {:error, term()}

Opens an ownership-aware consumer session for a validated format.

owner: defaults to the caller and must be a local PID. Consumer implementations use it to close the stream if its logical owner dies.

release(lease)

@spec release(VideoInterop.Frame.t() | VideoInterop.Lease.t()) :: :ok

retain(frame, timeout \\ 5000)

@spec retain(VideoInterop.Frame.t(), timeout()) ::
  {:ok, VideoInterop.Frame.t()} | {:error, term()}

validate(descriptor)

@spec validate(
  VideoInterop.DMABuf.Descriptor.t()
  | VideoInterop.Frame.t()
  | VideoInterop.Format.t()
) ::
  :ok | {:error, VideoInterop.Validator.reason()}

validate(frame, format)

@spec validate(VideoInterop.Frame.t(), VideoInterop.Format.t()) ::
  :ok | {:error, VideoInterop.Validator.reason()}