class_docstr: Support for pyAV as backend.
  
  Parameters
  ----------
  request : iio.Request
      A request object that represents the users intent. It provides a
      standard interface to access various the various ImageResources and
      serves them to the plugin as a file object (or file). Check the docs for
      details.
class_docstr_tok: ["Support","for","pyAV","as","backend",".","Parameters","--","--","--","--","--","request",":","iio.Request","A","request","object","that","represents","the","users","intent",".","It","provides","a","standard","interface","to","access","various","the","various","ImageResources","and","serves","them","to","the","plugin","as","a","file","object","(","or","file",")",".","Check","the","docs","for","details","."]
docstr: Read frames from the video.
  
  If ``index`` is an integer, this function reads the index-th frame from
  the file. If ``index`` is ... (Ellipsis), this function reads all frames
  from the video, stacks them along the first dimension, and returns a
  batch of frames.
  
  Parameters
  ----------
  index : int
      The index of the frame to read, e.g. ``index=5`` reads the 5th
      frame. If ``...``, read all the frames in the video and stack them
      along a new, prepended, batch dimension.
  format : str
      Set the returned colorspace. If not None (default: rgb24), convert
      the data into the given format before returning it. If ``None``
      return the data in the encoded format if it can be expressed as a
      strided array; otherwise raise an Exception.
  filter_sequence : List[str, str, dict]
      If not None, apply the given sequence of FFmpeg filters to each
      ndimage. Check the (module-level) plugin docs for details and
      examples.
  filter_graph : (dict, List)
      If not None, apply the given graph of FFmpeg filters to each
      ndimage. The graph is given as a tuple of two dicts. The first dict
      contains a (named) set of nodes, and the second dict contains a set
      of edges between nodes of the previous dict. Check the (module-level)
      plugin docs for details and examples.
  constant_framerate : bool
      If True assume the video's framerate is constant. This allows for
      faster seeking inside the file. If False, the video is reset before
      each read and searched from the beginning. If None (default), this
      value will be read from the container format.
  thread_count : int
      How many threads to use when decoding a frame. The default is 0,
      which will set the number using ffmpeg's default, which is based on
      the codec, number of available cores, threadding model, and other
      considerations.
  thread_type : str
      The threading model to be used. One of
  
      - `"SLICE"`: threads assemble parts of the current frame
      - `"FRAME"`: threads may assemble future frames
      - None (default): Uses ``"FRAME"`` if ``index=...`` and ffmpeg's
        default otherwise.
  
  
  Returns
  -------
  frame : np.ndarray
      A numpy array containing loaded frame data.
  
  Notes
  -----
  Accessing random frames repeatedly is costly (O(k), where k is the
  average distance between two keyframes). You should do so only sparingly
  if possible. In some cases, it can be faster to bulk-read the video (if
  it fits into memory) and to then access the returned ndarray randomly.
  
  The current implementation may cause problems for b-frames, i.e.,
  bidirectionaly predicted pictures. I lack test videos to write unit
  tests for this case.
  
  Reading from an index other than ``...``, i.e. reading a single frame,
  currently doesn't support filters that introduce delays.
docstr_tok: ["Read","frames","from","the","video",".","If","``","index","``","is","an","integer",",","this","function","reads","the","index-th","frame","from","the","file",".","If","``","index","``","is","...","(","Ellipsis",")",",","this","function","reads","all","frames","from","the","video",",","stacks","them","along","the","first","dimension",",","and","returns","a","batch","of","frames",".","Parameters","--","--","--","--","--","index",":","int","The","index","of","the","frame","to","read",",","e.g",".","``","index=5","``","reads","the","5th","frame",".","If","``","...","``",",","read","all","the","frames","in","the","video","and","stack","them","along","a","new",",","prepended",",","batch","dimension",".","format",":","str","Set","the","returned","colorspace",".","If","not","None","(","default",":","rgb24",")",",","convert","the","data","into","the","given","format","before","returning","it",".","If","``","None","``","return","the","data","in","the","encoded","format","if","it","can","be","expressed","as","a","strided","array",";","otherwise","raise","an","Exception",".","filter_sequence",":","List","[","str",",","str",",","dict","]","If","not","None",",","apply","the","given","sequence","of","FFmpeg","filters","to","each","ndimage",".","Check","the","(","module-level",")","plugin","docs","for","details","and","examples",".","filter_graph",":","(","dict",",","List",")","If","not","None",",","apply","the","given","graph","of","FFmpeg","filters","to","each","ndimage",".","The","graph","is","given","as","a","tuple","of","two","dicts",".","The","first","dict","contains","a","(","named",")","set","of","nodes",",","and","the","second","dict","contains","a","set","of","edges","between","nodes","of","the","previous","dict",".","Check","the","(","module-level",")","plugin","docs","for","details","and","examples",".","constant_framerate",":","bool","If","True","assume","the","video","'s","framerate","is","constant",".","This","allows","for","faster","seeking","inside","the","file",".","If","False",",","the","video","is","reset","before","each","read","and","searched","from","the","beginning",".","If","None","(","default",")",",","this","value","will","be","read","from","the","container","format",".","thread_count",":","int","How","many","threads","to","use","when","decoding","a","frame",".","The","default","is","0",",","which","will","set","the","number","using","ffmpeg","'s","default",",","which","is","based","on","the","codec",",","number","of","available","cores",",","threadding","model",",","and","other","considerations",".","thread_type",":","str","The","threading","model","to","be","used",".","One","of","-","`","``","SLICE","''","`",":","threads","assemble","parts","of","the","current","frame","-","`","``","FRAME","''","`",":","threads","may","assemble","future","frames","-","None","(","default",")",":","Uses","``","``","FRAME","''","``","if","``","index=","...","``","and","ffmpeg's","default","otherwise",".","Returns","--","--","--","-","frame",":","np.ndarray","A","numpy","array","containing","loaded","frame","data",".","Notes","--","--","-","Accessing","random","frames","repeatedly","is","costly","(","O","(","k",")",",","where","k","is","the","average","distance","between","two","keyframes",")",".","You","should","do","so","only","sparingly","if","possible",".","In","some","cases",",","it","can","be","faster","to","bulk-read","the","video","(","if","it","fits","into","memory",")","and","to","then","access","the","returned","ndarray","randomly",".","The","current","implementation","may","cause","problems","for","b-frames",",","i.e.",",","bidirectionaly","predicted","pictures",".","I","lack","test","videos","to","write","unit","tests","for","this","case",".","Reading","from","an","index","other","than","``","...","``",",","i.e",".","reading","a","single","frame",",","currently","does","n't","support","filters","that","introduce","delays","."]
code: def read(
      self,
      *,
      index: int = ...,
      format: str = "rgb24",
      filter_sequence: List[Tuple[str, Union[str, dict]]] = None,
      filter_graph: Tuple[dict, List] = None,
      constant_framerate: bool = None,
      thread_count: int = 0,
      thread_type: str = None,
  ) -> np.ndarray:
      """Read frames from the video.
  
      If ``index`` is an integer, this function reads the index-th frame from
      the file. If ``index`` is ... (Ellipsis), this function reads all frames
      from the video, stacks them along the first dimension, and returns a
      batch of frames.
  
      Parameters
      ----------
      index : int
          The index of the frame to read, e.g. ``index=5`` reads the 5th
          frame. If ``...``, read all the frames in the video and stack them
          along a new, prepended, batch dimension.
      format : str
          Set the returned colorspace. If not None (default: rgb24), convert
          the data into the given format before returning it. If ``None``
          return the data in the encoded format if it can be expressed as a
          strided array; otherwise raise an Exception.
      filter_sequence : List[str, str, dict]
          If not None, apply the given sequence of FFmpeg filters to each
          ndimage. Check the (module-level) plugin docs for details and
          examples.
      filter_graph : (dict, List)
          If not None, apply the given graph of FFmpeg filters to each
          ndimage. The graph is given as a tuple of two dicts. The first dict
          contains a (named) set of nodes, and the second dict contains a set
          of edges between nodes of the previous dict. Check the (module-level)
          plugin docs for details and examples.
      constant_framerate : bool
          If True assume the video's framerate is constant. This allows for
          faster seeking inside the file. If False, the video is reset before
          each read and searched from the beginning. If None (default), this
          value will be read from the container format.
      thread_count : int
          How many threads to use when decoding a frame. The default is 0,
          which will set the number using ffmpeg's default, which is based on
          the codec, number of available cores, threadding model, and other
          considerations.
      thread_type : str
          The threading model to be used. One of
  
          - `"SLICE"`: threads assemble parts of the current frame
          - `"FRAME"`: threads may assemble future frames
          - None (default): Uses ``"FRAME"`` if ``index=...`` and ffmpeg's
            default otherwise.
  
  
      Returns
      -------
      frame : np.ndarray
          A numpy array containing loaded frame data.
  
      Notes
      -----
      Accessing random frames repeatedly is costly (O(k), where k is the
      average distance between two keyframes). You should do so only sparingly
      if possible. In some cases, it can be faster to bulk-read the video (if
      it fits into memory) and to then access the returned ndarray randomly.
  
      The current implementation may cause problems for b-frames, i.e.,
      bidirectionaly predicted pictures. I lack test videos to write unit
      tests for this case.
  
      Reading from an index other than ``...``, i.e. reading a single frame,
      currently doesn't support filters that introduce delays.
  
      """
  
      if index is ...:
          props = self.properties(format=format)
          uses_filter = (
              self._video_filter is not None
              or filter_graph is not None
              or filter_sequence is not None
          )
  
          self._container.seek(0)
          if not uses_filter and props.shape[0] != 0:
              frames = np.empty(props.shape, dtype=props.dtype)
              for idx, frame in enumerate(
                  self.iter(
                      format=format,
                      filter_sequence=filter_sequence,
                      filter_graph=filter_graph,
                      thread_count=thread_count,
                      thread_type=thread_type or "FRAME",
                  )
              ):
                  frames[idx] = frame
          else:
              frames = np.stack(
                  [
                      x
                      for x in self.iter(
                          format=format,
                          filter_sequence=filter_sequence,
                          filter_graph=filter_graph,
                          thread_count=thread_count,
                          thread_type=thread_type or "FRAME",
                      )
                  ]
              )
  
          # reset stream container, because threading model can't change after
          # first access
          self._video_stream.close()
          self._video_stream = self._container.streams.video[0]
  
          return frames
  
      if (
          thread_type is not None
          and thread_type != self._video_stream.thread_type
      ):
          self._video_stream.thread_type = thread_type
      if (
          thread_count != 0
          and thread_count
          != self._video_stream.codec_context.thread_count
      ):
          # in FFMPEG thread_count == 0 means use the default count, which we
          # change to mean don't change the thread count.
          self._video_stream.codec_context.thread_count = thread_count
  
      if constant_framerate is None:
          constant_framerate = not self._container.format.variable_fps
  
      # note: cheap for contigous incremental reads
      self._seek(index, constant_framerate=constant_framerate)
      desired_frame = next(self._decoder)
      self._next_idx += 1
  
      self.set_video_filter(filter_sequence, filter_graph)
      if self._video_filter is not None:
          desired_frame = self._video_filter.send(desired_frame)
  
      return self._unpack_frame(desired_frame, format=format)
  
imports: from fractions import Fraction
  from math import ceil
  from typing import Any, Dict, List, Optional, Tuple, Union, Generator
  import av
  import av.filter
  import numpy
  from numpy.lib.stride_tricks import as_strided
  from ..core import Request
  from ..core.request import URI_BYTES, InitializationError, IOMode
  from ..core.v3_plugin_api import ImageProperties, PluginV3
label_desc: Use image node_id 2 for calling the PyAVPlugin obj's underlying member method code with example usage: obj.read() and returns: self, frames