Skip to main content

Positioning

Positioning controls where assets appear in your video. Because source assets vary in size and aspect ratio, Shotstack provides multiple properties that work together to give you precise control over placement and sizing.

Common positioning patterns​

Before diving into how each property works, here are solutions to common positioning needs:

Consistent sizing for variable images​

When using images of different sizes or aspect ratios (common in templates with user-provided content), set fixed dimensions with the appropriate fit mode to ensure consistent layout:

{
  "asset": {
    "type": "image",
    "src": "https://shotstack-assets.s3.amazonaws.com/images/woods1.jpg"
  },
  "start": 0,
  "length": 5,
  "width": 400,
  "height": 400,
  "fit": "contain"
}

Three images of different aspect ratios (portrait, square, landscape) all sized to 400x400 with fit contain, showing letterboxing

By setting fixed width and height values, every image—regardless of its original dimensions—will occupy exactly 800x450 pixels in your video. This is critical when working with user-provided content where source image sizes vary unpredictably.

The fit property determines how the source image fills this fixed area:

  • fit: "contain" (shown above) - Scales the image proportionally to fit entirely within the 800x450 area. Maintains aspect ratio but may add letterboxing. Best when you must show the complete image.
  • fit: "crop" - Fills the 800x450 area by cropping the source image. Centers the crop region.
  • fit: "cover" - Scales the image to completely fill the 800x450 area. Does not aintain aspect ratio and may distort the image.

Logo in corner​

Places a logo in the top-right corner with margin:

{
  "asset": {
      "type": "image",
      "src": "https://shotstack-assets.s3.amazonaws.com/logos/shotstack/small/logo-mono-white.png"
  },
  "start": 0,
  "length": 5,
  "fit": "crop", // Default setting. Can be ommitted.
  "scale": 0.07,
  "position": "topRight",
  "offset": {
      "x": -0.05,
      "y": -0.05
  }
}

Shotstack logo positioned in top-right corner with offset margin

The offset property adds spacing from the corner anchor point, while the fit properties value of crop crops the image to the size of the viewport. The scale property resizes the clip to 7% of the viewport size.

Full-bleed background​

Fills the entire canvas with an image, cropping edges if needed:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/woods1.jpg"
    },
    "start": 0,
    "length": 5,
    "fit": "crop", // Default setting. Can be omitted.
    "position": "center" // Default setting. Can be omitted.
}

Forest image filling entire canvas using fit crop, centered position

The "fit": "crop" property scales the image to fill the clip area while maintaining aspect ratio.

The coordinate system​

Shotstack uses normalized coordinates that work regardless of your output resolution. The viewport center is (0, 0), edges extend from -1 to 1 in both directions.

This means the same positioning values work identically for 720p, 1080p, or 4K videos—no need to recalculate for different resolutions.

Coordinate system diagram showing viewport with center at (0,0) and edges from -1 to 1 in both directions

Position property​

The position property anchors your asset to one of nine points on the viewport:

  • center (default)
  • top, bottom, left, right
  • topLeft, topRight, bottomLeft, bottomRight
{
  "asset": {
    "type": "image",
    "src": "https://shotstack-assets.s3.amazonaws.com/logos/shotstack/small/logo-mono-white.png"
  },
  "start": 0,
  "length": 5,
  "fit": "none",
  "position": "topLeft"
}

Shotstack logo positioned at top-left corner using position property with fit none

Use position when you want to align content to standard locations like corners or edges.

info

Make sure you are using the correct fit property. The default "fit": "crop" will scale the asset to the viewport, allowing you to control how the asset is cropped.

Offset property​

The offset property fine-tunes placement from the position anchor point, relative to the total width and height of the viewport. Values range from -1 to 1:

  • x: Negative moves left, positive moves right
  • y: Negative moves down, positive moves up
{
  "asset": {
      "type": "image",
      "src": "https://shotstack-assets.s3.amazonaws.com/logos/shotstack/small/logo-mono-white.png"
  },
  "start": 0,
  "length": 5,
  "fit": "none",
  "position": "topLeft",
  "offset":{
      "x": 0.05,
      "y": -0.05
  }
}

Shotstack logo positioned at top-left with offset creating 5% margin from edges

This example positions the asset at bottomLeft, then moves it right by 10% of width of the viewport, and up by 10% of the height of the viewport, creating margin from the edges.

info

Offset values use a relative -1 to 1 range, based on the width and height selected in the output. Values > 1 will move the image offscreen.

Fit property​

The fit property controls how assets scale to fit the clip:

Crop​

Scales the asset to fill the clip bounds while maintaining aspect ratio. This may crop the asset if aspect ratio doesn't match the viewport size:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/mountain-mist-lrg.jpg"
    },
    "start": 0,
    "length": 5,
    "fit": "crop"
}

Mountain landscape image with fit crop, filling canvas while maintaining aspect ratio

Cover​

Scales the asset to fill the clip area. This does not maintain the aspect ratio and may distort the asset if the viewport aspect ratio doesn't match:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/mountain-mist-lrg.jpg"
    },
    "start": 0,
    "length": 5,
    "fit": "cover"
}

Mountain landscape image with fit cover, stretched to fill canvas without maintaining aspect ratio

Contain​

Scales the asset to fit within the clip bounds while maintaining aspect ratio, but may add letterboxing if aspect ratios don't match:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/mountain-mist-lrg.jpg"
    },
    "start": 0,
    "length": 5,
    "fit": "contain"
}

Mountain landscape image with fit contain, showing letterboxing to preserve aspect ratio

None​

No scaling applied. Asset uses its original dimensions:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/mountain-mist-lrg.jpg"
    },
    "start": 0,
    "length": 5,
    "fit": "none"
}

Mountain landscape image with fit none, showing original dimensions without scaling

Use when you want exact control over sizing, typically combined with scale.

info

If no fit property is specified, the default behavior is crop, which will crop assets to fill the frame.

Width & Height​

Clips are set to the width and height of the viewport by default, unless you explicitly set its dimensions.

info

The width and height properties are not currently available in Shotstack Studio. These properties are only available when using the Shotstack API directly.

Implicit dimensions​

When width and height are not explicitly set the clip will assume the dimensions of the viewport as set in the output property.

Explicit dimensions​

You can set the exact pixel dimensions for a clip. This is helpful if you want to make sure your assets are contained within a fixed boundary:

{
  "asset": {
    "type": "video",
    "src": "https://shotstack-assets.s3.amazonaws.com/footage/city.mp4"
  },
  "start": 0,
  "length": 5,
  "width": 480,
  "height": 270,
  "position": "bottomRight",
  "offset": {
    "x": -0.1,
    "y": -0.1
  }
}

Picture-in-picture effect with smaller video overlay positioned in bottom-right corner using fixed dimensions

This creates a picture-in-picture effect with a fixed-size video overlay.

info

Fixed size clips are particularly useful if you are using UGC or other assets from which you cannot guarantee the size and/or aspect ratio.

Scale​

The scale property resizes assets proportionally. A value of 1 is normal size, 0.5 is half size, 2 is double size:

{
    "asset": {
        "type": "image",
        "src": "https://shotstack-assets.s3.amazonaws.com/images/woods1.jpg"
    },
    "start": 0,
    "length": 5,
    "scale": 0.2
}

Forest image scaled down to 20% of viewport size using scale property

Use scale when you want proportional resizing. Use width and height when you need exact dimensions.

info

The scale property is applied to the clip after fit scaling is applied to the asset.

How properties work together​

Properties are applied in this order:

  1. Width/Height - Sets explicit dimensions of the clip
  2. Fit - Scales asset to the clip
  3. Position - Anchors to grid point
  4. Offset - Fine-tunes from anchor relative to viewport
  5. Scale - Final size multiplier

Example using multiple properties:

{
  "asset": {
    "type": "image",
    "src": "https://shotstack-assets.s3.amazonaws.com/images/woods1.jpg"
  },
  "start": 0,
  "length": 5,
  "fit": "contain",
  "position": "topLeft",
  "width": 500,
  "height": 500,
  "offset": {
    "x": 0.1,
    "y": -0.1
  },
  "scale": 0.8
}

Forest image in 500x500 clip with fit contain, positioned top-left with offset and scaled to 80%

This example:

  1. The clip container is explicitly set to 500px by 500px.
  2. The asset is resized to fit within the 500px by 500px container without cropping the image, potentially with letterboxing.
  3. Anchors the clip to the top-left corner of the viewport (topLeft)
  4. Adds 10% margins margings (relative to the width and height of the viewport) from the corner
  5. Scales the clip down by 80% to 400px by 400px.
  • Animations - Animate position and offset over time