Audio Stream Validation and Automatic Repair

We provide the ability to validate audio stream quality and repair some problems.

We will validate the following audio parameters:

Empty or silent channels
Channels with low loudness levels
Loudness difference between paired channels (L and R, SL and SR)
LFE channel contains high-frequency sound louder than average level -10dB

We can then repair empty/silent audio channels where possible.

Request

<?xml version="1.0"?>
<query>
    <userid>[UserID]</userid> <!-- required-->
    <userkey>[UserKey]</userkey> <!-- required-->
    <action>[Action]</action> <!-- required-->
    <source>[SourceFile]</source> <!-- required -->
    <format>
        <output>[OutputFormat]</output> <!-- required -->
        <audio_stream>
            <validate>
                <on_error>[pass|fail|report]</on_error>
                <repair>[yes|no]</repair>
                <loudness_diff>[LoudnessDiff]<loudness_diff>
                <stereo_diff>[StereoDiff]</stereo_diff>
                <side_diff>[SideDiff]</side_diff>
            </validate>
            <!-- audio_stream params -->
        </audio_stream>
        <!-- multiple audio_streams -->
        <audio_stream>
            <!-- audio_stream params -->
        </audio_stream>
        <!-- format params -->
    </format>
</query>

{
    "query": {
        "userid": "[UserID]", // required
        "userkey": "[UserKey]", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "format": {
            "output": "[OutputFormat]", // required
            "audio_stream": [
                {
                    "validate": {
                        "on_error": "[pass|fail|report]",
                        "repair": "[yes|no]",
                        "loudness_diff": "[LoudnessDiff]",
                        "stereo_diff": "[StereoDiff]",
                        "side_diff": "[SideDiff]"
                    }
                    // audio_stream params
                },
                {
                    // audio_stream params
                }
            ]
            // format params
        }
    }
}

Parameter	Description	Allowed Values	Default Value
on_error	Validation action	pass – ignore validation fail – fail media if repairing not possible report – only report validation errors in media status and notification	pass
repair	Attempt to repair audio	yes, no	no
loudness_diff	Maximum allowed difference in loudness between a channel and the average level	Positive integer number between 1 and 30	15
stereo_diff	Maximum allowed percentage difference in loudness between L and R channels	Positive integer number between 1 and 100	5
side_diff	Maximum allowed percentage difference in loudness between SL and SR or BL and BR channels	Positive integer number between 1 and 100	10

Validation Results

Audio Stream Validation results can be found in the extended GetStatus response (e.g <extended />; parameter set to yes) and in the media notification.

Extended GetStatus response

<?xml version="1.0"?>
<response>
    <job>
        <id>[MediaID]</id>
        <userid>[UserID]</userid>
        <status>[MediaStatus]</status>
        <!-- job params -->
        <format>
            <id>[ID]</id>
            <status>[Status]</status>
            <!-- format params -->
            <audio_validation>
                <stream_id>[AudioStreamID]</stream_id>
                <alternate_id>[AlternateID]</alternate_id>
                <state>[ValidationStatus]</state>
                <muted_channels>[ChannelNumber1]</muted_channels>
                <muted_channels>[ChannelNumber2]</muted_channels>
                <!-- ... -->
                <muted_channels>[ChannelNumberN]</muted_channels>
                <too_low_level>[ChannelNumber1]</too_low_level>
                <too_low_level>[ChannelNumber2]</too_low_level>
                <!-- ... -->
                <too_low_level>[ChannelNumberN]</too_low_level>
                <stereo_diff>[0|1]</stereo_diff>
                <side_diff>[0|1]</side_diff>
                <high_freq_lfe>[0|1]</high_freq_lfe>
            <audio_validation>
            <audio_validation>
                <!-- audio_validation params -->
            </audio_validation>
        </format>
        <format>
            <!-- format params -->
        </format>
    </job>
    <job>
        <!-- job params -->
    </job>
</response>

{
    "response": {
        "job": [
            {
                "id": "[MediaID]",
                "userid": "[UserID]",
                "sourcefile": "[SourceFile]",
                "status": "[MediaStatus]",
                // job params
                "format": [
                    {
                        "id": "[ID]",
                        "status": "[Status]",
                        // format params
                        "audio_validation": [
                            {
                                "stream_id": "[AudioStreamID]",
                                "alternate_id": "[AlternateID]",
                                "state": "[ValidationStatus]",
                                "muted_channels": [
                                    "[ChannelNumber1]",
                                    "[ChannelNumber2]",
                                    // ...
                                    "[ChannelNumberN]"
                                ],
                                "too_low_level": [
                                    "[ChannelNumber1]",
                                    "[ChannelNumber2]",
                                    // ...
                                    "[ChannelNumberN]"
                                ],
                                "stereo_diff": "[0|1]",
                                "side_diff": "[0|1]",
                                "high_freq_lfe": "[0|1]"
                            },
                            {
                                // audio_validation params
                            }
                        ]
                    },
                    {
                        // format params
                    }
                ]
            },
            {
                // job params
            }
        ]
    }
}

Notification Data

<?xml version="1.0"?>
<result>
    <mediaid>[MediaID]</mediaid>
    <source>[SourceFile]</source>
    <status>[MediaStatus]</status>
    <description>[ErrorDescription]</description> <!-- Only present when Status = Error -->
    <format>
        <output>[OutputFormat]</output>
        <!-- format params -->
        <audio_validation>
            <stream_id>[AudioStreamID]</stream_id>
            <alternate_id>[AlternateID]</alternate_id>
            <state>[ValidationStatus]</state>
            <muted_channels>[ChannelNumber1]</muted_channels>
            <muted_channels>[ChannelNumber2]</muted_channels>
            <!-- ... -->
            <muted_channels>[ChannelNumberN]</muted_channels>
            <too_low_level>[ChannelNumber1]</too_low_level>
            <too_low_level>[ChannelNumber2]</too_low_level>
            <!-- ... -->
            <too_low_level>[ChannelNumberN]</too_low_level>
            <stereo_diff>[0|1]</stereo_diff>
            <side_diff>[0|1]</side_diff>
            <high_freq_lfe>[0|1]</high_freq_lfe>
        <audio_validation>
        <audio_validation>
            <!-- audio_validation params -->
        </audio_validation>
    </format>
</result>

{
    "result": {
        "mediaid": "[MediaID]",
        "source": "[SourceFile]",
        "status": "[MediaStatus]",
        "description": "[ErrorDescription]",
        "format": {
            "output": "[OutputFormat]",
            // format params
            "audio_validation": [
                {
                    "stream_id": "[AudioStreamID]",
                    "alternate_id": "[AlternateID]",
                    "state": "[ValidationStatus]",
                    "muted_channels": [
                        "[ChannelNumber1]",
                        "[ChannelNumber2]",
                        // ...
                        "[ChannelNumberN]"
                    ],
                    "too_low_level": [
                        "[ChannelNumber1]",
                        "[ChannelNumber2]",
                        // ...
                        "[ChannelNumberN]"
                    ],
                    "stereo_diff": "[0|1]",
                    "side_diff": "[0|1]",
                    "high_freq_lfe": "[0|1]"
                },
                {
                    // audio_validation params
                }
            ]
        }
    }
}

🚧
For audio_validation
The <audio_validation /> section will be included to the notification data only if
<extended_notify /> media parameter was set to yes.

Parameter	Description
stream_id	Audio Stream ID
alternate_id	Alternate Source ID. Optional for advanced multi-bitrate formats.
state	Validation status. Possible values: ok, warn, and error.
muted_channels	An array of a number of channels which loudness is is below -70dB
too_low_level	An array of a number of channels which loudness is less than average loudness for a value specified in <loudness_diff />
stereo_diff	The loudness difference between stereo channels is more than the value specified in <stereo_diff />
side_diff	The loudness difference between side channels is more than the value specified in <side_diff />
high_freq_lfe	LFE channel contains high-frequency sound.