=====================
User Guide
=====================

Allowed inputs
--------------

When uploading a file from your host, you will be able to select files with
the following extensions:

- `mp4`
- `ismv`, `isma`, `ismt`
- `cmfv`, `cmfa`, `cmft`
- `m4s`, `dash`
- `mpd`


When using an input URL, as long as it points to a file, Validator will not
make any assumptions or require the presence of any file extension, it will simply
attempt to parse whatever file the URL points to.

More details on Suites and FileChecks
------------------------------------------
In the :ref:`quickstart` section you have seen how to use Validator with an mp4
(and cmf/ism) file, running a validation suite called "Best Practice".

A `Suite` is a collection of `FileChecks` that can be run on a file of a
specific `Format`. Usually, a suite includes FileChecks that, together, concur
to a common validation scope.

Each FileCheck is specialized in a specific and self-contained task, i.e. 
performing a specific check on a video track, or validating the time scale of
an audio track. As a user, you cannot choose to run only *some* of the
FileChecks belonging to a suite. However, you will notice how the validation
report will show a shorter or longer list of executed FileChecks, depending on
the particular file being analyzed, as if some of the FileChecks sometimes
were skipped.

.. figure:: images/fragmented-report.png
   :alt: Report for a fragmented mp4

   A Validator "Best Practice" suite example report

.. figure:: images/non-fragmented-report.png
   :alt: Shorter report for a fragmented mp4

   Report for the same "Best Practice" suite on another mp4 file. Notice how
   shorter it is.

This can be confusing, however it's absolutely expected. In fact, each
FileCheck is designed so that it is only invoked if the specific mp4 file being
validated contains content relevant to that particular check. 

Some examples: a FileCheck working on audio tracks
will not be invoked at all if the mp4 files doesn't contain one; a FileCheck
performing checks on mp4 fragments will not be invoked if the mp4 is not
fragmented.

Validator's results (console output, web page Job Results section and .txt
report) will reflect this behaviour and only report results from FileChecks
effectively executed. The effect is that the list of FileChecks reported by
Validator for a particular mp4 file can differ from the list reported for
another.

If you want to know the comprehensive list of FileChecks included in each Suite
please refer to `Best Practice technical requirements
<http://docs.unified-streaming.com/best-practice/content-preparation.html>`_.
The same page will give you more details about the specific validations
each FileChecks execute, that may be useful to interpret Validator's results.

Parsing step
--------------
You can notice that the first step of each and every validation suite is
"File Parsing". This is the step where the binary file is read and
analyzed to determine if it is syntactically correct, based on the ISO/IEC
14496-12 and other related standards. 

This step also prepares an in-memory representation of the file, which is
then used by any other subsequent check. Failure in the Parsing phase
means that the mp4 file cannot be read, it is syntactically incorrect and
cannot be validated.

If an input file fails the parsing phase but you feel it should be parsed
correctly, please contact support, attaching the mp4 to reproduce the issue.

Interpreting "Best Practice" Suite Results
------------------------------------------
.. raw:: html

    <style> .red {color:#FF0000; font-weight:bold} </style>
    <style> .yellow {color:#FFA500; font-weight:bold} </style>
    <style> .green {color:#008000; font-weight:bold} </style>
    <style> .blue {color:#0000FF; font-weight:bold} </style>
    <style> .black {color:#000000; font-weight:bold} </style>

.. role:: red
.. role:: yellow
.. role:: green
.. role:: black
.. role:: blue

Every FileCheck is designed to detect two possible categories of issues in the
mp4:

- :red:`MUST FIX` issues: problems that needs to be solved before attempting to use
  the mp4 file for any purpose.
- :yellow:`SHOULD FIX` issues: problems that do not absolutely prevent the usage of the
  mp4 file, however, the reported issue and its consequences must be fully
  understood. It is in any case recommended to solve the issue.

Other messages can be present, not related to issues in the mp4s. In
particular:

- :blue:`INFO` any message reported in this category is there
  for informational purposes only and is never related to an issue.
- :black:`RUNTIME ERROR` if this message appears, it means the filecheck
  crashed at runtime. This is a sign of a bug and you should contact the
  developers about it. Any other results reported by a crashed filecheck
  should be ignored. Notice that the rest of the suite still contains valid
  results.

The presence of such issues influences the final state of the FileCheck. Its
outcome is:

- :red:`(FAIL)`: the check detected at least one MUST FIX issue
- :yellow:`(WARN)`: the check detected at least one SHOULD FIX issue
- :green:`(PASS)`: the check detected no issues
- :black:`(CRASH!)`: if a runtime error occurred

.. _Complete-CLI-Usage:


Getting more details about the mp4 file
------------------------------------------
In the "Job Options" section, you have the chance to select the 

.. figure:: images/include-parsing-webui.png
   :scale: 50%
   :alt: Validator's Web UI option to get Parsing Results

   This option can be turned on to get more details about the mp4's content

A brief summary of the mp4's content will be provided, including some
information on tracks, bitrates and durations.

Sharing results
----------------------------
Once a validation has been run, you can download a report file and share it
with interested 3rd parties.

.. figure:: images/download_share.png
   :alt: Download and Share buttons

If you have validated a publicly available file through a URL, you have an
additional option: you can share a link that 3rd parties can use to run
themselves the same job, with a pre-selected file and suite. Just click on
the ``Get Sharable Link`` button at the bottom of the page or copy/paste
the content of your browser address bar.