Actions provided by the job system

Global parameters applicable on all actions:

Parameter Type Description
run_next_on_failure Boolean Will cause the job to run the next action when the action with this field on fails, and then fail the job after the next action have finished
skip_if_previous_skipped Boolean Will skip the action if the previous action was skipped
skip_if_previous_succeeded Boolean Will skip the action if the previous action was successful

ANALYZE_FILE

Analyze a file, extracting metadata about file format, bitrate, sample rate etc and posting said data back to the adapter.

Inputs

Parameter Type Description
source_path String Url to the file that should be analyzed
source_file_id String File id for the source file, this is used to post back the analysis data to the adapter
force Boolean By default the analysis is skipped if the file already have a container set, to run it anyway set this to true.

Outputs

Parameter Type Description
analyze:file_type String File type of the analyzed file
analyze:container_format String Container format of the analyzed file

ASSET_CLEANUP

Will remove a given asset if the job fails. Needs to be added first in the list of actions in the job to work correctly.

Inputs

Parameter Type Description
asset_id String Asset id of asset to remove on job failure
file_delete_policy String File delete policy, defaults to detach
retain_file_tag String Comma separated list of tags for files that should only be detached, not deleted. Only relevant if file_delete_policy=delete, defaults to none.

ASSET_METADATA_UPDATE

Update asset metadata. Only metadata fields with prefix metadata: will be considered, and will be added to the asset metadata. Use variable substitution to extract actual data from the job.

Inputs

Parameter Type Description
asset_id String The asset to update metadata on
metadata:X String Update metadata field X to the given value

ATTACH_FILE

Attach a file to an asset.

Inputs

Parameter Type Description
asset_id String Asset to attach the file to
file_id String File to attach

ATTACH_TO_PARENT

Attach an asset to a parent asset.

Inputs

Parameter Type Description
child_asset_id String Asset to attach to a parent asset
parent_asset_id String Parent asset to attach to (optional)
parent_filter String If parent_asset_id is not given, look up assets with the given filters. If filters map to more than one asset the action will fail
parent_missing_timeout Duration If parent_asset_id is not given, and asset lookup is performed based on filters and no assets is found, wait and retry until the given timeout has passed before failing the action.

BATON_IMPORT

Import baton as timespans on a given asset.

Inputs

Parameter Type Description
original_file_type String Used to check if action should be run, must be BATON, or action will be skipped
asset_id String Asset to add timespans to
source_path String Url to source baton file

BUILD_TRANSCODE_JOB

Check if the given file needs to be transcoded into a different lowres format or have audio extracted. If file needs to be transcoded, a new RENDER job will be created to perform the actions derived.

Inputs

Parameter Type Description
original_file_type String If set to something other than VIDEO, action will be skipped
transcode_file_id String File to check transcode needs for
audio_extract_template_id String Preset id to use for audio extraction
lowres_template_id String Preset id to use for lowres transcode
audio_extract_max_output_channels Integer Maximum amount of audio channels per extracted audio file, defaults to 8
audio_extract_min_input_channels Integer Cutoff used to determine if audio extraction needs to be performed, defaults to 9
lowres_file_suffix String Filename suffix used for lowres video files, defaults to _v.mp4
audio_extract_file_suffix String Filename suffix used for audio extract files, defaults to _a.wav
target_path String Base path on given storage where files should be stored, defaults to a generated UUID
target_storage_id String Storage to put transcoded files on
force_audio_extract Boolean If audio extraction should be forced, defaults to false
force_lowres Boolean If lowres creation should be forced, defaults to false
force_audio_output_per_track Boolean If audio tracks should be extracted to separate audio files per track, defaults to false
lowres_tag String Tag to set on lowres files in AV, defaults to mp4
audio_extract_tag_base String Tag prefix to set on audio extracted files in AV, defaults to wav
transcode_render_backend String Render backend to use for transcode, defaults to ffmpeg

Outputs

Parameter Type Description
transcode_job_id String Job id of any potentially queued transcode job
result:X String (Multiple) Any metadata field on the queued transcode job with prefix result: is propagated here

COPY_FILE

Copy a file to a target location, either a storage or an HTTP url.

Inputs

Parameter Type Description
source_file_id String Id of source file
source_storage_id String Source storage to use to transfer from, if not given it will take the first available file location from the file
target_storage_id String Target storage to transfer to, if not given target_path will be assumed to be an HTTP url
target_path String Target location to copy file to
append_filename Boolean If set, target_path is assumed to be a folder, and the current filename from the source location will be added to the target filename
cache_control String Set cache-control for S3 upload
content_encoding String Set Content-Encoding for S3 upload
http_method String Http method to use for external upload (default is PUT)
content_type String Content-Type to use for external upload
external Boolean If set, target_path is assumed to be a valid HTTP url that the file will be uploaded to
target_uri_exist_policy String Policy on what to do if target URI already exist, defaults to abort

Valid values for target_uri_exist_policy are:

  • abort - aborts the job
  • overwrite - overwrites the file
  • increment - compute a new filename and try again
  • ignore - do not perform action but continue job with the old file in place

DELETE_FILE_LOCATION

Delete a single physical file from a storage.

Inputs

Parameter Type Description
file_id String Id of the file to delete
storage_id String Id of the file to delete the file from

ELEMENTAL_RENDER

Run AWS Elemental render job for the given timeline.

Inputs

Parameter Type Description
target_storage_id String Target storage to write Elemental output to, must be an S3 storage
aws_role String AWS role ARN for the IAM role to give to Elemental
template_id String Elemental preset to use for the rendering, only used by implicit outputs not defined by outputs
black_frame_location String S3 url to a black frame file to use for the render black frames (if needed)
black_frame_duration Integer Duration in frames of the given black frame file
black_frame_numerator Integer Frame rate numerator of the given black frame file, defaults to 25
black_frame_denominator Integer Frame rate denominator of the given black frame file, defaults to 1
file_output String Root location S3 url for the file output
video_file_modifier String Filename suffix used for video files created by Elemental, only used by implicit outputs not defined by outputs
file_group_name String File group name (Elemental field), defaults to File Group
timeline TimespanDto[] The timeline to render, encoded in Json
outputs FileInputDto[] The outputs that Elemental should create, encoded in Json, see below for more information

If outputs is defined, all outputs are assumed to be in that list and the implicit fields (video_file_modifier, template_id etc) will not be used. The following fields in FileInputDto will be used:

Field Type Description
fileName String The filename of the target file. Do note that the action will make a best effort here, as there is no way to completely control the output filename when using Elemental
metadata.template_id String The AWS Elemental preset to use for the output
metadata.straight_channel_remix Integer[] Audio mixing setup where each channel will only have full transfer from a single channel, based on the given list. The first channel in the output will be taken from the channel number on index 0 in the given list. The list should be encoded in json
metadata.mix_matrix AudioMixDto Full audio mix matrix, encoded in json.

If outputs is not defined, an implicit output with a straight channel remix will be created using the following fields:

  • video_file_modifier
  • template_id

Outputs

Parameter Type Description
elemental_job_id String AWS Elemental job id
elemental_queue_time Instant Time when the Elemental job was created
elemental_name_modifiers String[] File name modifiers for all requested output files
elemental_file_output.X String Filename on the given S3 storage of output X in the given outputs

EXPORT_FILE

Download the given file to the local filesystem on the runner.

Inputs

Parameter Type Description
source_file_id String File to download
target_uri String Location on local filesystem to download the file to
target_uri_exist_policy String Policy on what to do if target URI already exist, defaults to abort

Valid values for target_uri_exist_policy are:

  • abort - aborts the job
  • overwrite - overwrites the file
  • increment - compute a new filename and try again
  • ignore - do not perform action but continue job with the old file in place

Outputs

Parameter Type Description
source_storage_id String Id of the source storage the file was downloaded from
target_path String Filename on local filesystem the file was downloaded to

FFMPEG_RENDER

Run FFMPEG render job for the given timeline.

Inputs

Parameter Type Description
target_path String File on local workspace to write the output to, only used for implicit outputs not defined by outputs
template_id String Elemental preset to use for the rendering, only used by implicit outputs not defined by outputs
timeline TimespanDto[] The timeline to render, encoded in Json
outputs FileInputDto[] The outputs that should be created, encoded in Json, see below for more information

If outputs is defined, all outputs are assumed to be in that list and the implicit fields (target_path, template_id etc) will not be used. The following fields in FileInputDto will be used:

Field Type Description
fileName String The filename of the target file.
metadata.template_id String The FFMPEG preset to use for rendering the output
metadata.straight_channel_remix Integer[] Audio mixing setup where each channel will only have full transfer from a single channel, based on the given list. The first channel in the output will be taken from the channel number on index 0 in the given list. The list should be encoded in json
metadata.mix_matrix AudioMixDto Full audio mix matrix, encoded in json.

If outputs is not defined, an implicit output with a straight channel remix will be created using the following fields:

  • target_path
  • template_id

Outputs

Parameter Type Description
ffmpeg_file_output.X String Filename on the given S3 storage of output X in the given outputs

GET_TIMELINE

Retrieves a timeline, or builds a timeline from given parameters. Also expands all timeline segments with file information, such as frame rate, duration, url to the actual file (remote location), start timecode etc

Inputs

Parameter Type Description
timeline TimespanDto[] Timeline given directly as input, encoded in Json
asset_id String Retrieve the timeline from the given asset, will retrieve all timespans with type=timeline
implicit_timeline_file_id String Build a timeline with a single segment for the full duration of the given file
implicit_timeline_asset_id String Build a timeline with a single segment for the full duration of the first video file in the given asset with tag=original
expand_timeline_from_video_track Boolean If true, will create timeline segments for all audio tracks/channels in the source file, matching the given timeline clips for the video track

Outputs

Parameter Type Description
timeline TimespanDto[] The full expanded timeline

IMPORT_FILE

Upload a file from the local filesystem to an AV storage or an external HTTP url. If uploaded to an AV storage, the file will also be indexed in the adapter.

Inputs

Parameter Type Description
source_path String Location on filesystem of the file to import
target_storage_id String Storage to upload file to, if not given and external is set to false, the file will be uploaded to default storage
target_path String Location on the given storage to upload the file to
file_type String The file type to set on the file when indexing in the adapter
target_uri_exist_policy String Policy on what to do if target URI already exist, defaults to abort, see EXPORT_FILE for more information
cache_control String Set cache-control for S3 upload
content_encoding String Set Content-Encoding for S3 upload
http_method String Http method to use for external upload (default is PUT)
content_type String Content-Type to use for external upload
external Boolean If set, target_path is assumed to be a valid HTTP url that the file will be uploaded to

Outputs

Parameter Type Description
target_path String Resulting filename on the AV storage
target_file_id String File id of the indexed file in the adapter

INDEX_FILE

Index an existing file on a storage, will not transfer any files. If transfer from local storage is also need, use IMPORT_FILE instead.

Inputs

Parameter Type Description
storage_id String Storage where file is located
file_name String Filename on the given storage
file_type String The file type to set on the file when indexing in the adapter

Outputs

Parameter Type Description
target_path String Resulting filename on the AV storage
target_file_id String File id of the indexed file in the adapter

MANIFEST_INGEST

Parse the given manifest file and create a new ingest job based on its contents. Manifest files are a description of metadata and files that together should be ingested as a single asset. Our own format use AssetInputDto for the manifest files.

Inputs

Parameter Type Description
asset_id String The id of the asset to ingest to. Optional, if not given a new asset will be created.
source_path String Url to the manifest file
storage_id String The id of the storage where the manifest file is housed. Only required if the manifest file refers to other files on the same storage using relative paths
storage_path String The filename on the storage for the manifest file. Only required if the manifest file refers to other files on the same storage using relative paths
manifest_format String The file format of the manifest file, see below for more information
ingest_template_id String The job template to use for the ingest job, defaults to ingest

Manifest formats supported:

  • If empty, manifest file is assumed to be in AssetInputDto format, encoded in Json
  • X - if configuration property av.runner.manifest_reader_location is set, we assume X is a custom format, and a custom script will be run to produce the end result:
  • If configuration property av.runner.manifest_reader.X exist, we use the value of that configuration property as the script filename, and lookup that in av.runner.manifest_reader_location.
  • If configuration property av.runner.manifest_reader.X does not exist, we use X as the script filename, and lookup that in av.runner.manifest_reader_location
  • The script is called with the following parameters reader_location/script input_path output_path. The output must be a json file in AssetInputDto format.

Outputs

Parameter Type Description
ingest_job_id String Job id of the created ingest job
result:X String (Multiple) Any metadata field on the queued ingest job with prefix result: is propagated here

MARKER_EXPORT

Export a subset of the markers for an asset using a given destination format.

Inputs

Parameter Type Description
asset_id String The asset id to export marker timespans from
timespan_type String Optional timespan type to export, if not given all types will be exported
destination_format String The file format to export in, for valid values see below
target_path String The filename to export to
csv_separator String The separator to use when exporting in CSV format, defaults to ,
csv_fields String The set of metadata fields to export with exporting in CSV format. Comma separated string, defaults to name,description,subtype
frame_rate_numerator Integer Frame rate to use for timecodes in the exported data
frame_rate_denominator Integer Frame rate to use for timecodes in the exported data
dropframe Boolean Drapframe indicator to use in exported data
filter:X String Metadata filters used to reduce the number of timespans to export, see below for more information. Multiples allowed

Supported destination formats

  • xml - export in XML format using ur in house DTO format
  • json - export in Json format uing our in house DTO format, also used if no destination format is given in request
  • csv - export in CSV format, will export the following data (in order):
  • timespan id, String
  • start frame, Integer
  • start framerate, decimal format (29.97), Float
  • start timecode, SMPTE format, String
  • end frame, Integer
  • end framerate, decimal format (29.97), Float
  • end timecode, SMPTE format, String
  • frame duration, Integer
  • clock time duration in seconds, Float
  • runtime, SMPTE format, String
  • metadata fields in order as requested in csv_fields
  • X - if configuration property timespan_writer_location is set, we assume X is a custom format, and a custom script will be run to produce the end result:
  • If configuration property timespan_writer.X exist, we use the value as the script filename, and lookup that in timespan_writer_location.
  • If configuration property timespan_writer.X does not exist, we use X as the script filename, and lookup that in timespan_writer_location
  • The script is called with the following parameters
    • writer_location/script input_path output_path frame_rate_numerator frame_rate_denominator dropframe. The input is the timespan list in JSON format

Filters

Filters can be applied to the set of timespans to export using filter:X metadata fields on the action request. If given, the set of timespans will be filtered on metadata field X having the given value.

MARKER_IMPORT

Import a set of the markers to an asset using a given source format.

Inputs

Parameter Type Description
asset_id String The asset id to import timespans to
timespan_type String Optional timespan type to use for import, will be set on all timespans
source_format String The file format of the import file, for valid values see below
source_path String Url to the file to import
csv_separator String The separator to use when exporting in CSV format, defaults to ,
frame_rate_numerator Integer Frame rate to use for timecodes in the imported data
frame_rate_denominator Integer Frame rate to use for timecodes in the imported data
dropframe Boolean Drapframe indicator to use in imported data
metadata:X String Metadata values to set on all imported timespans, will cause metadata field X to be set to the given value. Multiples allowed.

Supported source formats

  • xml - import in XML format using our in house DTO format
  • json - import in Json format using our in house DTO format, also used if no source format is given in request
  • csv - import in CSV format, will assume each line contain the following fields:
  • start frame, String, on formats frame@num/denom, seconds(Float) or smpte@num/denom
  • end frame, String, on formats frame@num/denom, seconds(Float) or smpte@num/denom
  • name
  • description
  • subtype
  • X - if configuration property timespan_reader_location is set, we assume X is a custom format, and a custom script will be run to produce the end result:
  • If configuration property timespan_reader.X exist, we use the value as the script filename, and lookup that in timespan_reader_location.
  • If configuration property timespan_reader.X does not exist, we use X as the script filename, and lookup that in timespan_reader_location.
  • The script is called with the following parameters reader_location/script input_path output_path frame_rate_numerator frame_rate_denominator dropframe.
  • The output must be a list of timespans in JSON format using our inhouse DTO schema.

POSTER

Attempt to extract a poster image from a video file.

Inputs

Parameter Type Description
original_file_type String If set to something other than VIDEO, action will be skipped
source_path String Url to source video file
source_file_id String File id for source file, this is used to post back updates to the adapter.
target_path_poster String Path to output file on local filesystem
frame Integer Specific frame to capture. Frame in the format frame@num:den, if only frame is supplied num is interpreted as 705600000 and den as 1 (flicks). If only num is provided, den is set to 1. If not supplied a frame is selected automatically.
region_source_in String Upper left corner of clip region, in format XxY, example: 20x10
region_source_out String Lower right corner of clip region, in format XxY, example: 20x10
destination_resolution String Scale result to the given resolution, in format WxH, example: 1920x1080

Outputs

Parameter Type Description
file_type String File type of resulting file, always STILL_FRAME
poster:resolution String Resolution of poster, in format WxH
poster:timestamp String Timestamp of poster, in format frame@num:den
poster:output String Path to output file on local filesystem

REKOGNITION_MEDIA_ANALYSIS

Run AWS Rekognition to perform media segment analysis, and add results as timespans on the given asset.

Inputs

Parameter Type Description
asset_id String Asset to store timespans on
file_id String File to analyze
file_location_id String File location to use for analysis
segment_type String (Multiple) The segment types to analyze, available values are technical_cue and shot, defaults to technical_cue and shot
label_type String (Multiple) The label types to analyze, available values are content_moderation and label_detection, defaults to content_moderation and label_detection
shot_confidence Float Confidence value for shot segments, defaults to 80.0
technical_cue_confidence Float Confidence value for technical cue segments, defaults to 80.0
content_moderation_confidence Float Confidence value for content moderation, defaults to 80.0
label_detection_confidence Float Confidence value for label detection, defaults to 80.0

Outputs

Parameter Type Description
rekognition_job_id String Segment detection AWS Rekognition job id
content_moderation_job_id String Content moderation AWS Rekognition job id
label_detection_job_id String Label detection AWS Rekognition job id

RESULT

Extract results from the job and add it to the job metadata.

Inputs

Parameter Type Description
result:X String (Multiple) Add value to job metadata with key result:X

SHELL

Run a shell command line action.

Inputs

Parameter Type Description
command String (Multiple) The command line to run.
cleanup String (Multiple) A command line to run if the action fails
timeout Integer Timeout in seconds, defaults to 1800 (30 minutes)

SPRITE_MAP

Build spritemap and manifest from a video file.

Inputs

Parameter Type Description
original_file_type String If set to something other than VIDEO, action will be skipped
source_path String Url to source video file
source_file_id String File id for source video file, used to get frame rate, duration, aspect ratio etc
frame_rate_numerator Integer Specify frame rate directly, overrides source_file_id
frame_rate_denominator Integer Specify frame rate directly, overrides source_file_id
image_width Integer Thumbnail width, defaults to 240
image_height Integer Thumbnail height, defaults to 135
video_aspect Double Manually specify the aspect ratio instead of using the source file container
interval_seconds Double Interval between thumbnails in seconds
interval_frames Integer Interval between thumbnails in frames
interval_count Integer Set the total number of thumbnails to approx this number. Requires source_file_id be set and have a video stream with a duration.
output_manifest String Output manifest file, defauls to out.json
output_spritemap String Output spritemap file, defaults to out.jpg

Notes on image_width/image_height: Just one of these may be supplied, in which case the other one is calculated from the aspect ratio. If an aspect ratio is set the thumbnails will keep the aspect ratio and the image size is treated as a max size.

If frame_rate_* is not specified, source_file_id must be set and have a container with a video stream with a valid frame rate. If not both of image_* is given, either video_aspect must be set or source_file_id must be set and have a container with a video stream with an aspect ratio.

If no interval is set, the default is 5s.

STORAGE_REFRESH

Perform storage refresh on a single given storage

Inputs

Parameter Type Description
storage_id String Storage to refresh
force_refresh Boolean Ignore refresh interval and force a refresh, defaults to false

SUBTITLE_EXPORT

Export a subset of the markers for an asset using a given destination format.

Inputs

Parameter Type Description
asset_id String The asset that contain the timespans to export
target_path String The destination file on local disc to export subtitles to
destination_format String The subtitle file format to export subtitles in. Valid values: webvtt, srt
identifier String If given, filter the subtitle timespans on metadata field 'identifier'
language String If given, filter the subtitle timespans on metadata field 'language'
subtitle_type String If given, filter the subtitle timespans on metadata field 'subtitle_type'

SUBTITLE_IMPORT

Import subtitle file as timespans on the given asset.

Inputs

Parameter Type Description
original_file_type String Used to check if action should be run, must be SUBTITLE, or action will be skipped
asset_id String Asset to import subtitle timespans to
source_path String Location of subtitle file
language String Optional language, will be set as metadata field on resulting timespans
subtitle_type String Subtitle type, will be set as metadata field on resulting timespans, defaults to 'closed'
identifier String Subtitle identifier, will be set as metadata field on resulting timespans, defaults to filename portion of source_path
analyze:container_format String Subtitle file format, valid values are: ttml, scc, webvtt, srt or cap

TEMPLATE

Expand a template to a set of jobs, queue said jobs and wait for them to complete. See job template documentation for more information on the templates themselves.

Inputs

Parameter Type Description
template_id String The id of the template to use
file_id String (Multiple) File to fetch from the backend and supply to the template in the files parameter
asset_id String (Multiple) Asset to fetch from the backend and supply to the template in the assets parameter
files FileInputDto[] List of files to supply to the template in the files parameter

Outputs

Parameter Type Description

WAIT_FOR_JOB

Waits for a set of jobs to complete.

Inputs

Parameter Type Description
wait_for_job_id String (Multiple) Id of job to wait for

Outputs

Parameter Type Description
result:X String (Multiple) Any metadata field on the dependent jobs with prefix result: is propagated here

WAVEFORM

Generate Waveform PCM files for a given video/audio file.

Inputs

Parameter Type Description
source_path String File to extract waveforms from
target_path_prefix String Prefix to use for created files, they will get filenames like ${target_path_prefix}_${track}_${resolution}.pcm
tracks Integer Number of audio tracks in the file
sample_rate_modifier Integer[] List of sample rate modifiers for the generated waveform files (2, 32, 500 default)
channels.X Integer Number of audio channels in track X

Outputs

Parameter Type Description
waveform_file.X.Y String (Multiple) The target filename of the waveform file for track X and sample rate modifier Y