Video Document Ingestion Template (ocli.aikp.document.video)

This task template packages video files (such as MP4, MOV, MKV, AVI, M4V) into adaptive bitrate HLS (HTTP Live Streaming) assets, prepares metadata documents (GeoJSON), uploads the transcoded streams to S3 private storage, and registers the documents with the PostGIS database.

What It Does

  1. Transcoding: Takes an input video file and transcodes it using ffmpeg into two adaptive bitrate HLS variant streams:

    • HEVC/H.265 (High-efficiency): Standard main stream for compatible modern devices (e.g. Safari, modern macOS/iOS, edge).

    • H.264/AVC (High-compatibility): Fallback stream for older platforms and legacy browsers.

  2. Master Playlist: Generates a master playlist (index.m3u8) referencing both variants.

  3. GeoJSON Metadata: Generates a coordinate-centered GeoJSON document representing the video capture point. The properties include the geographic location (centroid), S3 bucket metadata, and Role-Based Access Control (RBAC) groups (roles) fetched from the environment defaults (defaults.yaml) or task recipe.

  4. Upload: Automatically uploads the HLS master playlist, stream directories, and segment files (.ts) privately to the AWS S3/Object Store.

  5. Database Registration: Publishes the resulting GeoJSON document into the PostGIS features table.

Configuration

When creating and configuring a task, the following parameters are supported:

Task Configuration (in task.config)

  • file_path (string, required): The local file path to the input video file.

  • lat (float, required): The latitude coordinate of the capture location.

  • lon (float, required): The longitude coordinate of the capture location.

  • output_file_name (string): The base filename for the master playlist (defaults to index.m3u8).

  • friendly_name (string): A pattern for generating the human-readable document label.

  • cos_key (string): The path prefix pattern under which files are uploaded to the S3 bucket.

Recipe Configuration (in recipe.yaml)

  • properties.roles (list of strings): The OIDC JWT group names allowed to access this video. If empty or missing, access is denied to everyone (secure-by-default).

Usage Example

# 1. Create a task using the video template
ocli task create -t ocli.aikp.document.video -n traffic-cam-01 --activate

# 2. Configure video location and access control roles
ocli task set file_path="/data/cams/traffic.mp4" lat=52.3702 lon=4.8952

# 3. Compile the recipe configuration
ocli task make recipe --override

# 4. Transcode the input video into suitable for streaming on a web format.
ocli task template assemble

# 5. Generate document metadata
ocli ai makegeojson

# 6. Upload files to Object Store and Publish into DB
ocli ai upload
ocli ai publish post