This topic answers frequently asked questions about transcoding in ApsaraVideo VOD.
How do I troubleshoot a transcoding failure?
Verify that the source file can be played on a local device. This is a critical first step, as most transcoding failures result from issues within the source file itself. Common issues include a missing video stream, invalid metadata, frame errors, or a missing video header. These issues can trigger transcoding efficiency monitoring and cause the transcoding job to fail.
Run the
ffprobe -show_streams -show_format -of json -i [filePath]command to inspect the file's metadata for issues such as a missing moov atom or stream anomalies.Run the
ffprobe -show_packets -i [filePath]command to check for data stream issues and verify that the stream duration matches the duration specified in the metadata.NoteA mismatch between the duration specified in the metadata and the actual stream duration may cause transcoding to fail. If a file has invalid metadata, use a tool such as FFmpeg to fix the file locally before uploading it for transcoding.
Find the corresponding error code in the Error Codes list to identify the specific reason for the failure.
To prevent truncation or job failures, escape any special characters used in text watermarks.
If an encryption transcoding job fails, refer to Video Encryption FAQ for common errors related to HLS standard encryption.
Why billing and template definitions differ
When you configure a transcoding template, you can select a definition and then manually change its resolution. However, billing is determined by the output specification tier that corresponds to the long and short sides of the actual output video's resolution. As a result, the definition set in your template may differ from the one used for billing. For more information about how billing specifications are determined, see Media Transcoding Billing.
For example, if you set the definition in a transcoding template in the ApsaraVideo VOD console to SD (LD), the system defaults to a resolution of 960×540.
If you transcode a video with this default resolution, it is billed as HD (SD) (1280x720). This is because the output resolution of 960×540 is higher than the 640×480 maximum allowed for the SD (LD) billing tier.
If you manually change the resolution for the SD (LD) definition to 1920x1080 and transcode a video, it is billed as HD (1920x1080).
Playback issues with the No Transcoding template
This issue can occur for the following reasons:
Cause 1: The source video is corrupted and cannot be played.
Cause 2: Only videos in MP4, FLV, M3U8, MP3, and WEBM formats can be played directly without transcoding.
When you upload a video to ApsaraVideo VOD using the built-in No Transcoding template group, an original quality video stream is generated if the source video is in MP4, FLV, M3U8, MP3, or WEBM format. For other formats, an original video stream is generated.
An original video stream cannot be previewed in the ApsaraVideo VOD console, and you cannot obtain its playback URL by calling the Get audio and video playback URL API. You can only obtain the source file URL for playback by calling the Get source file information API. In contrast, an original quality video stream can be previewed in the ApsaraVideo VOD console, and you can obtain its playback URL by calling the Get audio and video playback URL API.
Multiple audio streams reduced to a single stream
Currently, transcoding retains only one audio stream. This is controlled by theaudioMap=0 setting in the Output parameter. If your use case requires multiple audio streams,submit a ticket.
Output resolution does not match settings
In ApsaraVideo VOD transcoding templates, the auto-rotate screen feature (LongShortMode) is enabled by default. When this feature is enabled, width corresponds to the long side and height corresponds to the short side. You only need to set one of these values and leave the other blank. If you want to enforce a specific output resolution, you must disable the auto-rotate screen feature. Disabling this feature may cause the output video to appear stretched or distorted.
Incorrect video orientation after transcoding
This typically happens if the source video contains a rotation metadata flag, such asrotation=-90, which swaps the video's width and height during transcoding. You can use a tool like FFmpeg to inspect the source file for rotation information. To check the file information, run the following command:
ffprobe -show_streams -show_format -of json -i [filepath]Black screen on transcoded M3U8 files
First, check if the video stream in your source file is valid. If the first Transport Stream (TS) segment of the source file does not contain video data, the player may fail to display video. If this occurs, try transcoding the source file to MP4 first, and then transcode the resulting MP4 file to M3U8. This should resolve the playback issue.
Exposure issues after HDR to SDR conversion
If your source video is in HDR, select SDR Mapping in the dynamic range settings of your transcoding template. For example:
SDR Mapping is in public preview. This feature will incur charges after the public preview ends. For more information, see Audio and video enhancement fees. If the issue persists,submit a ticket for assistance.
Handling the moov box in transcoding
After transcoding, ApsaraVideo VOD places the moov box at the beginning of the MP4 file by default. This behavior cannot be customized. Files that do not have a moov box cannot be processed and will cause the transcoding job to fail.
Duration mismatch in video-to-audio conversion
To ensure duration consistency, the ApsaraVideo VOD transcoding logic uses the shortest audio stream in the input file as the basis for timing. If timestamps in some segments of the source file are not continuous, the service may be unable to retrieve the media information from the video stream. This affects the duration estimate and can lead to a discrepancy.
Playback errors for audio-only files
Check that video processing is disabled in your transcoding template. For an audio-only file, you must disable video processing. You can do this in the template's settings.
Bitrate settings not applied
Check whether you have enabled the bitrate check mechanism in your transcoding template. In the ApsaraVideo VOD console, you can find this feature in a regular transcoding template under Conditional Transcoding Parameters as either Check video bitrate or Check audio bitrate. When this mechanism is enabled, the bitrate you set in the template may not take effect under certain conditions. Specifically, if the output encoder is the same as the source encoder and the target bitrate is higher than the source bitrate, the service either resets the output bitrate to match the source bitrate or skips transcoding the stream, depending on your configuration.
How long does a transcoding job take?
The reference values below describe the processing speed under typical test conditions after a transcoding job has started processing. These values do not include any queuing time, do not represent the total job completion time, and do not constitute a service-level agreement (SLA).
For a typical transcoding scenario to H.264 720P, the processing speeds for different transcoding algorithms are as follows:
Transcoding algorithm |
Processing speed |
Description |
regular transcoding |
Average speed: approx. 3x |
This value reflects the processing speed during the transcoding phase under typical conditions. |
Narrowband HD™ 1.0 |
Average speed: approx. 1.5x |
Processing time is typically longer than regular transcoding. |
Narrowband HD™ 2.0 |
Typically much lower than 1x speed |
Processing time is often longer than the source video duration. The actual time depends on the specific job. |
Speed multiplier
Speed multiplier = Duration of video processed per unit of processing time
Example:
A 3x speed means that approximately 3 minutes of video content can be processed in 1 minute of processing time.
Therefore, excluding queuing time, a 30-minute video would theoretically take about 10 minutes to process.The reference values apply only to typical H.264 720P transcoding scenarios.
These values should not be used to estimate the total job completion time.
Processing speed is typically lower for higher resolutions, more complex encoding, or more intensive parameters.
Differences in the source video's bitrate, frame rate, container format, and stream structure can significantly affect processing time.
The processing complexity of Narrowband HD™ 2.0 is significantly higher than that of regular transcoding and Narrowband HD™ 1.0.
Refer to the job status query or completion notification for the actual processing time.
Querying transcoding progress
ApsaraVideo VOD does not provide an API to query the real-time progress of a transcoding job. Instead, you can configure event notifications to receive notifications about the job's status.
Can I perform batch transcoding?
ApsaraVideo VOD does not directly support batch transcoding operations for existing media. The system automatically transcodes videos during the upload process by using transcoding templates or workflows. However, if you store your media in your own Object Storage Service (OSS) buckets, you can achieve batch transcoding by integrating with Intelligent Media Management (IMM). You can create an IMM project and then define a batch processing job by using criteria such as a prefix match to efficiently transcode multiple videos. For more information, see Batch Processing in OSS.
Why do my transcoding jobs keep failing?
Job failures can have various causes. Always check the returned error message. If you receive a preprocessing failure error, it means the service was unable to decode your source file. In this case,submit a ticket and provide the following information to help us diagnose the issue: your Alibaba Cloud account ID and the video ID.
Does ApsaraVideo VOD support real-time transcoding?
ApsaraVideo VOD is a file-based transcoding service and does not support real-time transcoding.
Batch transcoding for existing videos
ApsaraVideo VOD does not support batch transcoding for videos that have already been uploaded.
Watermark does not appear after transcoding
Check the parameters of the watermark template used for transcoding, such as its dimensions (width × height) and offsets. Ensure that these settings place the watermark within the bounds of the video's resolution. If the watermark's settings place it outside the video frame, it will not be visible even if the transcoding job completes successfully.
Missing callbacks for transcoding failures
When you configure event notifications for transcoding, if you subscribe only to the Single Definition Transcoding Complete (StreamTranscodeComplete) event and not to the TranscodeComplete event, you may not receive failure notifications in certain scenarios. For example, if you upload a corrupted source file that causes all output streams to fail, ApsaraVideo VOD sends a failure callback for the TranscodeComplete event. Because you are not subscribed to this event, you will not receive a notification of the transcoding failure.