Add new APIs for Ad Engine

adengine/how-to/image.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 10
+sidebar_label: Image
+---
+
+# Image Generation
+
+The **Image API** provides a simple way to extract a single image frame from a media asset stored in the cloud. It is commonly used to generate images without downloading or transcoding the full media file.
+
+The image is captured at a specific position in the source video and returned in a standard image format.
+
+## Use Cases
+
+The Image API is typically used to:
+
+- Generate thumbnail images for media assets
+- Create preview frames for asset browsers or dashboards
+- Perform quick visual verification of content
+- Support quality control and asset review workflows
+- Extract still frames without creating intermediate proxies
+
+This endpoint is optimized for **fast, lightweight, on-demand image extraction**.
+
+## Image API
+
+The Image API is accessed using an HTTP GET request with query parameters.
+
+```
+GET https://api.galaxy.dolbyrasp.com/image?url=https://my_bucket/my_folder/my_file.mxf&format=png&height=280
+```
+
+### Required Query Parameters
+
+- **url**  
+  The URL of the media file to extract the image from.
+
+### Optional Query Parameters
+
+- **format**  
+  The image format to return.  
+  Supported values: `jpeg`, `png`  
+  Default: `jpeg`
+
+- **width**  
+  The desired width of the image in pixels.  
+  If not specified, the width is calculated based on the source dimensions. If only width is specified, height is calculated from the source aspect ratio.
+
+- **height**  
+  The desired height of the image in pixels.  
+  If not specified, the height is calculated based on the source dimensions. If only height is specified, width is calculated from the source aspect ratio.
+
+- **offset_percent**  
+  The percentage offset into the video where the image should be captured.  
+  Range: `0–100`  
+  Default: `10`
+
+- **credentials_key**  
+  The key of stored credentials to use when accessing the media URL.
+
+### Using Credentials
+
+Typically, cloud content is not publicly accessable. If the provided `url` is an encrypted link, remember to use `encodeURI()` to encode the URL inside the GET call. If you have registered cloud credentials with the Dolby OptiView Engine, you can reference those credentials in the call.
+
+```
+GET https://api.galaxy.dolbyrasp.com/image?url=s3://my_bucket/my_folder/my_file.mxf&format=png&height=280&credentials_key=my_s3_creds
+```
+
+## Response
+
+The response is a binary image returned directly in the requested format.
+
+- `Content-Type: image/jpeg` or `image/png`
+- The response body contains the image data
+
+This endpoint does not return JSON metadata; the response payload is the image itself.
+
+## Notes
+
+- The Image API is read-only and does not modify the source asset.
+- The exact frame captured depends on source encoding and GOP structure.
+- Width and height constraints are validated by the service.

adengine/how-to/media-info.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 9
+---
+
+# Media Info
+
+The **Media Info** endpoint provides a fast, normalized view of the technical characteristics of a media asset stored in the cloud. The Media Info API inspects a media file and returns a structured JSON response describing the container, duration, bitrate, and all detected tracks (video, audio, timecode, and others).
+
+## Use Cases
+
+The Media Info API is commonly used to:
+
+- Inspect unfamiliar or third-party assets
+- Validate source media before encoding or preview
+- Drive conditional logic in automated workflows
+- Confirm track counts, codecs, and durations
+- Extract timecode and technical metadata for QC
+
+It is often used as a **first step** before invoking preview, encoding, or ad-processing APIs.
+
+## Media Info Endpoint
+
+The Media Info endpoint is accessed using a simple HTTP GET request. You provide an accessible media URL as a query parameter.
+
+```
+https://api.galaxy.dolbyrasp.com/media-info?url=https://my_bucket/my_folder/my_file.mov
+```
+
+The response is returned as normalized JSON, making it easy to consume programmatically or inspect manually.
+
+If the `url` is an encrypted link, make sure to use encodeURIComponent() to modify the `url` so that it can be correctly handled by the GET call.
+
+## Media Info Response
+
+The Media Info response is divided into two main sections:
+
+- **file** — container-level metadata about the asset
+- **tracks** — an array describing each detected track
+
+The `file` object summarizes the overall media asset:
+
+```json
+{
+  "file": {
+    "id": "file0",
+    "name": "my_file.mov",
+    "path": "https://my_bucket.s3.us-east-1.amazonaws.com/",
+    "format": "QuickTime / MOV",
+    "last_modified": "Mon, 05 Aug 2024 19:58:46 GMT",
+    "size_bytes": 948427028,
+    "bitrate_kb": 66849.5,
+    "duration_sec": "113.500000",
+    "video_tracks": 1,
+    "audio_tracks": 1,
+    "timecode_tracks": 1
+  }
+}
+```
+
+### Key Fields
+
+- **name** – File name extracted from the URL
+- **format** – Container format
+- **size_bytes** – File size in bytes
+- **bitrate_kb** – Average bitrate of the asset
+- **duration_sec** – Duration of the file in seconds
+- **video_tracks / audio_tracks / timecode_tracks** – Track counts by type
+
+The `tracks` array provides detailed information about each individual track detected in the file.
+
+```json
+{
+  "tracks": [
+    {
+      "kind": "video",
+      "codec": "prores",
+      "duration": 113.5,
+      "bitrate_kb": 65312.4,
+      "width": 1920,
+      "height": 1080,
+      "frame_rate": "24/1",
+      "range": "sdr"
+    },
+    {
+      "kind": "audio",
+      "codec": "pcm_s16le",
+      "duration": 113.5,
+      "bitrate_kb": 1536,
+      "sample_rate": 48000,
+      "channels": 2,
+      "channel_layout": "stereo",
+      "channel_placement": "FL FR"
+    },
+    {
+      "kind": "timecode",
+      "duration": 113.5,
+      "start_timecode": "01:00:00:00"
+    }
+  ]
+}
+```

adengine/how-to/quality-control.md

@@ -2,7 +2,7 @@
 sidebar_position: 6
 ---
 
-# Quality Control
+# Ad Quality Control
 
 One of the realities of ads is that there are many instances where the ad source can be problematic. These types of problems can include things like too long duration, too short duration, too small dimensions, too low of a bitrate, etc. A bad ad can look bad, sound bad, or simply stall your player, so it is important to verify the quality of the ad.
 
@@ -75,4 +75,4 @@ The Ad Engine inlcludes both source and output QC. The `pre` object defines the
 
 ### QC Conditions
 
-The QC `conditions` is an object that defines `pass` and `fail` conditions. You can define a condition either as a `pass` condition that must be true, or a `fail` condition that will generate a failure. In our above example, we are using the `pass` condition -- meaning that each condition must evaluate to `true` in order for the file to pass QC. The QC decision can be defined by a [math.js](https://mathjs.org/) string, which allows for complex operations if needed.
+The QC `conditions` is an object that defines `pass` and `fail` conditions. You can define a condition either as a `pass` condition that must be true, or a `fail` condition that will generate a failure. In our above example, we are using the `pass` condition -- meaning that each condition must evaluate to `true` in order for the file to pass QC. The QC decision can be defined by a `math.js` string, which allows for complex operations if needed.

adengine/index.mdx

@@ -71,3 +71,16 @@ VAST files typically reference the ad master stored on the ad server. The OptiVi
 The Ad Engine can be used as part of the OptiView suite of services, including the OptiView Player, Streaming, and Ads. The Ad Engine facilitates preparing ads for any scenario, including Server-Guided Ad Insertion (SGAI). The low latency of the Ad Engine is particularly important when the OptiView Player is getting ads directly without them being stitched into the stream by the streaming engine. OptiView Ads manages the ad signaling and coordination between the various components. Here is an outline of the architecture in this scenario:
 
 ![OptiView Ad Engine Architecture](./assets/img/ad-engine-sgai-ad-insertion.svg)
+
+### Cloud Preview Capabilities
+
+In addition to rapid ad processing, the Ad Engine can generate **cloud-based previews** of media assets that are not natively streamable. A common use case is previewing high-quality master files encoded in formats such as Dolby Vision and Dolby Atmos. These master assets often have extremely high bitrates (for example, 800 Mbps or more) and are therefore unsuitable for direct streaming.
+
+The Ad Engine addresses this by **transcoding master files on-the-fly into streamable formats**, enabling immediate playback in a web browser. This allows customers to perform quality control directly in the cloud, without the need to generate or store intermediate proxy files.
+
+Cloud Preview output is compatible with any HLS-capable player. In addition, Dolby provides built-in support for the following multi-track players:
+
+- **Codemill Accurate Player** — https://www.codemill.com
+- **Omakase Player** — https://player.byomakase.org
+
+These multi-track players allow you to view multiple video, audio, and sub-title files in a single timeline with video thumbnails and audio waveforms.