.. _SD.Multimedia.AcceleratedDecodeWithFfmpg:

.. include:: /content/swdocs.rsts

.. spelling::
   dec
   dq
   ffmpeg
   nvCodingType
   nvFrame
   nvPacket
   nvv
   req

Accelerated Decode with ffmpeg
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

The NVIDIA ``ffmpeg`` package supports hardware-accelerated decode on |NVIDIA(r)| |Jetson(tm)| device.

An application can use accelerated decode to read video files in the
following elementary formats and container formats and dump them in YUV 420 format:

-  H.264
-  H.265
-  VP8
-  VP9
-  MPEG2
-  MPEG4

.. note::
   The ``ffmpeg`` package does not support MPEG4 container files.

To install the ffmpeg binary package
####################################

-  Enter this command::

      $ sudo apt install ffmpeg

To get source files for the ffmpeg package
##########################################

-  Enter this command::

      $ apt source ffmpeg

To include the ffmpeg library in Jetson Linux builds
####################################################

1. Add the following lines to /etc/apt/sources.list::

   $ echo "deb https://repo.download.nvidia.com/jetson/ffmpeg main main" | sudo tee -a /etc/apt/sources.list
   $ echo "deb-src https://repo.download.nvidia.com/jetson/ffmpeg main main" | sudo tee -a /etc/apt/sources.list

2. Enter this command::

      $ sudo apt update

Decode Functional Flow
######################

This section describes the function flow of the ``ffmpeg`` decoding process:

1.  Call ``nvv4l2dec_init_decoder()`` to create a new V4L2 Video Decoder object on the device node ``/dev/nvhost-nvdec``.

2.  Call ``subscribe_event()`` to subscribe to resolution change events.

3.  Call ``set_output_plane_format()`` to set the format on the output plane.

4.  Call ``capture_thread()`` to start a capture thread.

5.  Call ``set_capture_plane_format()`` to set the format on the capture plane.

6.  Call ``nvv4l2dec_decode()`` to read buffers from ffmpeg and start the decode process.

7.  Call ``nvv4l2dec_decoder_get_frame()`` to get the hardware-accelerated decoded data and pass it to ``ffmpeg`` for dumping.

8.  Call ``nvv4l2dec_decoder_close()`` to destroy the buffers and close the device.

The following table describes the key structure.

============ ==========================================
Element      Description
============ ==========================================
nvPacket     Contains information about input packets.
nvFrame      Contains information about decoded frames.
nvCodingType Specifies a different codec type.
BufferPlane  Holds the buffer plane parameters.
Buffer       Holds the buffer information.
context_t    Defines the decoder context.
============ ==========================================

.. todo::
   What are "elements"? The names suggest that some are structures, some are functions, and one is a data type. Perhaps all of them are just field names, but in that case it’s misleading to give some of them names with the “nv” prefix, some names in camel case, and one a name with the “_t” suffix.

   nvCodingType "Specifies a different codec type." Different from what? Perhaps this just means "Specifies the codec type."

This table describes the key function:

.. todo::

   The parallel wording of this statement and the preceding one implies that the preceding table describes “the key structure” of something, and this one describes the same something’s “key function.” In fact I recognize many of this entry’s “Element” entries as the function names in the functional flow, so this table describes the key functions, i.e. the essential functions. That makes me wonder whether the previous table’s description is also confusingly vague. Can you clarify this, please?

   As separate issues, the table entries generally track the steps in the decode functional flow, but a few functions appear in one place and not in the other. Apart from that, the table and functional flow section appear duplicative. Please clarify what their respective functions are and why their sets of functions are different.

==============================   =================================================
Element                          Description
==============================   =================================================
nvv4l2dec_create_decoder         Creates a new V4L2 Video Decoder object on the
                                 device node ``/dev/nvhost-nvdec``.
------------------------------   -------------------------------------------------
subscribe_event                  Subscribes to resolution change events.
------------------------------   -------------------------------------------------
set_output_plane_format          Sets the format on the output plane.
------------------------------   -------------------------------------------------
req_buffers_on_output_plane      Requests buffers on the output plane to be filled
                                 from the input bit stream.
------------------------------   -------------------------------------------------
dq_buffer                        Dequeues the V4L2 buffer.
------------------------------   -------------------------------------------------
q_buffer                         Queues the V4L2 buffer.
------------------------------   -------------------------------------------------
capture_thread                   Starts the capture thread.
------------------------------   -------------------------------------------------
dq_event                         Dequeues an event reported by the V4L2 device.
------------------------------   -------------------------------------------------
req_buffers_on_capture_plane     Requests buffers on the capture plane.
------------------------------   -------------------------------------------------
set_capture_plane_format         Sets the capture plane format.
==============================   =================================================