Poster Spec Reference

The poster spec is a JSON configuration file that defines how a Liveposter animation behaves. It controls everything from animation mode and timing to effects, overlays, and input handling.

Schema Overview

A poster spec JSON file has the following top-level structure:

{
  "container": "#element-id",
  "title": "Display title",
  "description": "Description of this poster",
  "mode": "diaporama",
  "loop": true,
  "timing": { ... },
  "effects": { ... },
  "overlays": [ ... ],
  "images": [ ... ],
  "input": { ... }
}

Core Properties

container

Type: string (CSS selector) Required: Yes

The CSS selector for the DOM element that will contain the poster. Must be a valid selector.

{
  "container": "#my-slideshow"
}

title

Type: string Required: No

Display title for the poster. Used for metadata and debugging.

{
  "title": "My Beautiful Slideshow"
}

description

Type: string Required: No

Longer description of the poster’s content or behavior.

{
  "description": "A cinematic slideshow with Ken Burns effects"
}

mode

Type: string Required: Yes

Defines the primary animation mode. Available modes:

"diaporama" - Classic slideshow with timed transitions
"pan-slideshow" - Slideshow with panning effects
"zoom-slideshow" - Slideshow with zoom/scale effects (Ken Burns)
"lenticular" - Mouse-driven multi-image viewer
"parallax-layers" - Mouse-driven parallax depth effects

{
  "mode": "diaporama"
}

loop

Type: boolean Required: No Default: false

Whether the animation should loop continuously. Set to true for continuous playback, false for single play-through.

{
  "loop": true
}

Timing Configuration

The timing object controls animation duration and transition timing.

Global Timing

{
  "timing": {
    "duration": 3000,
    "transition": 500
  }
}

Properties:

duration (number): How long each image displays in milliseconds
transition (number): Length of the transition effect in milliseconds
- 0 = instant hard cut
- > 0 = smooth transition over specified time

Per-Image Timing Override

Individual images can override the global timing:

{
  "images": [
    {
      "src": "image1.jpg",
      "timing": {
        "duration": 5000,
        "transition": 800
      }
    }
  ]
}

Effects Configuration

The effects object defines animation effects. Can be set globally or per-image.

Global Effects

{
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  }
}

Effect Types

fade

Crossfade transition between images.

{
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  }
}

Properties:

easing: Timing function (see Easing Functions)

cut

Instant transition with no animation (hard cut).

{
  "effects": {
    "type": "cut"
  }
}

pan

Horizontal or vertical panning motion.

{
  "effects": {
    "type": "pan",
    "direction": "right",
    "easing": "linear",
    "distance": "100%"
  }
}

Properties:

direction: "left" | "right" | "up" | "down"
easing: Timing function
distance: CSS distance value (e.g., "100%", "500px")

zoom

Scale/zoom effect (Ken Burns style).

{
  "effects": {
    "type": "zoom",
    "scale": 1.3,
    "origin": "center",
    "easing": "ease-in-out"
  }
}

Properties:

scale (number): Target scale factor (e.g., 1.3 = 130%)
origin: Transform origin point
- "center", "top-left", "top-right", "bottom-left", "bottom-right"
- Or CSS values like "50% 50%"
easing: Timing function

parallax

Parallax motion effect (used with parallax-layers mode).

{
  "effects": {
    "type": "parallax",
    "easing": "ease-out"
  }
}

Per-image properties:

{
  "images": [
    {
      "src": "background.jpg",
      "layer": 0,
      "effects": {
        "intensity": 10,
        "axis": "x"
      }
    }
  ]
}

Properties:

intensity (number): Movement intensity (higher = more movement)
axis: "x" | "y" | "both"

Per-Image Effects Override

{
  "images": [
    {
      "src": "image1.jpg",
      "effects": {
        "type": "zoom",
        "scale": 1.5,
        "origin": "top-left",
        "easing": "ease-out"
      }
    }
  ]
}

Easing Functions

Standard CSS timing functions are supported:

"linear" - Constant speed
"ease" - Default, starts slow, speeds up, ends slow
"ease-in" - Starts slow, accelerates
"ease-out" - Starts fast, decelerates
"ease-in-out" - Slow start and end, faster middle
Custom cubic-bezier: "cubic-bezier(0.4, 0, 0.2, 1)"

Images Array

The images array defines the image sequence. Each image is an object with source and optional overrides.

Basic Image

{
  "images": [
    {
      "src": "https://example.com/image.jpg",
      "alt": "Description"
    }
  ]
}

Properties:

src (string, required): Image URL or path
alt (string): Alternative text for accessibility

Image with Overrides

{
  "images": [
    {
      "src": "image.jpg",
      "alt": "Custom timing and effects",
      "timing": {
        "duration": 5000,
        "transition": 800
      },
      "effects": {
        "type": "zoom",
        "scale": 1.5,
        "origin": "center",
        "easing": "ease-in-out"
      }
    }
  ]
}

Parallax Layer Image

For parallax-layers mode:

{
  "images": [
    {
      "src": "background.jpg",
      "alt": "Background layer",
      "layer": 0,
      "effects": {
        "intensity": 10,
        "axis": "x"
      }
    }
  ]
}

Properties:

layer (number): Layer depth (0 = background, higher = foreground)
effects.intensity: Parallax intensity
effects.axis: Movement axis

Viewport Configuration

For pan effects on wide images:

{
  "images": [
    {
      "src": "wide-panorama.jpg",
      "viewport": {
        "width": "1080px",
        "height": "1920px",
        "overflow": "hidden"
      },
      "effects": {
        "type": "pan",
        "direction": "right",
        "distance": "100%"
      }
    }
  ]
}

Overlays

Overlays are visual elements layered on top of images. Multiple overlays can be stacked.

{
  "overlays": [
    {
      "type": "gridline",
      "zIndex": 10,
      "opacity": 0.6
    }
  ]
}

Overlay Types

gridline

Compositional grid overlay.

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

Properties:

rows (number): Number of horizontal divisions
columns (number): Number of vertical divisions
color (string): CSS color value
lineWidth (number): Line thickness in pixels
opacity (number): 0.0 to 1.0
zIndex (number): Stacking order

scanline

Retro CRT/VHS scanline effect.

{
  "type": "scanline",
  "lineHeight": 2,
  "lineSpacing": 4,
  "color": "rgba(0, 0, 0, 0.3)",
  "animationSpeed": 0.5,
  "flickerIntensity": 0.05,
  "flickerSpeed": 2,
  "glowEnabled": true,
  "glowColor": "rgba(0, 255, 100, 0.15)",
  "glowCycleSpeed": 3,
  "zIndex": 20
}

Properties:

lineHeight (number): Height of each scanline in pixels
lineSpacing (number): Spacing between lines in pixels
color (string): Line color (CSS)
animationSpeed (number): Scroll speed multiplier
flickerIntensity (number): Flicker strength (0-1)
flickerSpeed (number): Flicker rate
glowEnabled (boolean): Enable phosphor glow effect
glowColor (string): Glow color (CSS)
glowCycleSpeed (number): Glow pulse speed
zIndex (number): Stacking order

video

Video overlay with blending.

{
  "type": "video",
  "src": "https://example.com/video.mp4",
  "loop": true,
  "muted": true,
  "autoplay": true,
  "opacity": 0.3,
  "blendMode": "overlay",
  "zIndex": 10
}

Properties:

src (string): Video URL
loop (boolean): Loop playback
muted (boolean): Mute audio
autoplay (boolean): Auto-start playback
opacity (number): 0.0 to 1.0
blendMode (string): CSS blend mode ("overlay", "multiply", "screen", etc.)
zIndex (number): Stacking order

image

Static image overlay.

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

Properties:

src (string): Image URL
opacity (number): 0.0 to 1.0
blendMode (string): CSS blend mode
objectFit (string): CSS object-fit value ("contain", "cover", etc.)
position (string): Positioning preset
- "top-left", "top-center", "top-right"
- "center-left", "center", "center-right"
- "bottom-left", "bottom-center", "bottom-right"
width (string): CSS width
height (string): CSS height
zIndex (number): Stacking order

Input Configuration

The input object defines user interaction modes. Used for interactive modes like lenticular and parallax-layers.

{
  "input": {
    "type": "mouseX",
    "mapping": "linear",
    "bounds": [0, 1]
  }
}

Input Types

"mouseX" - Horizontal mouse position
"mouseY" - Vertical mouse position
"mouseXY" - Both axes
"scroll" - Scroll position

Input Properties

type (string): Input source

mapping (string): How input maps to output

"linear" - Direct 1:1 mapping
"eased" - Smoothed/interpolated mapping

bounds (array): Input range [min, max]

Typically [0, 1] for normalized values

Complete Examples

Example 1: Hard Cut Slideshow

{
  "container": "#slideshow-hardcut",
  "title": "Hard Cut Diaporama",
  "description": "Instant transitions between images",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 2000,
    "transition": 0
  },
  "effects": {
    "type": "fade"
  },
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=1",
      "alt": "Mountain landscape"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=2",
      "alt": "Ocean sunset"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=3",
      "alt": "Forest path"
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo1-hardcut.json

Example 2: Smooth Fade with Grid Overlay

{
  "container": "#slideshow-fade",
  "title": "Fade Slideshow with Grid",
  "description": "Smooth crossfade with compositional grid",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 2000,
    "transition": 500
  },
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  },
  "overlays": [
    {
      "type": "gridline",
      "rows": 3,
      "columns": 3,
      "color": "rgba(255, 255, 255, 0.3)",
      "lineWidth": 2,
      "opacity": 0.6,
      "zIndex": 10
    }
  ],
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=4",
      "alt": "Product view 1",
      "timing": {
        "duration": 5000,
        "transition": 500
      }
    },
    {
      "src": "https://picsum.photos/1080/1920?random=5",
      "alt": "Product view 2"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=6",
      "alt": "Product view 3"
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo2-fade.json

Example 3: Pan Slideshow with Video Overlay

{
  "container": "#slideshow-pan",
  "title": "Pan Reveal + Jump Cut",
  "description": "Continuous pan across wide image, then hard cut",
  "mode": "pan-slideshow",
  "loop": true,
  "overlays": [
    {
      "type": "video",
      "src": "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
      "loop": true,
      "muted": true,
      "autoplay": true,
      "opacity": 0.3,
      "blendMode": "overlay",
      "zIndex": 10
    }
  ],
  "images": [
    {
      "src": "https://picsum.photos/3840/1920?random=13",
      "alt": "Wide panorama",
      "timing": {
        "duration": 3000,
        "transition": 3000
      },
      "effects": {
        "type": "pan",
        "direction": "right",
        "easing": "linear",
        "distance": "100%"
      },
      "viewport": {
        "width": "1080px",
        "height": "1920px",
        "overflow": "hidden"
      }
    },
    {
      "src": "https://picsum.photos/1080/1920?random=14",
      "alt": "Final slide",
      "timing": {
        "duration": 2000,
        "transition": 0
      },
      "effects": {
        "type": "cut"
      }
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo3-pan.json

Example 4: Lenticular (Mouse-Driven)

{
  "container": "#lenticular-demo",
  "title": "Lenticular Effect",
  "description": "Mouse-driven multi-view display",
  "mode": "lenticular",
  "loop": false,
  "input": {
    "type": "mouseX",
    "mapping": "linear",
    "bounds": [0, 1]
  },
  "timing": {
    "transition": 50
  },
  "effects": {
    "type": "fade",
    "easing": "ease-out"
  },
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=15",
      "alt": "View angle 1"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=16",
      "alt": "View angle 2"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=17",
      "alt": "View angle 3"
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo4-lenticular.json

Example 5: Parallax Layers

{
  "container": "#parallax-demo",
  "title": "Parallax Layers",
  "description": "Three-layer depth effect with mouse control",
  "mode": "parallax-layers",
  "loop": false,
  "input": {
    "type": "mouseX",
    "mapping": "eased"
  },
  "effects": {
    "type": "parallax",
    "easing": "ease-out"
  },
  "overlays": [
    {
      "type": "image",
      "src": "https://picsum.photos/400/400?random=100",
      "opacity": 0.8,
      "blendMode": "multiply",
      "objectFit": "contain",
      "position": "top-right",
      "width": "200px",
      "height": "200px",
      "zIndex": 15
    }
  ],
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=20",
      "alt": "Background",
      "layer": 0,
      "effects": {
        "intensity": 10,
        "axis": "x"
      }
    },
    {
      "src": "https://picsum.photos/1080/1920?random=21",
      "alt": "Midground",
      "layer": 1,
      "effects": {
        "intensity": 30,
        "axis": "x"
      }
    },
    {
      "src": "https://picsum.photos/1080/1920?random=22",
      "alt": "Foreground",
      "layer": 2,
      "effects": {
        "intensity": 60,
        "axis": "x"
      }
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo5-parallax.json

Example 6: Zoom Slideshow (Ken Burns)

{
  "container": "#slideshow-zoom",
  "title": "Ken Burns Effect",
  "description": "Slow zoom creating cinematic effect",
  "mode": "zoom-slideshow",
  "loop": true,
  "timing": {
    "duration": 3000,
    "transition": 2000
  },
  "effects": {
    "type": "zoom",
    "scale": 1.3,
    "origin": "center",
    "easing": "ease-in-out"
  },
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=30",
      "alt": "Landscape zoom"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=31",
      "alt": "Portrait zoom",
      "effects": {
        "type": "zoom",
        "scale": 1.5,
        "origin": "top-left",
        "easing": "ease-out"
      }
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo6-zoom.json

Example 7: Retro Scanline Effect

{
  "container": "#slideshow-scanline",
  "title": "Retro CRT Effect",
  "description": "VHS/retro aesthetic with animated scanlines",
  "mode": "diaporama",
  "loop": true,
  "timing": {
    "duration": 2500,
    "transition": 800
  },
  "effects": {
    "type": "fade",
    "easing": "ease-in-out"
  },
  "overlays": [
    {
      "type": "scanline",
      "lineHeight": 2,
      "lineSpacing": 4,
      "color": "rgba(0, 0, 0, 0.3)",
      "animationSpeed": 0.5,
      "flickerIntensity": 0.05,
      "flickerSpeed": 2,
      "glowEnabled": true,
      "glowColor": "rgba(0, 255, 100, 0.15)",
      "glowCycleSpeed": 3,
      "zIndex": 20
    }
  ],
  "images": [
    {
      "src": "https://picsum.photos/1080/1920?random=40",
      "alt": "Retro scene 1"
    },
    {
      "src": "https://picsum.photos/1080/1920?random=41",
      "alt": "Retro scene 2"
    }
  ]
}

Reference: /packages/demo-server/public/specs/demo7-scanline.json

Best Practices

Performance

Keep transition times reasonable (200-1000ms typically)
Optimize image sizes for target display resolution
Limit the number of overlays (3-4 max recommended)
Use video overlays sparingly (they’re performance-intensive)

Timing

Hard cuts: transition: 0
Quick fade: transition: 200-400
Standard fade: transition: 500-800
Slow cinematic: transition: 1000-2000
Pan/zoom duration should match or exceed transition time

Effects

Match easing to content mood:
- linear for mechanical/technical content
- ease-in-out for natural, organic motion
- ease-in for acceleration effects
- ease-out for deceleration effects

Per-Image Overrides

Use per-image overrides to:

Extend duration for important slides
Apply different effects to specific images
Create rhythm variation in the sequence
Implement custom timing for specific content

Accessibility

Always provide alt text for images
Avoid rapid transitions that might trigger motion sensitivity
Consider providing user controls for pause/play
Test with reduced motion preferences

Additional Examples

All example specs can be found in /packages/demo-server/public/specs/:

demo1-hardcut.json - Basic hard cut slideshow
demo2-fade.json - Fade with grid overlay and per-image timing
demo2b-fade-ease-in.json - Fade with ease-in timing
demo2c-fade-ease-out.json - Fade with ease-out timing
demo3-pan.json - Pan reveal with video overlay
demo4-lenticular.json - Mouse-driven lenticular effect
demo5-parallax.json - Parallax layers with image overlays
demo6-zoom.json - Ken Burns zoom effect
demo7-scanline.json - Retro CRT scanline effect