Custom Trailer Configuration

Overview

Custom trailers let you publish a shortened version of a video to EngageKit. The configuration is stored at the project level and applied to every new piece of content imported or uploaded after the settings are enabled.

You can combine two parameters to control the desired length:

• durationInSeconds – An absolute upper bound, in seconds.
• durationPercentage – A percentage (1–100) of the original video length. The transcoder uses the smallest value between the computed percentage and the absolute cap.

When durationPercentage is omitted or null, the system relies solely on durationInSeconds. When both are absent, trailers cannot be generated.

Endpoint Summary

All endpoints require either a user-based Bearer token with project access or a project API key.

Retrieving the Configuration

GET https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/customTrailer
Authorization: Bearer <token>

Response Example

{
  "isEnabled": true,
  "durationInSeconds": 45,
  "durationPercentage": 40,
  "height": 720,
  "blur": {
    "isEnabled": true,
    "strength": 3
  },
  "generation": {
    "strategy": "equallyDistantSegments",
    "equallyDistantSegments": {
      "segments": 3,
      "segmentDurationSeconds": 6
    }
  }
}

Field Reference

• isEnabled (boolean) – Turns the feature on/off. When false, only blur defaults remain in the payload.
• durationInSeconds (number ≥ 1) – Max length, in seconds.
• durationPercentage (number 1–100 or null) – Optional percentage. If provided, the trailer length is min(durationInSeconds, percentage of original duration). If you omit both durationInSeconds and durationPercentage, enabling the feature will fail validation.
• height (number ≥ 1) – Vertical resolution of the generated trailer.
• blur – Options for producing a blurred variant for EngageKit:
  • isEnabled (boolean)
  • strength (number ≥ 0) – Required when isEnabled is true.
• generation – Controls how the trailer is assembled:
  • strategy – One of:
    • equallyDistantSegments – Picks evenly spaced snippets. Requires equallyDistantSegments.
    • continuousFromPercentage – Generates a single continuous segment. Requires continuousFromPercentage.
  • equallyDistantSegments – Provides segments (integer ≥ 1) and optional segmentDurationSeconds (number ≥ 1).
  • continuousFromPercentage – Provides startPercentage (0–100).

Updating the Configuration

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/configurations/customTrailer
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "isEnabled": true,
  "durationPercentage": 35,
  "height": 720,
  "blur": {
    "isEnabled": false
  },
  "generation": {
    "strategy": "equallyDistantSegments",
    "equallyDistantSegments": {
      "segments": 2,
      "segmentDurationSeconds": 5
    }
  }
}

Validation Rules

• isEnabled must be true to require height, generation, and at least one duration control (durationInSeconds or durationPercentage).
• durationPercentage accepts null only when durationInSeconds is supplied. A null percentage with no absolute duration is rejected.
• durationPercentage must be between 1 and 100 when set. Values at 0 or above 100 generate a validation error.
• For blur, strength is required when isEnabled is true and must be ≥ 0.
• Each generation strategy enforces its nested object:
  • equallyDistantSegments requires segments ≥ 1 and optional segmentDurationSeconds ≥ 1.
  • continuousFromPercentage requires startPercentage between 0 and 100.

Response

The endpoint returns the normalized configuration, mirroring the GET response. Fields that are not provided default as follows:

• blur.isEnabled defaults to false.
• durationPercentage is omitted when not supplied and null when explicitly cleared.

Trailer Generation Behavior

• When both durationInSeconds and durationPercentage are present, MP2 computes two candidates and picks the smallest duration.
• The transcoder enforces the height you specify; widths follow the original aspect ratio.
• Enabling blur produces two EngageKit files: the base trailer and its blurred derivative.
• If the configured rules produce no viable segments (for example, too many micro segments), no trailer files are attached.
• Disabling the feature removes the configuration from future transcodes but keeps previously generated assets intact.

Accessing Generated Trailers

Once the transcoder finishes, the trailers are published alongside the rest of the EngageKit bundle:

• Content list – GET https://api.fastevo.net/api/v1/projects/mediaProtection/contents now returns an engageKit array for every ready item. Each entry includes:
  • _id – EngageKit file identifier.
  • fileType – customTrailer for both the primary and blurred variants.
  • signedUrl – A short–lived URL (defaults to 1 hour) that can be downloaded directly. If blur is enabled, the blurred trailer URL contains -blurred in the filename.
• Single content – GET https://api.fastevo.net/api/v1/projects/mediaProtection/contents/{contentId} exposes the same engageKit array, making it easy to fetch fresh signed URLs on demand.

Example excerpt:

"engageKit": [
  {
    "_id": "67a2f8b0191f9a0012a9d317",
    "fileType": "customTrailer",
    "signedUrl": "https://<project-subdomain>.protected.delivery/.../videoTrailer/trailer-engage.mp4?Expires=..."
  },
  {
    "_id": "67a2f8b0191f9a0012a9d318",
    "fileType": "customTrailer",
    "signedUrl": "https://<project-subdomain>.protected.delivery/.../videoTrailer/trailer-blurred-engage.mp4?Expires=..."
  }
]

Signed URLs expire automatically; request the content again if a fresh URL is required. Existing assets are preserved, so previously generated trailers remain downloadable even if you later disable or change the configuration.

Webhook Notifications

When a transcoding job completes the contentStatusChanged webhook is fired (if enabled for the project). The payload includes the EngageKit breakdown so you can react without polling:

{
  "contentId": "667efed78de8c3000f8a2d02",
  "status": "ready",
  "details": {
    "contentType": "video",
    "durationInSeconds": 187,
    "maxResolution": "1080p",
    "engageKit": {
      "customTrailers": [
        "https://<project-subdomain>.protected.delivery/.../videoTrailer/trailer-engage.mp4",
        "https://<project-subdomain>.protected.delivery/.../videoTrailer/trailer-blurred-engage.mp4"
      ]
    }
  }
}

These webhook URLs point to the same CloudFront distribution used for EngageKit assets. Apply your usual signing logic (if applicable) before exposing these links to end users.

Troubleshooting

Related Resources

• Content Management
• EngageKit Assets
• Advanced Watermarks