Ingest a Video

SafeStream Ingest Overview

Ingesting a video allows SafeStream to prepare the video for watermarking. The source of the file is discarded but SafeStream keeps a version of the file in its secure storage for use in watermarking video. Each video only needs to be ingested once.

Ingesting a video requires you to include an http reference to the video file. We recommend that you use our Upload endpoint. Alternatively, SafeStream can ingest videos from any publicly accessible URL.

The initial file ingest will typically take between 25%-75% of the source video duration to complete. If forensic watermarking is enabled expect ingest to take longer.

Once SafeStream has ingested your video its ready to begin accepting on-demand watermarking requests. This means that you can use the ingested video to watermark videos on the fly in a fraction of the time of traditional watermarking methods. While the video ingest take ~25% of playback time, real-time watermarking can be completed in seconds.

🚧

Enabling Forensic Watermarking

For videos that you'd like to apply a forensic watermark to you need to set the payload property "enableForensic" to true. See above for the full request payload documentation.

Embedding a forensic watermark in videos of less than 5 minutes in duration is not supported.

📘

If callback url is specified

If a callback url was specified the final result will be posted back to the specified url. We will only attempt to post the results once.

Note we will only attempt to send results when the video is no longer in the PENDING state.

Please see here for encoding status overview.

CallbackUrls can contain any query parameters you choose. E.g. an HMAC signature with an expiration parameter for authentication purposes. This prevents the need for unauthenticated resources on the system receiving the callback.

We recommend configuring the expiration of an HMAC signature to be double the video length, plus a 3-4 hour buffer time. This buffer times allows for the callback to succeed despite long running jobs and/or temporary backups in ingest processing. E.g. an expiration signature for a 1 hour video would be 2 (double the video length) + 3 which is 5 hours.

Sample Callback Response

{
    "id": "038b6df7-9f5f-4de7-9517-2c8c8be9d7bc",
    "scope": "ds7uej83l0s9o2",
    "sourceUrl": "http://safestream.com/short-2.mp4",
    "key": "short-2",
    "encrypt": true,
    "allowHmacAuth": true,
    "enableForensic": true,
    "posterFrameUrl": "https://s3.amazonaws.com/videos.safestream.com/sdcujr849ksi/4b3c7c70-4ccd-43e3-803e-605136fdsdv94_large.jpg",
    "posterFrameTimeCode": 0,
    "status": "INGESTED",
    "bitRates": [
      "4000k"
    ],
    "targetBitRate": "4000k",
    "groupId": "",
    "filename": "",
    "description": "",
    "title": "",
    "width": 1280,
    "height": 720,
    "createdBy": "c56e21ee-b0c6-4948-9e20-eab170758c3a",
    "createdOn": 1492639705000,
    "updatedBy": "c56e21ee-b0c6-4948-9e20-eab170758c3a",
    "updatedOn": 1492640198000,
		"metadata": []
  }

🚧

Width and Height

We determine the width and height of a video during our ingest process. Until the video has a status of "INGESTED" the width and height will be 0.

👍

Next: Learn how to watermark your videos

Watermarking Documentation