Improve Reliability for Video Transcoding

Introduction

Using Warning on Error with Source Media, Retry on Error, and Soft-fail for Outputs can significantly enhance the reliability of your video transcoding jobs. By leveraging these features, you can reduce job failures, optimize workflow efficiency, and improve user satisfaction. Experiment with these settings, monitor their impact, and continuously refine your configurations to achieve the best results in your transcoding operations.

1

Check Warning Messages for Additional Error Details

Qencode provides warning messages with additional details in case issues detected with the transcoding job. This may include errors related to source video decoding, callback endpoints, Low Audio Bitrate, and warnings of soft-fails. This provides better transparency into the transcoding process and enables more efficient troubleshooting.

How It Works

In case any non-fatal issue occurs during job processing a warning is generated. You can get the list of warnings from the /v1/status API method or from the job status provided in the callback request.

Example 1: Issues delivering a callback request

In case callback_url param is specified for a job and client's web server is not reachable or responds with an error, system generates the 'Callback delivery error' warning. You can find the URL callback was sent to, HTTP status code and server response in the warning details.

...
"warnings": [
    {
        "message": "Callback delivery error",
        "details": "Error sending callback to https://yourserver.com/qencode_callback 500: Internal Server Error."
    }
],
...

Example 2: Source media decoding errors

When an error is encountered during encoding, the system tries to decode the source media. Decoding errors usually mean the source media is corrupted. You can also verify it by playing the source media in a video or audio player. In case of any decoding errors are detected the 'Source media decoding error' warning is generated.

...
"warnings": [
    {
        "message": "Source media decode error"
    }
],
...

Types of Warning Messages

Best Practices for Warning Messages

• Regularly review warning logs to identify recurring issues.
• Use warnings to prioritize maintenance on problematic source files.
• Configure alert systems to notify relevant teams of warnings.

2

Enable retry_on_error Parameter

The Retry on Error feature can be enabled to automatically re-attempt a transcoding job if it encounters an error. This reduces the impact of intermittent issues, decreases job failure rates, and reduces management requirements. This results in higher job completion rates and a reduced need for manual intervention.

How It Works

When retry_on_error is set to 1, the job is retried if there is a non-persistent error encountered during encoding process. Temporary network-related issues may trigger a retry, while persistent problems (like corrupted files) may not. Download errors, as well as errors when saving output files to their destination location, do not trigger a retry.
When a job is restarted, the following workflow is triggered:

1. A warning is added to the failed job with the following message:

   An error occurred while processing your job.
   It will be automatically retried with the same parameters in a new job.

2. After new job is started, another warning is added to the failed job with the message:

   Retry on error triggered.

   Warning details contain the new job ID.
3. A special callback with 'restarted' event is sent for the failed job, including all the warnings.
4. In case there’s an error when starting new task, a callback is sent for the failed job with the 'restart_failed' event and the following warning message:

   Retry on error failed.

{
  "query": {
    "source": "...",
    "retry_on_error": 1,
    "format": [
      {
        "output": "mp4",
        ...
      }
    ]
  }
}

Enable Retry on Error toggle in the job settings:

Best Practices

• While retry_on_error is not enabled by default we recommend to enable it for all your jobs.

Example

1. Temporary network issues cause a job to fail.
2. Job is retried.
3. Job succeeds on the second attempt.

3

Allow Soft-fail for Multi-Output Jobs

By default, an error in any output causes an error for the entire job and stops the transcoding process. To further reduce error rates, you can allow certain outputs to fail without causing an error for the entire transcoding job. This reduces failures caused by non-essential outputs, reduces overhead for transcoding jobs with many outputs, and increases time to market for your videos.

How It Works

You can specify which outputs should be allowed to soft-fail by configuring job settings.

{
  "query": {
    "source": "...",
    "format": [
      {
        "output": "mp4",
        ...
      },
      {
        "output": "speech_to_text",
        "allow_soft_fail": 1,
        ...
      }
    ]
  }
}

In the API, set allow_soft_fail to 1 for any output that is not critical. This is recommended for Speech-to-Text and audio-only outputs since some source files can have no or silent audio stream. Enabling soft-fail behavior will make sure your job is completed successfully with only valid outputs, e.g. video or thumbnails in this case.

Enable Allow Soft-fail toggle in the job output settings:

Benefits

• Ensures critical outputs are prioritized and completed.
• Reduces job failure rates.

Best Practices

• Clearly define the most critical outputs for each job.
• Configure soft-fail for outputs that are supplementary or optional.
• Regularly review and adjust output priorities based on usage and importance.

Example

A job requires outputs in multiple formats; an optional format fails but the critical formats succeed. Transcoding for various device profiles, where some profiles are less critical and can be set to soft-fail.

Frequently Asked Questions

What if all retries fail?

Investigate the root cause and consider manual intervention.

Can I prioritize certain outputs within a job?

Yes, use soft-fail settings to prioritize critical outputs.

How do I configure notifications for warnings?

Use logging tools and notification systems integrated with your transcoding software.

Need More Help?

For additional information, tutorials, or support, visit the Qencode Documentation page or contact Qencode Support at support@qencode.com.