View Source Image.Video (image v0.20.0)

Implements functions to extract frames froma video file as images using eVision.

Images can be extracted by frame number of number of milliseconds with:

In order to extract images the video file must first be opened with Image.Video.open/1. At the end of processing the video file should be closed with Image.Video.close/1.

This process can be wrrapped by Image.Video.with_video/2 which will open a video file, execute a function (passing it the video reference) and closing the video file at the end of the function.

Link to this section Summary

Functions

Closes a video.

Closes a video or raises an exception.

Extracts a frame at a given millisecond offset of the a video and returns an image.

Extracts a frame at a given millisecond offset of the a video and returns an image or raises an exception.

Extracts a frame from a video and returns an image.

Extracts a frame from a video and returns an image or raises an exception.

Guards that a frame offset is valid for a video

Guards that a millisecond count is valid for a video

Opens a video file for frame extraction.

Opens a video file for frame extraction or raises an exception.

Opens a video file, calls the given function with the video reference and closes the video after the function returns.

Link to this section Functions

@spec close(Evision.VideoCapture.t()) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Closes a video.

arguments

Arguments

returns

Returns

  • {:ok, closed_video} or

  • {:error, reason}

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> Image.Video.close(video)

Closes a video or raises an exception.

arguments

Arguments

returns

Returns

  • closed_video or

  • raises an exception.

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> Image.Video.close!(video)
Link to this function

image_at_millisecond(video, millis)

View Source
@spec image_at_millisecond(Evision.VideoCapture.t(), non_neg_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Extracts a frame at a given millisecond offset of the a video and returns an image.

arguments

Arguments

  • video is any Evision.VideoCapture.t/0

  • millis is an integer millisecond offset into the video. The first millisecond of a video is frame 0.

returns

Returns

  • {:ok, image} or

  • {:error, reason}

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> {:ok, _image} = Image.Video.image_at_millisecond(video, 0)
iex> {:error, "Milliseconds number must be in the range 0..5189999. Found -1"} =
...>   Image.Video.image_at_millisecond(video, -1)
iex> {:error, "Milliseconds number must be in the range 0..5189999. Found 10000000"} =
...>   Image.Video.image_at_millisecond(video, 10_000_000)
Link to this function

image_at_millisecond!(video, millis)

View Source
@spec image_at_millisecond!(Evision.VideoCapture.t(), non_neg_integer()) ::
  Vix.Vips.Image.t() | no_return()

Extracts a frame at a given millisecond offset of the a video and returns an image or raises an exception.

arguments

Arguments

  • video is any Evision.VideoCapture.t/0

  • millis is an integer millisecond offset into the video. The first millisecond of a video is frame 0.

returns

Returns

  • image or

  • raises an exception.

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

Link to this function

image_from_frame(video, frame)

View Source
@spec image_from_frame(Evision.VideoCapture.t(), non_neg_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error_message()}

Extracts a frame from a video and returns an image.

arguments

Arguments

  • video is any Evision.VideoCapture.t/0

  • frame is an integer frame offset into the video. The first frame of a video is frame 0.

returns

Returns

  • {:ok, image} or

  • {:error, reason}

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

example

Example

iex> {:ok, video} = Image.Video.open "./test/support/video/video_sample.mp4"
iex> {:ok, _image} = Image.Video.image_from_frame(video, 0)
iex> {:error, "Frame number must be in the range 0..172. Found -1"} = Image.Video.image_from_frame(video, -1)
iex> {:error, "Frame number must be in the range 0..172. Found 500"} = Image.Video.image_from_frame(video, 500)
Link to this function

image_from_frame!(video, frame)

View Source
@spec image_from_frame!(Evision.VideoCapture.t(), non_neg_integer()) ::
  Vix.Vips.Image.t() | no_return()

Extracts a frame from a video and returns an image or raises an exception.

arguments

Arguments

  • video is any Evision.VideoCapture.t/0

  • frame is an integer frame offset into the video. The first frame of a video is frame 0.

returns

Returns

  • image or

  • raises an exception

warning

Warning

This frame extraction is NOT atomic. First the read head is set to the frame of interest, then the frame is extracted and decoded. It is possible for another process to interleave its own seek operation resulting in undefined results.

Link to this macro

is_frame(frame, frame_count)

View Source (macro)

Guards that a frame offset is valid for a video

Link to this macro

is_valid_millis(millis, frames, fps)

View Source (macro)

Guards that a millisecond count is valid for a video

@spec open(Path.t()) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Opens a video file for frame extraction.

arguments

Arguments

  • filename is the filename of a video file

returns

Returns

  • {:ok, video} or

  • {:error, reason}

example

Example

iex> Image.Video.open "./test/support/video/video_sample.mp4"
@spec open!(Path.t()) :: Evision.VideoCapture.t() | no_return()

Opens a video file for frame extraction or raises an exception.

arguments

Arguments

  • filename is the filename of a video file

returns

Returns

  • video or

  • raises an exception

example

Example

iex> Image.Video.open! "./test/support/video/video_sample.mp4"
Link to this function

with_video(filename, fun)

View Source
@spec with_video(filename :: Path.t(), (Evision.VideoCapture.t() -> any())) ::
  {:ok, Evision.VideoCapture.t()} | {:error, Image.error_message()}

Opens a video file, calls the given function with the video reference and closes the video after the function returns.

arguments

Arguments

  • filename is the filename of a video file

returns

Returns

  • {:ok, video} or

  • {:error, reason}

example

Example

iex> Image.Video.with_video "./test/support/video/video_sample.mp4", fn video ->
...>  Image.Video.image_from_frame(video, 1)
...> end