IMS multi-subtitle transcoding packaging best practices-Intelligent Media Services(IMS)-阿里云帮助中心

Transcoding and packaging workflow

Packaged file structure example:

#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-Subtitles",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. Activate IMS.

Configuration

Basic IMS configuration

Storage: Bind an OSS bucket to IMS. Configure a storage location.
Callbacks: Configure HTTP or MNS callbacks for job status notifications. Overview of callback events.

Transcoding template configuration

Configuration process

Example requirements

Codec: H.264/H.265

Video resolution: 360P, 540P, 720P, 1080P

Audio: HE-AAC 64 Kbps (default configuration).

Subtitles: M3U8 (VTT).

Configuration example

Create transcoding templates for four video resolutions. Create a transcoding template.

Note

For Narrowband HD™ transcoding, create a template based on the table, then submit a ticket to upgrade the backend configuration.

H.264

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

H.265

Note

Recommended: Use fmp4 container format, an Apple standard with better Safari compatibility.
Alternative: ts format is supported but incompatible with Safari.
Console limitation: The console does not support fmp4. Create a template with m3u8(ts), then submit a ticket to upgrade the backend configuration.

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

Multi-bitrate transcoding and packaging

Submit a job

Call the SubmitMediaConvertJob API to submit a transcoding job.

Use OverrideParams to configure subtitle streams

Subtitle settings cannot be configured in transcoding templates. Specify them in the OverrideParams parameter.

Parameter	Type	Description
Subtitles	Array of Subtitle	Subtitle stream settings.

Subtitle

Parameter	Type	Description
Codec	String	Subtitle stream codec. HLS supports only VTT.

HlsGroupConfig parameters

Parameter	Type	Description
Type	string	Stream type. Valid values: video: IMS processes only video settings. audio: IMS processes only audio settings. hybrid: IMS processes both audio and video settings.
Bandwidth	string	Bandwidth. Optional. Defaults to bitrate (bps). Takes effect when `Type` is `video` or `hybrid`.
AudioGroup	string	Audio group for this video stream. Takes effect when `Type` is `video`.
SubtitleGroup	string	Subtitle group for this video stream. Takes effect when `Type` is `video` or `hybrid`.
Name	string	`NAME` attribute in the HLS manifest. Required when `Type` is `audio` or `subtitle`.
Group	string	`GROUP-ID` attribute in the HLS manifest. Takes effect when `Type` is `audio` or `subtitle`. Defaults to the `Type` value.
Language	string	`LANGUAGE` attribute in the HLS manifest. Must comply with RFC 5646. Takes effect when `Type` is `audio` or `subtitle`.
Default	boolean	Whether this is the default stream. Takes effect when `Type` is `audio`.
AutoSelect	boolean	Whether this stream is auto-selected. Takes effect when `Type` is `audio`.
Forced	boolean	Whether to force playback. Takes effect when `Type` is `audio`.

Use case 1: Transcode multi-bitrate files

{
    "Config": {
        "Inputs": [
            {
                "Name": "video",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS public endpoint>/<video_file_chinese>"
                }
            },
            {
                "Name": "EnglishAudio",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS public endpoint>/<audio_file_english>"
                }
            },
            {
                "Name": "ChineseSubtitle",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS public endpoint>/<subtitle_file_chinese>"
                }
            },
            {
                "Name": "EnglishSubtitle",
                "InputFile": {
                    "Type": "OSS",
                    "Url": "https://<Bucket>.<OSS public endpoint>/<subtitle_file_english>"
                }
            }
        ],
        "OutputGroups": [
            {
                "Name": "Hls",
                "GroupConfig": {
                    "Type": "Hls",
                    "OutputFileBase": {
                        "Type": "OSS",
                        "Url": "https://<Bucket>.<OSS public endpoint>/<URI>/"
                    },
                    "ManifestName": "<m3u8_filename>"
                },
                "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_job",
                        "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_job",
                        "OverrideParams": {
                            "Subtitles": [
                                {
                                    "Codec": "vtt"
                                }
                            ]
                        },
                        "HlsGroupConfig": {
                            "Type": "Subtitle",
                            "Name": "EnglishSubtitle",
                            "Language": "en",
                            "AutoSelect": true,
                            "Default": false
                        }
                    }
                ]
            }
        ]
    }
}

Query job results

Call the GetMediaConvertJob API to query transcoding job details.

Callback event

EventType: MediaConvertComplete

This event is not available in the console. Configure it by calling the SetEventCallback API.

Key callback parameters

Parameter name	Type	Required	Description
Name	String	Yes	Main task name.
JobId	String	Yes	The job ID.
Status	String	Yes	Job status. `Success` means at least one sub-job succeeded.
TriggerSource	String	No	Trigger source. `API` means the job was submitted via API.
FinishTime	String	No	Job completion time. Same format as `EventTime`.
UserData	string	No	Custom data from job submission.

Example

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