From 22017f0dac228e71efc75c36aa19ebcb6b419838 Mon Sep 17 00:00:00 2001 From: Chris Kalafarski Date: Tue, 28 Jul 2026 16:42:27 -0400 Subject: [PATCH 1/3] Add possible HLS task details --- README.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/README.md b/README.md index 4415b119..3c1a466a 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Many input and output methods are supported to allow flexibility with other appl - [Copy](#copy) - [Image Transform](#image-transform) - [Transcode](#transcode) + - [HLS](#hls) - [Transcribe](#transcribe) - [WAV Wrap](#wav-wrap) - [Detect Silence](#detect-silence) @@ -727,6 +728,108 @@ Output: } ``` +### HLS + +`HLS` tasks produce a set of assets from the job's source file. It's generally expected that the source file will be a video file of sufficiently-high resolution and quality (1080p, 2160p, etc), from which downscaled derivative videos and audio files (variants) will be created. Currently the only supported destination mode is `AWS/S3`. + +Currently all task configuration is handled using presets. + +Task output includes details about every asset generated by the task, including the master playlist and variants. Each task produces exactly one master playlist, and each variant produced will include exactly one media file and exactly one playlist. + +#### Presets + +The `HLS` task provides preset, which determines the specific encoding configuration and parameters that will be used to create the variants. Using presets reduces the amount of per-job configuration that's required, and makes the set of assets resulting from the task more predictable. + +When running a task with a preset, the resulting variants will be labeled. Each preset publishes a list of possible labels that may be included in the set of variants. For example, a preset may publish a list like `["480P", "720P", "1080P]`, to indicate that it is able to generate video variants at those three frame sizes. Any given job using that preset may not produce all possible variants. For example, if the source file is 720p, the preset configuration may only generate variants that are equal-to-or-smaller-than the source media (i.e., the job would not produce an upscaled 1080p variant). See below for details about specific presets. + +The variant details in the task output will include the appropriate label, so an application receiving the callback can easily extract information about a specific, expected variant. + +#### AWS/S3 + +The `BucketName` and `ObjectKeyPrefix` properties are required. + +For `AWS/S3` destinations, the contents of `Parameters` are set as options on [`#put_object`](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_object-instance_method), but should be listed using the format of [`ALLOWED_UPLOAD_ARGS`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html) from Boto3's `S3Transfer` class. For example, to set the content disposition of the object, use `ContentDisposition`, not `content_disposition`. + +Any `Parameters` set on the task will be used for all objects that are created. The `content-type` for each variant will be set automatically; if `Parameters.ContentType` is set on the destination, the value will be ignored. + +#### Presets + +- **Podcast Standard 2026:** tktk + +Input: + +```json +{ + "Type": "HLS", + "Preset": "Standard Podcast 2026 v1", + "Destination": { + "Mode": "AWS/S3", + "BucketName": "myBucket", + "ObjectKeyPrefix": "myPrefix/", + "Parameters": { + "CacheControl": "max-age=600", + "Metadata": { + "MyMetadataKey": "MyMetadataValue" + } + } + } +} +``` + +Output: + +```json +{ + "Task": "HLS", + "BucketName": "myBucket", + "ObjectKeyPrefix": "myPrefix/", + "Preset": { + "Name": "Standard Podcast 2026 v1", + "PossibleLabels": [ + "AUDIO", + "240P", + "360P", + "480P", + "720P", + "1080P", + "1440P", + "2160P", + "2880P", + "4320P", + "8640P", + ] + }, + "Assets": { + "MasterPlaylist": { + "ObjectKey": "myPrefix/index.m3u8" + }, + "Variants": [ + { + "PresetLabel": "AUDIO", + "Playlist": { + "ObjectKey": "myPrefix/audio.m3u8" + }, + "Media": { + "ObjectKey": "myPrefix/audio.ts", + "IncludesAudioStreams": true, + "IncludesVideoStreams": false + } + }, + { + "PresetLabel": "480P", + "Playlist": { + "ObjectKey": "myPrefix/480p.m3u8" + }, + "Media": { + "ObjectKey": "myPrefix/480p.ts", + "IncludesAudioStreams": false, + "IncludesVideoStreams": true + } + } + ] + } +} + ### Inspect `Inspect` tasks performs an analysis of the job's source file, and returns a set of metadata. The method of analysis and resulting data are determined by the type of the source file. From 01bfdbe95ce0a4ebd9aee9b116c82a45d57d7a6b Mon Sep 17 00:00:00 2001 From: Chris Kalafarski Date: Tue, 28 Jul 2026 16:45:20 -0400 Subject: [PATCH 2/3] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3c1a466a..e91510cb 100644 --- a/README.md +++ b/README.md @@ -738,7 +738,7 @@ Task output includes details about every asset generated by the task, including #### Presets -The `HLS` task provides preset, which determines the specific encoding configuration and parameters that will be used to create the variants. Using presets reduces the amount of per-job configuration that's required, and makes the set of assets resulting from the task more predictable. +The `HLS` task provides various presets, which determines the specific encoding configuration and parameters that will be used to create the variants. Using presets reduces the amount of per-job configuration that's required, and makes the set of assets resulting from the task more predictable. When running a task with a preset, the resulting variants will be labeled. Each preset publishes a list of possible labels that may be included in the set of variants. For example, a preset may publish a list like `["480P", "720P", "1080P]`, to indicate that it is able to generate video variants at those three frame sizes. Any given job using that preset may not produce all possible variants. For example, if the source file is 720p, the preset configuration may only generate variants that are equal-to-or-smaller-than the source media (i.e., the job would not produce an upscaled 1080p variant). See below for details about specific presets. From 687408c8039f2319855cf60923225cfc7db7f69e Mon Sep 17 00:00:00 2001 From: Chris Kalafarski Date: Tue, 28 Jul 2026 16:49:51 -0400 Subject: [PATCH 3/3] Add file name details --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e91510cb..51fcc256 100644 --- a/README.md +++ b/README.md @@ -742,13 +742,15 @@ The `HLS` task provides various presets, which determines the specific encoding When running a task with a preset, the resulting variants will be labeled. Each preset publishes a list of possible labels that may be included in the set of variants. For example, a preset may publish a list like `["480P", "720P", "1080P]`, to indicate that it is able to generate video variants at those three frame sizes. Any given job using that preset may not produce all possible variants. For example, if the source file is 720p, the preset configuration may only generate variants that are equal-to-or-smaller-than the source media (i.e., the job would not produce an upscaled 1080p variant). See below for details about specific presets. -The variant details in the task output will include the appropriate label, so an application receiving the callback can easily extract information about a specific, expected variant. +Individual variant details in the task output will include the appropriate label, so an application receiving the callback can easily extract information about a specific, expected variant. #### AWS/S3 The `BucketName` and `ObjectKeyPrefix` properties are required. -For `AWS/S3` destinations, the contents of `Parameters` are set as options on [`#put_object`](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_object-instance_method), but should be listed using the format of [`ALLOWED_UPLOAD_ARGS`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html) from Boto3's `S3Transfer` class. For example, to set the content disposition of the object, use `ContentDisposition`, not `content_disposition`. +File names for all files created by the task will begin with the `ObjectKeyPrefix`. For example, `"ObjectKeyPrefix": "myPrefix/"` may produce a files like `myPrefix/720p.ts` and `myPrefix/1080p.ts`. The prefix must include a trailing slash if directory-style file names are desired (i.e., `"ObjectKeyPrefix": "myPrefix"`, without a trailing slash, would produce `myPrefix720p.ts`). Other than the prefix, the names of the resulting files are determined by the task, and reported via the task results callback. + +The contents of `Parameters` are set as options on [`#put_object`](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Client.html#put_object-instance_method), but should be listed using the format of [`ALLOWED_UPLOAD_ARGS`](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html) from Boto3's `S3Transfer` class. For example, to set the content disposition of the object, use `ContentDisposition`, not `content_disposition`. Any `Parameters` set on the task will be used for all objects that are created. The `content-type` for each variant will be set automatically; if `Parameters.ContentType` is set on the destination, the value will be ignored.