labthings_fastapi.outputs.mjpeg_stream
======================================

.. py:module:: labthings_fastapi.outputs.mjpeg_stream

.. autoapi-nested-parse::

   MJPEG Stream support.

   This module defines a descriptor that allows `.Thing` subclasses to expose an
   MJPEG stream. See `.MJPEGStreamDescriptor`.



Classes
-------

.. autoapisummary::

   labthings_fastapi.outputs.mjpeg_stream.RingbufferEntry
   labthings_fastapi.outputs.mjpeg_stream.MJPEGStreamResponse


Module Contents
---------------

.. py:class:: RingbufferEntry

   A single entry in a ringbuffer.

   This structure comprises one frame as a JPEG, plus a timestamp and
   a buffer index. Each time a frame is added to the stream, it is
   tagged with a timestamp and index, with the index increasing by
   1 each time.


   .. py:attribute:: frame
      :type:  bytes

      The frame as a `bytes` object, which is a JPEG image for an MJPEG stream.



   .. py:attribute:: timestamp
      :type:  datetime.datetime

      The time the frame was added to the ringbuffer.



   .. py:attribute:: index
      :type:  int

      The index of the frame within the stream.



.. py:class:: MJPEGStreamResponse(gen: AsyncGenerator[bytes, None], status_code: int = 200)

   Bases: :py:obj:`fastapi.responses.StreamingResponse`


   A StreamingResponse that streams an MJPEG stream.

   This response uses an async generator that yields `bytes`
   objects, each of which is a JPEG file. We add the --frame markers and mime
   types that mark it as an MJPEG stream. This is sufficient to enable it to
   work in an `img` tag, with the `src` set to the MJPEG stream's endpoint.

   Set up StreamingResponse that streams an MJPEG stream.

   This response is initialised with an async generator that yields `bytes`
   objects, each of which is a JPEG file. We add the --frame markers and mime
   types that mark it as an MJPEG stream. This is sufficient to enable it to
   work in an `img` tag, with the `src` set to the MJPEG stream's endpoint.

   It expects an async generator that supplies individual JPEGs to be streamed,
   such as the one provided by `.MJPEGStream`.

   NB the ``status_code`` argument is used by FastAPI to set the status code of
   the response in OpenAPI.

   :param gen: an async generator, yielding `bytes` objects each of which is
       one image, in JPEG format.
   :param status_code: The status code associated with the response, by default
       a 200 code is returned.


   .. py:attribute:: media_type
      :value: 'multipart/x-mixed-replace; boundary=frame'


      The media_type used to describe the endpoint in FastAPI.



   .. py:attribute:: frame_async_generator


   .. py:method:: mjpeg_async_generator() -> AsyncGenerator[bytes, None]
      :async:


      Return a generator yielding an MJPEG stream.

      This async generator wraps each incoming JPEG frame with the
      ``--frame`` separator and content type header. It is the basis
      of the response sent over HTTP (see ``__init__``).

      :yield: JPEG frames, each with a ``--frame`` marker prepended.