HLS

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,110 @@ 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 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.
+
+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.
+
+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.
+
+#### 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.