Assets and Images — CmdCal Docs

Image Sources

The PaperImage node supports three source formats via the src and svgSrc fields:

HTTPS URLs

JSON

{
  "type": "Image",
  "style": { "position": "absolute", "left": 60, "top": 100, "width": 400, "height": 300 },
  "src": "https://example.com/photo.png"
}

The engine fetches the image at render time and embeds it in the PPTX archive. Supported formats: PNG, JPEG, GIF, BMP, TIFF, WMF, EMF.

Base64 Data URLs

JSON

{
  "type": "Image",
  "src": "data:image/png;base64,iVBORw0KGgoAAAANS..."
}

Inline images avoid network fetches and are deterministic across renders.

SVG Embedding

Use svgSrc for native SVG embedding with a raster src as the fallback (required by OOXML for older PowerPoint versions):

JSON

{
  "type": "Image",
  "style": { "position": "absolute", "left": 60, "top": 100, "width": 200, "height": 200 },
  "src": "https://example.com/logo.png",
  "svgSrc": "https://example.com/logo.svg"
}

PowerPoint 2019+ renders the SVG natively; older versions fall back to the raster src.

Image Effects

The imageEffects property applies visual adjustments at the OOXML level:

TYPESCRIPT

interface ImageEffects {
  brightness?: number;   // -100 to 100 (percentage adjustment)
  contrast?: number;     // -100 to 100 (percentage adjustment)
  grayscale?: boolean;   // Convert to grayscale
  biLevel?: number;      // Black/white threshold (0-100000)
  duotone?: {
    color1: ColorValue;  // Shadow color
    color2: ColorValue;  // Highlight color
  };
  blur?: number;         // Blur radius in pixels
}

Example: Duotone Brand Image

JSON

{
  "type": "Image",
  "style": { "position": "absolute", "left": 0, "top": 0, "width": 960, "height": 540 },
  "src": "https://example.com/hero.jpg",
  "imageEffects": {
    "duotone": {
      "color1": "#0F172A",
      "color2": "#2563EB"
    }
  }
}

Cropping

The crop property trims edges as a percentage of the original image dimensions:

JSON

{
  "type": "Image",
  "src": "https://example.com/wide-photo.jpg",
  "style": { "position": "absolute", "left": 60, "top": 100, "width": 400, "height": 300 },
  "crop": {
    "left": 10,
    "top": 5,
    "right": 10,
    "bottom": 15
  }
}

Each value is a percentage (0-100) of that edge to remove.

Border Radius

Apply rounded corners to images via borderRadius (in pixels). The engine converts this to a roundRect geometry clip:

JSON

{
  "type": "Image",
  "src": "https://example.com/avatar.png",
  "style": { "width": 120, "height": 120 },
  "borderRadius": 60
}

Shape Effects on Images

Images inherit the FlexStyle.effects system. You can apply drop shadows, reflections, and 3D transforms:

JSON

{
  "type": "Image",
  "src": "https://example.com/product.png",
  "style": {
    "position": "absolute",
    "left": 300, "top": 100, "width": 360, "height": 240,
    "effects": {
      "dropShadow": {
        "color": "#000000",
        "offsetX": 4, "offsetY": 4,
        "blurRadius": 12,
        "opacity": 0.3
      },
      "reflection": {
        "blurRadius": 2,
        "startOpacity": 0.4,
        "endOpacity": 0,
        "distance": 4,
        "size": 40
      }
    }
  }
}

Image Fills

Beyond PaperImage nodes, images can fill any shape via the fill property on FlexStyle:

JSON

{
  "type": "View",
  "style": {
    "position": "absolute",
    "left": 60, "top": 100, "width": 300, "height": 200,
    "fill": {
      "type": "image",
      "src": "https://example.com/texture.jpg",
      "stretch": true
    }
  },
  "shapeType": "roundRect"
}

Set tile: true for tiled/repeating image fills instead of stretch.

Video Embedding

The PaperVideo node embeds video files in the presentation:

JSON

{
  "type": "Video",
  "style": { "position": "absolute", "left": 60, "top": 100, "width": 640, "height": 360 },
  "src": "https://example.com/demo.mp4",
  "poster": "https://example.com/demo-poster.png",
  "mimeType": "video/mp4",
  "playback": {
    "autoPlay": false,
    "loop": false,
    "showControls": true,
    "volume": 80
  }
}

Audio Embedding

The PaperAudio node embeds audio files:

JSON

{
  "type": "Audio",
  "style": { "position": "absolute", "left": 60, "top": 400, "width": 200, "height": 40 },
  "src": "https://example.com/narration.mp3",
  "mimeType": "audio/mp3",
  "playback": {
    "autoPlay": true,
    "loop": false,
    "showControls": true
  }
}

Accessibility

All image, video, and audio nodes accept altText and decorative properties:

JSON

{
  "type": "Image",
  "src": "https://example.com/chart.png",
  "altText": "Revenue trend chart showing 23% year-over-year growth",
  "decorative": false
}

Set decorative: true for purely visual elements (borders, backgrounds) so screen readers skip them.

When using HTTPS URLs, the engine fetches images during rendering. If a URL is unreachable, the render fails with a `MEDIA_FETCH_FAILED` error. For reliable builds, prefer base64 data URLs or verify URL accessibility before submitting.

Best Practices

Use PNG for logos and graphics with transparency; JPEG for photographs
Keep individual images under 10 MB to avoid memory pressure during archiving
Prefer svgSrc for vector logos -- they scale cleanly at any slide size
Set explicit width and height on every image node; the engine does not intrinsic-size images
Use imageEffects instead of pre-processing images when you need PowerPoint-native editability