Transcode and package multiple subtitle tracks - Intelligent Media Services

This document describes how to transcode and package media with multiple subtitle tracks, making it compatible with various devices.

Workflow

Example of an output file structure:

#EXTM3U

# Audio stream definition (multi-language)
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="Chinese-Audio",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="zh",URI="audio/chinese/chinese.m3u8"
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English-Audio",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="audio/english/english.m3u8"

# Video stream definition (multi-bitrate)
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=900000,CODECS="avc1.640020",RESOLUTION=720x1280,AUDIO="audio",SUBTITLES="subtitle"
video/720p/720p.m3u8
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=400000,CODECS="avc1.640020",RESOLUTION=360x640,AUDIO="audio",SUBTITLES="subtitle"
video/360p/360p.m3u8

# Subtitle stream definition (multi-language)
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitle",NAME="Chinese-Subtitle",DEFAULT=YES,AUTOSELECT=YES,FORCED=NO,LANGUAGE="zh",URI="subtitle/chinese/chinese.m3u8"
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subtitle",NAME="English-Subtitle",DEFAULT=NO,AUTOSELECT=YES,FORCED=NO,LANGUAGE="en",URI="subtitle/english/english.m3u8"

Prerequisites

IMS is activated. For details, see Activate IMS.

Configuration

Basic configuration

Storage: Associate an Object Storage Service (OSS) bucket with IMS. For more information, see Configure storage addresses.
Callback: Configure an HTTP or MNS callback to receive task status notifications. For callback methods and events, see Overview.

Transcoding template configuration

Procedure

Example requirements

Codec: H.264, H.265

Resolution: 360P, 540P, 720P, 1080P

Audio: HE-AAC, 64 Kbps (default)

Subtitles: M3U8 (VTT)

Example configuration

This example shows how to configure transcoding templates for the four required video resolutions. To learn how to create a template, see Create a transcoding template.

Note

To perform Narrowband HD™ transcoding, create a basic template based on the following table. Then, submit a ticket for backend upgrade.

H.264

Template	Codec	Container format	Other parameters
Video-360P	H.264	m3u8 (.ts)	Resolution (long edge fixed): 640px Segment length: 5s Configure other parameters as needed
Video-540P	H.264	m3u8 (.ts)	Resolution (long edge fixed): 960px Segment length: 5s Configure other parameters as needed
Video-720P	H.264	m3u8 (.ts)	Resolution (long edge fixed): 1280px Segment length: 5s Configure other parameters as needed
Video-1080P	H.264	m3u8 (.ts)	Resolution (long edge fixed): 1920px Segment length: 5s Configure other parameters as needed

H.265

Note

Recommended: Use the .fmp4 container format. It is an Apple standard and is highly compatible with Safari browsers.
Alternative: The .ts container format is also viable but is not compatible with Safari.
Console limitation: The .fmp4 container format cannot be created in the console. Create a template with the m3u8 (.ts) format first, then submit a ticket to upgrade the configuration on the backend.

Template	Codec	Container format	Other parameters
Video-360P	H.265	m3u8 (.fmp4)	Resolution (long edge fixed): 640px Segment length: 5s Configure other parameters as needed
Video-540P	H.265	m3u8 (.fmp4)	Resolution (long edge fixed): 960px Segment length: 5s Configure other parameters as needed
Video-720P	H.265	m3u8 (.fmp4)	Resolution (long edge fixed): 1280px Segment length: 5s Configure other parameters as needed
Video-1080P	H.265	m3u8 (.fmp4)	Resolution (long edge fixed): 1920px Segment length: 5s Configure other parameters as needed

Multi-bitrate transcoding task

Submit a task

Call the SubmitMediaConvertJob operation to submit a transcoding task.

Use OverrideParams to set the subtitle stream

Since subtitle information cannot be customized in transcoding templates, you must explicitly set it using the OverrideParams field when submitting a task.

Parameter	Type	Description
Subtitles	Array of Subtitle	Subtitle stream settings.

Subtitle

Parameter	Type	Description
Codec	String	The codec for the subtitle stream. HLS only supports the `vtt` format.

HlsGroupConfig

Parameter	Type	Description
Type	string	Specifies the stream type. Valid values: video: A video stream. Only video-related settings are retained during processing. audio: An audio stream. Only audio-related settings are retained during processing. hybrid: A hybrid stream. Both audio and video-related settings are retained during processing.
Bandwidth	string	(Optional) Sets the bandwidth. By default, the bitrate (in bps) is used. Effective when `Type` is `video` or `hybrid`.
AudioGroup	string	The audio group referenced by this video stream. Effective when `Type` is `video`.
SubtitleGroup	string	The subtitle group referenced by this video stream. Effective when `Type` is `video` or `hybrid`.
Name	string	The `NAME` attribute of this output stream in the HLS manifest. Required when `Type` is `audio` or `subtitle`.
Group	string	The `GROUP-ID` attribute of this output stream in the HLS manifest. Effective when `Type` is `audio` or `subtitle`. Defaults to the value of `Type`.
Language	string	The `LANGUAGE` attribute of this output stream in the HLS manifest. Must conform to RFC 5646. Effective when `Type` is `audio` or `subtitle`.
Default	boolean	Whether to set this stream as the default. Effective when `Type` is `audio`.
AutoSelect	boolean	Whether this stream is automatically selected. Effective when `Type` is `audio`.
Forced	boolean	Whether this stream is forced to display. Effective when `Type` is `audio`.

Usage example

{
    "Config": {
        "Inputs": [
            {
                "Name": "video",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS Public Endpoint>/<Video1_Chinese>"
                }
            },
            {
                "Name": "EnglishAudio",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS Public Endpoint>/<Audio1_English>"
                }
            },
            {
                "Name": "ChineseSubtitle",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS Public Endpoint>/<Subtitle1_Chinese>"
                }
            },
            {
                "Name": "EnglishSubtitle",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS Public Endpoint>/<Subtitle1_English>"
                }
            }
        ],
        "OutputGroups": [
            {
                "Name": "Hls",
                "GroupConfig": {
                    "Type": "Hls",
                    "OutputFileBase": {
                        "Type": "OSS",
                        "Url": "https://<Bucket>.<Public Endpoint>/<URI>/"
                    },
                    "ManifestName": "<m3u8filename>"
                },
                "Outputs": [
                    {
                        "Name": "720P",
                        "OutputFileName": "video/720p/720p",
                        "TemplateId": "Video-720P",
                        "HlsGroupConfig": {
                            "Type": "Video"
                        }
                    },
                    {
                        "Name": "360P",
                        "OutputFileName": "video/360p/360p",
                        "TemplateId": "Video-360P",
                        "HlsGroupConfig": {
                            "Type": "Video"
                        }
                    },
                    {
                        "OutputFileName": "audio/chinese/chinese",
                        "TemplateId": "Audio-64Kbps",
                        "HlsGroupConfig": {
                            "Type": "Audio",
                            "Name": "ChineseAudio",
                            "Language": "zh",
                            "Autoselect": "TRUE",
                            "Default": "TRUE"
                        }
                    },
                    {
                        "InputRef": "ChineseSubtitle",
                        "OutputFileName": "subtitle/chinese/chinese",
                        "TemplateId": "Any template ID in the task",
                        "OverrideParams": {
                            "Subtitles": [
                                {
                                    "Codec": "vtt"
                                }
                            ]
                        },
                        "HlsGroupConfig": {
                            "Type": "Subtitle",
                            "Name": "ChineseSubtitle",
                            "Language": "zh",
                            "Autoselect": "TRUE",
                            "Default": "TRUE"
                        }
                    },
                    {
                        "InputRef": "EnglishAudio",
                        "OutputFileName": "audio/english/english",
                        "TemplateId": "Audio-64Kbps",
                        "HlsGroupConfig": {
                            "Type": "Audio",
                            "Name": "EnglishAudio",
                            "Language": "en",
                            "Autoselect": "TRUE",
                            "Default": "FALSE"
                        }
                    },
                    {
                        "InputRef": "EnglishSubtitle",
                        "OutputFileName": "subtitle/english/english",
                        "TemplateId": "Any template ID in the task",
                        "OverrideParams": {
                            "Subtitles": [
                                {
                                    "Codec": "vtt"
                                }
                            ]
                        },
                        "HlsGroupConfig": {
                            "Type": "Subtitle",
                            "Name": "EnglishSubtitle",
                            "Language": "en",
                            "Autoselect": "TRUE",
                            "Default": "FALSE"
                        }
                    }
                ]
            }
        ]
    }
}

Query the task result

Call GetMediaConvertJob to retrieve the details of a transcoding task.

Callback events

Event type: MediaConvertComplete

Configuration method: This event cannot be configured in the console. Configure it by calling SetEventCallback.

Key callback parameters

Parameter	Type	Required	Description
Name	String	Yes	The name of the main task.
JobId	String	Yes	The ID of the task.
Status	String	Yes	The task status. `Success` indicates that at least one output (subtask) succeeded.
TriggerSource	String	No	The source that triggered the task. `API` indicates the task was submitted via an API call.
FinishTime	String	No	The time the task was completed, in UTC format.
UserData	string	No	A custom string specified when submitting the task. It is passed through and returned in the callback.

Example

{
	"FinishTime": "2025-05-09T08:03:21Z",
	"JobId": "your-job-id",
	"Status": "Success",
	"TriggerSource": "IceWorkflow",
	"UserData": "{\"ImsSrc\":\"Workflow\",\"TaskId\":\"e89a955d88ca47f0b9b79c562e5c622f\"}"
}