edit-icon download-icon

HLS package

Last Updated: Apr 24, 2018

Introduction

HLS package refers to the process in which multi-subtitle, multi-track and multi-bitstream are integrated into a Master Playlist file. The process includes two steps. Firstly, create HLS package workflow. Secondly, call AddMedia interface to specify video and the ID of the HLS package workflow for video processing.

  1. When performing AddMediaWorkflow operation, the following objects require special attention:

    • Topology

      Topology refers to the business processing procedure, Directed Acyclic Graph (DAG).

    • Activity

      Activity refers to the processing nodes which constitute the topology. While creating HLS package workflow, pay attention to the following activities:

      • PackageConfig

        Specify HLS package configuration, and configure the output location for the Master Playlist file.

        Interdependency between the front node and the back node:

        • The front node allows: Start.

        • The back node allows: SubtitleGroup, AudioGroup, and Transcode (only video).

      • SubtitleGroup

        Specify the subtitle group ID.

        Interdependency between the front node and the back node

        • The front node allows: PackageConfig.

        • The back node allows: Transcode (only subtitle).

      • AudioGroup

        Specify the audio group ID.

        Interdependency between the front node and the back node

        • The front node allows: PackageConfig.

        • The back node allows: Transcode (only audio).

      • Transcode

        Extract video streams/audio stream/subtitle stream.

        Interdependency between the front node and the back node

        • The front node allows: PackageConfig, SubtitleGroup, and AudioGroup.

        • The back node allows: GenerateMasterPlayList。

      • GenerateMasterPlayList

        HLS package generation activity specifies multi-ratestream configuration, audio group and subtitle group.

        Interdependency between the front node and the back node

        • The front node allows: Transcode.

        • The back node allows: Report.

    • Dependencies

      Dependencies refer to the edges of the topology, indicating the dependency between activities.

  2. Call AddMedia, pay attention to the following aspects:

    • Specify Media workflow ID.

    • If subtitle extraction exists, you can configure in the way that the subtitle file address overwrites the WebVTTSubtitleURL parameter in the Transcode activity, and only subtitle files of WebVTT are supported.

    • Set the Workflow triggering mode as NotInAuto.

Scenarios

The mxf format of the source file, also supports such formats as mp4, flv and m3u8(ts), extracts three audio tracks, two video streams and two groups of WebVTT subtitles from the source file, and then combine and package into a Master Playlist:

Configure HLS package output location and name of Master Playlist.

  • Configure Bucket.

  • Configure Location.

  • Configure the name of Master Playlist.

  • The activity is defined as follows:

    1. {
    2. "Parameters" : {
    3. "Output" : "{\"Bucket\": \"processedmediafile\",\"Location\": \"oss-cn-hangzhou\",\"MasterPlayListName\": \"{MediaId}/{RunId}/hls/master.m3u8\"}"
    4. },
    5. "Type" : "PackageConfig"
    6. }

Audio group

  • Configure the audio group ID, wherein two audio streams belongs to the same audio group.

  • The activity is defined as follows:

    1. {
    2. "Parameters" : {
    3. "GroupId" : "audios"
    4. },
    5. "Type" : "AudioGroup"
    6. }
    • GroupId: Specify the audio group Id as audios.

    • Type: Specify the type as AudioGroup activity.

Audio extraction

  • Extract audio streams from mxf source file, and the video streams must be removed.

  • Output audio parameters:

    • Codec: AAC

    • SampleRate: 48000 Hz

    • Format: Stereo

  • The activity is defined as follows:

    1. {
    2. "Name" : "audio-extract-1",
    3. "Parameters" : {
    4. "Outputs" : "[{\"TemplateId\":\"S00000001-100020\",\"AudioStreamMap\":\"0:a:0\",\"Video\":{\"Remove\":\"true\"}}]",
    5. "ExtXMedia" : "{\"URI\": \"sd/audio-en.m3u8\",\"Name\": \"audio-en\",\"Language\": \"en-US\"}"
    6. }
    • Preset static templates ID: S00000001-100020 indicates that the audio output is m3u8(ts), and the audio bitrate configured in the preset templates is 80kbps.

    • AudioStreamMap: Audio stream sequence number. For more information, see Output.

    • Remove the video streams from the output. For more information, see Video.

    • ExtXMedia defines Media Playlist, and URI specifies the name of Media Playlist.

    • Type is configured as Transcode, which is transcode activity.

Video extraction

  • Extract video streams from the mxf source file, and the audio streams must be removed.

  • The activity is defined as follows:

    1. {
    2. "Name" : "video-extract",
    3. "Parameters" : {
    4. "Outputs" : "[{\"TemplateId\":\"1fe5393bdb7b2b883f0a0fc91e81344a\",\"Audio\":{\"Remove\":\"true\"}}]",
    5. "MultiBitrateVideoStream" : "{\"URI\": \"sd/video1.m3u8\"}"
    6. },
    7. "Type" : "Transcode"
    8. }
    • Custom transcoding template ID: 1fe5393bdb7b2b883f0a0fc91e81344a, the video transcoding parameter can be configured in MPS console > Settings > Transcoding Templates:

      • Codec: H.264

      • Resolution: 384x216

      • Profile: Main

      • Bitrate: 240 Kbps

      • Fps: 25

      • PixelFormat: YUV420P Max GOP size: 1 segment length (4 seconds)

      • Output format: m3u8

    • Remove audio streams from the output. For more information Audio.

    • MultiBitrateVideoStream defines the multi-bitrate video streams in Master Playlist, and URI specifies the name of Media Playlist.

    • Type is configured as Transcode, which is transcode activity.

Subtitle group

  • Configure subtitle group ID, wherein two subtitle streams belong to the same subtitle group.

  • The activity is defined as follows:

    1. {
    2. "Parameters" : {
    3. "GroupId" : "subtitles"
    4. },
    5. "Type" : "SubtitleGroup"
    6. }
    • GroupId: Specify the audio group Id as subtitles.

    • Type: Specify the type as SubtitleGroup activity.

Subtitle extraction

  • Upload subtitles in the WebVtt format to OSS.

  • The activity is defined as follows:

    1. {
    2. "Name" : "subtitle-extract-1",
    3. "Parameters" : {
    4. "WebVTTSubtitleURL" : "http://mts-video.oss-cn-hangzhou.aliyun-inc.com/ShawshankRedemption.vtt",
    5. "ExtXMedia" : "{\"URI\": \"zh/subtitle1-cn.m3u8\",\"Name\": \"subtitle-cn\",\"Language\": \"cn\"}"
    6. },
    7. "Type" : "Transcode"
    8. }
    • WebVTTSubtitleURL specified the subtitle address. The subtitle address is overwritten dynamically while calling AddMedia. For more information about this parameter, see OverrideParams.

    • ExtXMedia defines Media Playlist, and URI specifies the name of Media Playlist.

    • Type is configured as Transcode, which is transcode activity.

Master Playlist output

  • By means of audio, video and subtitle extraction, all the resources after extraction conversion are packaged into a Master Playlist.

  • The activity is defined as follows:

    1. {
    2. "Parameters" : {
    3. "MasterPlayList" : "{\"MultiBitrateVideoStreams\": [{\"RefActivityName\": \"video-extract\",\"ExtXStreamInfo\": {\"BandWidth\": \"1110000\",\"Audio\": \"audios\",\"Subtitles\": \"subtitles\"}}]}"
    4. },
    5. "Type" : "GenerateMasterPlayList"
    6. }
    • MasterPlayList defines Master Playlist.

    • MultiBitrateVideoStreams refers to multi-bitrate video streams group.

    • RefActivityName specifies the activity name of video streams.

    • ExtXStreamInfo defines the attributes of the multi-bitrate video streams, Audio specifies the audio group, and Subtitles specifies the subtitle group.

    • Type is set as GenerateMasterPlayList, that is generating Master Playlist activity.

Topology diagram:

topology

Complete scenario example shown in topology:

  1. {
  2. "Activities" : {
  3. "package-node" : {
  4. "Name" : "package-node",
  5. "Parameters" : {
  6. "Output" : "{\"Bucket\": \"processedmediafile\",\"Location\": \"oss-cn-hangzhou\",\"MasterPlayListName\": \"{MediaId}/{RunId}/hls/master.m3u8\"}"
  7. },
  8. "Type" : "PackageConfig"
  9. },
  10. "audioGroupNode" : {
  11. "Name" : "audioGroupNode",
  12. "Parameters" : {
  13. "GroupId" : "audios"
  14. },
  15. "Type" : "AudioGroup"
  16. },
  17. "subtitleGroupNode" : {
  18. "Name" : "subtitleGroupNode",
  19. "Parameters" : {
  20. "GroupId" : "subtitles"
  21. },
  22. "Type" : "SubtitleGroup"
  23. },
  24. "video-extract-1" : {
  25. "Name" : "video-extract-1",
  26. "Parameters" : {
  27. "Outputs" : "[{\"TemplateId\":\"1fe5393bdb7b2b883f0a0fc91e81344a\",\"Audio\":{\"Remove\":\"true\"}}]",
  28. "MultiBitrateVideoStream" : "{\"URI\": \"sd/video1.m3u8\"}"
  29. },
  30. "Type" : "Transcode"
  31. },
  32. "video-extract-2" : {
  33. "Name" : "video-extract-1",
  34. "Parameters" : {
  35. "Outputs" : "[{\"TemplateId\":\"1fe5393bdb7b2b883f0a0fc91e81344b\",\"Audio\":{\"Remove\":\"true\"}}]",
  36. "MultiBitrateVideoStream" : "{\"URI\": \"sd/video2.m3u8\"}"
  37. },
  38. "Type" : "Transcode"
  39. },
  40. "audio-extract-1" : {
  41. "Name" : "audio-extract-1",
  42. "Parameters" : {
  43. "Outputs" : "[{\"TemplateId\":\"S00000001-100020\",\"AudioStreamMap\":\"0:a:0\"}]",
  44. "ExtXMedia" : "{\"URI\": \"sd/audio-en-1.m3u8\",\"Name\": \"audio-en\",\"Language\": \"en-US\"}"
  45. },
  46. "Type" : "Transcode"
  47. },
  48. "audio-extract-2" : {
  49. "Name" : "audio-extract-2",
  50. "Parameters" : {
  51. "Outputs" : "[{\"TemplateId\":\"S00000001-100020\",\"AudioStreamMap\":\"0:a:1\"}]",
  52. "ExtXMedia" : "{\"URI\": \"sd/audio-cn.m3u8\",\"Name\": \"audio-cn\",\"Language\": \"cn\"}"
  53. },
  54. "Type" : "Transcode"
  55. },
  56. "audio-extract-3" : {
  57. "Name" : "audio-extract-3",
  58. "Parameters" : {
  59. "Outputs" : "[{\"TemplateId\":\"S00000001-100020\",\"AudioStreamMap\":\"0:a:2\"}]",
  60. "ExtXMedia" : "{\"URI\": \"sd/audio-de.m3u8\",\"Name\": \"audio-de\",\"Language\": \"de\"}"
  61. },
  62. "Type" : "Transcode"
  63. },
  64. "subtitle-extract-1" : {
  65. "Name" : "subtitle-extract-1",
  66. "Parameters" : {
  67. "WebVTTSubtitleURL" : "http://mts-video-daily-bucket.oss-test.aliyun-inc.com/1.vtt",
  68. "ExtXMedia" : "{\"URI\": \"zh/subtitle1-cn.m3u8\",\"Name\": \"subtitle-cn\",\"Language\": \"cn\"}"
  69. },
  70. "Type" : "Transcode"
  71. },
  72. "subtitle-extract-2" : {
  73. "Name" : "subtitle-extract-2",
  74. "Parameters" : {
  75. "WebVTTSubtitleURL" : "http://mts-video.oss-cn-hangzhou.aliyun-inc.com/ShawshankRedemption.vtt",
  76. "ExtXMedia" : "{\"URI\": \"zh/subtitle1-en.m3u8\",\"Name\": \"subtitle-en\",\"Language\": \"en-US\"}"
  77. },
  78. "Type" : "Transcode"
  79. },
  80. "masterPlayListGenerate" : {
  81. "Name" : "masterPlayListGenerate",
  82. "Parameters" : {
  83. "MasterPlayList" : "{\"MultiBitrateVideoStreams\": [{\"RefActivityName\": \"video-extract-1\",\"ExtXStreamInfo\": {\"BandWidth\": \"1110000\",\"Audio\": \"audios\",\"Subtitles\": \"subtitles\"}}, {\"RefActivityName\": \"video-extract-2\",\"ExtXStreamInfo\": {\"BandWidth\": \"5000000\",\"Audio\": \"audios\",\"Subtitles\":\"subtitles\"}}]}"
  84. },
  85. "Type" : "GenerateMasterPlayList"
  86. },
  87. "activityEnd" : {
  88. "Name" : "activityEnd",
  89. "Parameters" : {
  90. "PublishType" : "Manual"
  91. },
  92. "Type" : "Report"
  93. },
  94. "activityStart" : {
  95. "Name" : "activityStart",
  96. "Parameters" : {
  97. "PipelineId" : "900ededca77641ecbecd4f44cc3a2965",
  98. "Role" : "AliyunMTSDefaultRole",
  99. "InputFile" : "{\"Bucket\":\"videouploaded\",\"Location\":\"oss-cn-hangzhou\",\"ObjectPrefix\":\"uploaded/\"}"
  100. },
  101. "Type" : "Start"
  102. }
  103. },
  104. "Dependencies" : {
  105. "video-extract-1" : [ "masterPlayListGenerate" ],
  106. "video-extract-2" : [ "masterPlayListGenerate" ],
  107. "audio-extract-1" : [ "masterPlayListGenerate" ],
  108. "audio-extract-2" : [ "masterPlayListGenerate" ],
  109. "audio-extract-3" : [ "masterPlayListGenerate" ],
  110. "subtitle-extract-1" : [ "masterPlayListGenerate" ],
  111. "subtitle-extract-2" : [ "masterPlayListGenerate" ],
  112. "package-node" : [ "video-extract-1", "video-extract-2","subtitleGroupNode", "audioGroupNode" ],
  113. "audioGroupNode" : [ "audio-extract-1", "audio-extract-2","audio-extract-3"],
  114. "subtitleGroupNode" : [ "subtitle-extract-1", "subtitle-extract-2" ],
  115. "masterPlayListGenerate" : [ "activityEnd" ],
  116. "activityEnd" : [ ],
  117. "activityStart" : [ "package-node" ]
  118. }
  119. }

Code example

Step 1. Create HLS package workflow

Create workflow-Java

Create workflow-Python

Create workflow-PHP

Step 2. Add media

Add media-Java

Add media-Python

Add media-PHP

Thank you! We've received your feedback.