Overlays

Overlays are visual elements layered on top of your image animations. They can add depth, effects, branding, and visual interest without modifying the underlying images. Liveposter supports four types of overlays: gridlines, images, videos, and scanlines.

Overview

Overlays are configured in the overlays array of your poster specification:

{
  "container": "#slideshow",
  "mode": "diaporama",
  "images": [ /* your images */ ],
  "overlays": [
    {
      "type": "gridline",
      /* overlay-specific config */
    }
  ]
}

Overlay Type	Best For	Animated
Gridline	Composition guides, rule of thirds	No
Image	Logos, watermarks, static graphics	No
Video	Motion graphics, atmospheric effects	Yes
Scanline	CRT/retro effects, screen simulation	Yes

Gridline Overlay

Creates SVG grid lines over the animation, perfect for composition guides or aesthetic effects.

What It Is

Gridline overlays draw horizontal and vertical lines dividing the container into rows and columns. Commonly used for rule of thirds composition guides or geometric design elements.

Configuration

{
  "type": "gridline",
  "rows": 3,
  "columns": 3,
  "color": "rgba(255, 255, 255, 0.3)",
  "lineWidth": 1,
  "opacity": 1,
  "zIndex": 10
}

Parameters

rows (number): Number of horizontal divisions (default: 3)
columns (number): Number of vertical divisions (default: 3)
color (string): Line color in CSS format (default: "rgba(255, 255, 255, 0.3)")
lineWidth (number): Line thickness in pixels (default: 1)
opacity (number): Overall overlay opacity 0-1 (default: 1)
zIndex (number): Stacking order (default: 10)

Example: Rule of Thirds

{
  "container": "#slideshow",
  "mode": "diaporama",
  "overlays": [
    {
      "type": "gridline",
      "rows": 3,
      "columns": 3,
      "color": "rgba(255, 255, 255, 0.2)",
      "lineWidth": 2
    }
  ],
  "images": [
    { "src": "landscape1.jpg", "alt": "Landscape" }
  ]
}

Example: Golden Ratio Grid

{
  "type": "gridline",
  "rows": 5,
  "columns": 8,
  "color": "rgba(255, 215, 0, 0.15)",
  "lineWidth": 1
}

Tips

Use low opacity (0.1-0.3) for subtle composition guides
Higher opacity (0.5-0.8) for intentional graphic elements
White or gold colors work well on dark images
Keep lineWidth at 1-2px for clean, crisp lines

Image Overlay

Static images layered on top of animations, ideal for logos, watermarks, and graphic elements.

What It Is

Image overlays display a static image (PNG, JPG, SVG) over your animation. Supports positioning, blend modes, and transparency for flexible compositing.

Configuration

{
  "type": "image",
  "src": "logo.png",
  "opacity": 0.8,
  "blendMode": "normal",
  "zIndex": 15,
  "objectFit": "contain",
  "position": "top-right",
  "width": "200px",
  "height": "200px"
}

Parameters

src (string): Image URL or path (required)
opacity (number): Opacity 0-1 (default: 1)
blendMode (string): CSS blend mode (default: "normal")
- Options: normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion
zIndex (number): Stacking order (default: 10)
objectFit (string): How image fits container (default: "cover")
- Options: cover, contain, fill, none, scale-down
position (string): Preset position (default: "center")
- Options: center, top-left, top-right, bottom-left, bottom-right, custom
width (string): Width in CSS units (default: "100%")
height (string): Height in CSS units (default: "100%")

For position: "custom", you can also specify:

top (string): Top offset (e.g., "20px")
left (string): Left offset
right (string): Right offset
bottom (string): Bottom offset

Example: Logo Watermark

{
  "type": "image",
  "src": "company-logo.png",
  "opacity": 0.7,
  "position": "bottom-right",
  "width": "150px",
  "height": "auto",
  "zIndex": 15
}

Example: Full-Screen Texture

{
  "type": "image",
  "src": "paper-texture.png",
  "opacity": 0.3,
  "blendMode": "multiply",
  "position": "center",
  "width": "100%",
  "height": "100%",
  "objectFit": "cover"
}

Example: Custom Positioning

{
  "type": "image",
  "src": "badge.png",
  "position": "custom",
  "top": "50px",
  "right": "50px",
  "width": "100px",
  "height": "100px"
}

Blend Modes

Experiment with blend modes for creative effects:

multiply: Darkens, good for shadows/textures
screen: Lightens, good for glows/light leaks
overlay: Increases contrast
soft-light: Subtle lighting effect
color-dodge: Strong brightness/glow effect

Tips

Use PNG images with transparency for logos
objectFit: "contain" preserves aspect ratio
Lower zIndex appears below, higher appears above
Blend modes can create striking visual effects
Test opacity and blend mode combinations

Video Overlay

Looping video overlays for motion graphics and atmospheric effects.

What It Is

Video overlays play looping video files over your animations. Perfect for subtle motion, particle effects, light leaks, or atmospheric elements.

Configuration

{
  "type": "video",
  "src": "particles.mp4",
  "loop": true,
  "muted": true,
  "autoplay": true,
  "opacity": 0.5,
  "blendMode": "screen",
  "zIndex": 10,
  "objectFit": "cover"
}

Parameters

src (string | array): Video URL/path or array of sources (required)
loop (boolean): Loop video continuously (default: true)
muted (boolean): Mute audio (default: true)
autoplay (boolean): Auto-start playback (default: true)
opacity (number): Opacity 0-1 (default: 0.5)
blendMode (string): CSS blend mode (default: "normal")
zIndex (number): Stacking order (default: 10)
objectFit (string): How video fits container (default: "cover")

Example: Light Leak Effect

{
  "type": "video",
  "src": "light-leak.mp4",
  "loop": true,
  "muted": true,
  "autoplay": true,
  "opacity": 0.4,
  "blendMode": "screen",
  "objectFit": "cover"
}

Example: Multiple Video Sources

{
  "type": "video",
  "src": [
    { "src": "particles.webm", "type": "video/webm" },
    { "src": "particles.mp4", "type": "video/mp4" }
  ],
  "loop": true,
  "opacity": 0.6
}

Example: Atmospheric Smoke

{
  "type": "video",
  "src": "smoke.mp4",
  "loop": true,
  "muted": true,
  "opacity": 0.3,
  "blendMode": "multiply",
  "objectFit": "cover"
}

Video Format Recommendations

WebM: Best compression, good browser support
MP4 (H.264): Universal compatibility
File size: Keep under 5MB for smooth performance
Resolution: Match or exceed container size
Frame rate: 24-30fps is sufficient for overlays
Length: 5-15 seconds loops seamlessly

Tips

Always set muted: true for autoplay to work
Use blendMode: "screen" for light/glow effects
Use blendMode: "multiply" for smoke/shadow effects
Keep videos short and optimized
Provide multiple formats for browser compatibility
Test on target devices for performance

Scanline Overlay

Animated CRT-style scanlines with flicker and glow effects.

What It Is

Scanline overlays create an animated retro CRT monitor effect with moving scanlines, flicker, and optional screen glow. Perfect for cyberpunk aesthetics, retro gaming themes, or screen simulation.

Configuration

{
  "type": "scanline",
  "lineHeight": 2,
  "lineSpacing": 4,
  "color": "rgba(0, 255, 100, 0.15)",
  "animationSpeed": 1,
  "flickerIntensity": 0.05,
  "glowEnabled": true,
  "glowColor": "rgba(0, 255, 100, 0.2)",
  "opacity": 1,
  "blendMode": "screen",
  "zIndex": 10
}

Parameters

Scanline Appearance:

lineHeight (number): Height of each scanline in pixels (default: 2)
lineSpacing (number): Space between scanlines in pixels (default: 4)
color (string): Scanline color (default: "rgba(0, 255, 100, 0.15)" - green CRT)
alternateColor (string | null): Optional color for alternating lines (default: null)

Animation:

animationSpeed (number): Speed of scanline movement (default: 1)
flickerIntensity (number): Flicker strength 0-1 (default: 0.05)
flickerSpeed (number): Flicker frequency multiplier (default: 4)
noiseAmount (number): Random noise 0-1 (default: 0.03)

Glow Effect:

glowEnabled (boolean): Enable screen glow effect (default: true)
glowColor (string): Glow color (default: "rgba(0, 255, 100, 0.2)")
glowCycleSpeed (number): Glow pulsing speed (default: 0.5)
glowIntensity (number): Glow strength 0-1 (default: 0.3)

General:

opacity (number): Overall opacity 0-1 (default: 1)
blendMode (string): CSS blend mode (default: "screen")
zIndex (number): Stacking order (default: 10)

Example: Classic Green CRT

{
  "type": "scanline",
  "lineHeight": 2,
  "lineSpacing": 4,
  "color": "rgba(0, 255, 100, 0.15)",
  "flickerIntensity": 0.08,
  "glowEnabled": true,
  "glowColor": "rgba(0, 255, 100, 0.2)"
}

Example: Amber Monitor

{
  "type": "scanline",
  "lineHeight": 3,
  "lineSpacing": 5,
  "color": "rgba(255, 176, 0, 0.2)",
  "flickerIntensity": 0.1,
  "glowEnabled": true,
  "glowColor": "rgba(255, 176, 0, 0.25)",
  "blendMode": "screen"
}

Example: Blue Terminal

{
  "type": "scanline",
  "lineHeight": 2,
  "lineSpacing": 3,
  "color": "rgba(0, 170, 255, 0.18)",
  "alternateColor": "rgba(0, 140, 220, 0.12)",
  "flickerIntensity": 0.06,
  "glowEnabled": true,
  "glowColor": "rgba(0, 170, 255, 0.15)"
}

Example: Subtle Modern Scanline

{
  "type": "scanline",
  "lineHeight": 1,
  "lineSpacing": 6,
  "color": "rgba(255, 255, 255, 0.05)",
  "flickerIntensity": 0.02,
  "glowEnabled": false,
  "blendMode": "overlay"
}

Color Themes

Green CRT (classic):

"color": "rgba(0, 255, 100, 0.15)"

Amber monitor:

"color": "rgba(255, 176, 0, 0.2)"

Blue terminal:

"color": "rgba(0, 170, 255, 0.18)"

Monochrome:

"color": "rgba(255, 255, 255, 0.12)"

Tips

Higher lineSpacing creates more visible scanlines
Lower flickerIntensity (0.02-0.05) is more subtle
blendMode: "screen" works best for colored scanlines
blendMode: "overlay" for subtle monochrome effects
Disable glowEnabled for cleaner, less retro look
Use alternateColor for interlaced CRT effect
Experiment with color to match your theme

Combining Multiple Overlays

You can layer multiple overlays for complex effects:

{
  "container": "#slideshow",
  "mode": "diaporama",
  "overlays": [
    {
      "type": "video",
      "src": "light-leak.mp4",
      "opacity": 0.3,
      "blendMode": "screen",
      "zIndex": 10
    },
    {
      "type": "scanline",
      "color": "rgba(0, 255, 100, 0.1)",
      "flickerIntensity": 0.05,
      "zIndex": 11
    },
    {
      "type": "image",
      "src": "logo.png",
      "position": "bottom-right",
      "width": "150px",
      "height": "auto",
      "zIndex": 15
    },
    {
      "type": "gridline",
      "rows": 3,
      "columns": 3,
      "color": "rgba(255, 255, 255, 0.1)",
      "zIndex": 12
    }
  ],
  "images": [ /* your images */ ]
}

Layering Strategy

Background effects (zIndex: 10): Textures, subtle videos
Mid-layer effects (zIndex: 11-14): Scanlines, gridlines
Foreground elements (zIndex: 15+): Logos, important graphics

Performance Considerations

Video overlays: Most resource-intensive; keep files small
Scanline overlays: Canvas-based animation; generally performant
Image overlays: Very lightweight
Gridline overlays: Very lightweight (SVG-based)

Best practices:

Limit video overlays to 1-2 per animation
Keep video files under 5MB
Use appropriate blend modes (some are GPU-accelerated)
Test on target hardware (especially for digital signage)
Lower framerates for scanline effects reduce CPU usage

Next Steps

Learn about Effects for transition effects
Explore Animation Modes
Check the Poster Spec Format for complete schema
See the API Reference for programmatic control