FFmpeg
======

.. toctree::
   :maxdepth: 1
   :caption: Contents:

About
-----

`FFmpeg`_ is a complete, cross-platform solution to record, convert and stream audio and video. The version installed on Discoverer HPC is one `compiled by John Van Sicle`_.

Versions avaiable
-----------------

Supported versions
..................

To check which FFmpeg versions are currently supported on Discoverer, execute on the login node:

.. code-block:: bash

 module avail ffmpeg

User-supported installations
............................

.. important:: Users are welcome to bring and install FFmpeg within their scratch folders, but **those installations will not be supported by the Discoverer HPC team.**

Running FFmpeg as Slurm job
---------------------------

.. warning:: Do not run FFmpeg on the login node. Always use Slurm batch script to invoke FFmpeg from within a job submitted to the queue.

Shown below is a Slurm batch script that handles an AVI video container and transforms the content into MPEG-4 format, after getting rid of the packet B-frames (some old video captures installed in experimental aparature produce such AVI video containers):

.. code:: bash

 #!/bin/bash
 #
 #SBATCH --partition=cn         # Partition
 #SBATCH --job-name=ffmpeg      # Job Name
 #SBATCH --time=01:00:00        # WallTime

 #SBATCH --nodes           1    # Use 1
 #SBATCH --ntasks-per-node 1    # Use 1
 #SBATCH --cpus-per-task   12   # Do not set here more than 12 threads

 #SBATCH -o slurm.%j.out        # STDOUT
 #SBATCH -e slurm.%j.err        # STDERR

 module purge
 module load ffmpeg/latest

 cd $SLURM_SUBMIT_DIR

 # Fixing the problem with the wasteful store of packet B-frames in AVI encoders:
 #
 ffmpeg -i source.avi -codec copy -bsf:v mpeg4_unpack_bframes source.fixed.avi

 # Perform a two-pass encoding:
 #
 ffmpeg -y -i source.fixed.avi -c:v libx264 -b:v 1M -pass 1 -threads ${SLURM_CPUS_PER_TASK} -an -f mp4 /dev/null
 ffmpeg -y -i source.fixed.avi -c:v libx264 -b:v 1M -pass 2 -threads ${SLURM_CPUS_PER_TASK} -c:a aac source.fixed.mp4

Specify the parmeters and resources required for successfully running and completing the job:
 
 - the Slurm partition of compute nodes, based on your project resource reservation (``--partition``)
 - the job name, under which the job will be seen in the queue (``--job-name``)
 - the wall time for running the job (``--time``)
 - the requested numbef of threads (``--cpus-per-task``)

.. note:: FFmpeg has its limit when using threading. So try to vary ``--cpus-per-task`` until obtain some better productivity.

Save the complete Slurm job description as a file, for example ``/discofs/$USER/ffmpeg/run_ffmpeg.batch``, and submit it to the queue:

.. code:: bash

 cd /discofs/$USER/ffmpeg
 sbatch run_ffmpeg.batch

Upon successful submission, the standard output will be directed into the file ``/discofs/$USER/ffmpeg/slurm.%j.out`` (where ``%j`` stands for the Slurm job ID.

Getting help
------------

See :doc:`help`

.. _`FFmpeg`: https://ffmpeg.org/
.. _`compiled by John Van Sicle`: https://johnvansickle.com/ffmpeg/