Poster List Reference

Poster List Reference

The poster list is a JSON file that defines a collection of posters to be displayed together. It supports two formats: a simple array format for basic use cases, and an advanced object format with build configuration for generating gallery pages.

Format Types

Simple Array Format

The simplest format is a JSON array of poster spec file paths:

[
  "specs/demo1-hardcut.json",
  "specs/demo2-fade.json",
  "specs/demo3-pan.json"
]

This format is ideal for:

• Quick prototyping
• Simple poster collections
• Runtime-only configurations

Advanced Object Format

The advanced format includes build configuration and detailed poster metadata:

{
  "buildConfig": {
    "template": "minimal",
    "title": "My Gallery",
    "description": "Collection description"
  },
  "posters": [
    {
      "id": "poster-1",
      "configPath": "specs/demo1.json",
      "name": "Poster Name",
      "description": "Poster description",
      "enabled": true
    }
  ]
}

This format enables:

• Build-time static gallery generation
• Template-based layouts
• Per-poster metadata and controls
• Enable/disable toggles

Custom Format (Array with Metadata)

A hybrid format that adds metadata to the simple array:

[
  {
    "spec": "specs/demo1-hardcut.json",
    "title": "Hard Cut Animation",
    "description": "Instant transitions - no fading"
  },
  {
    "spec": "specs/demo2-fade.json",
    "title": "Smooth Fade Transitions",
    "description": "Beautiful crossfade effects"
  }
]

Simple Array Format

Structure

[
  "path/to/poster1.json",
  "path/to/poster2.json",
  "path/to/poster3.json"
]

Example

[
  "specs/demo1-hardcut.json",
  "specs/demo2-fade.json",
  "specs/demo2b-fade-ease-in.json",
  "specs/demo2c-fade-ease-out.json",
  "specs/demo3-pan.json",
  "specs/demo4-lenticular.json",
  "specs/demo5-parallax.json",
  "specs/demo6-zoom.json",
  "specs/demo7-scanline.json"
]

Reference: /packages/demo-server/public/example-poster-list.json

Path Resolution

Paths are resolved relative to the poster list file location.

Example directory structure:

public/
├── poster-list.json
└── specs/
    ├── demo1.json
    └── demo2.json

In poster-list.json:

[
  "specs/demo1.json",
  "specs/demo2.json"
]

Use Cases

• Development and testing
• Simple deployments
• Dynamic poster loading
• Minimal configuration needs

Advanced Object Format

Full Structure

{
  "buildConfig": {
    "template": "minimal" | "sequential",
    "title": "string",
    "description": "string",
    "favicon": "path/to/favicon.ico",
    "customStyles": "path/to/custom.css"
  },
  "posters": [
    {
      "id": "unique-id",
      "configPath": "path/to/spec.json",
      "name": "Display Name",
      "description": "Poster description",
      "enabled": true
    }
  ]
}

buildConfig Object

Configuration for build-time static page generation.

template

Type: "minimal" | "sequential" Required: Yes

Defines the layout template:

• "minimal" - Grid-based gallery layout with all posters visible
• "sequential" - Single-poster view with navigation controls

{
  "buildConfig": {
    "template": "minimal"
  }
}

title

Type: string Required: No

Page title for the generated gallery.

{
  "buildConfig": {
    "title": "My Liveposter Gallery"
  }
}

description

Type: string Required: No

Page description (used in meta tags).

{
  "buildConfig": {
    "description": "A collection of animated posters showcasing various animation modes"
  }
}

favicon

Type: string (path) Required: No

Path to favicon file, relative to the build output directory.

{
  "buildConfig": {
    "favicon": "assets/favicon.ico"
  }
}

customStyles

Type: string (path) Required: No

Path to custom CSS file for styling the gallery page.

{
  "buildConfig": {
    "customStyles": "assets/custom.css"
  }
}

posters Array

Array of poster objects with metadata and configuration.

Poster Object Properties

id

• Type: string
• Required: Yes
• Description: Unique identifier for the poster (used as DOM element ID)

{
  "id": "poster-hardcut"
}

configPath

• Type: string
• Required: Yes
• Description: Path to the poster spec JSON file

{
  "configPath": "specs/demo1-hardcut.json"
}

name

• Type: string
• Required: No
• Description: Display name for the poster

{
  "name": "Hardcut Slideshow"
}

description

• Type: string
• Required: No
• Description: Longer description of the poster

{
  "description": "Instant transitions between images"
}

enabled

• Type: boolean
• Required: No
• Default: true
• Description: Whether to include this poster in the gallery

{
  "enabled": true
}

Complete Examples

Example 1: Minimal Template Gallery

{
  "buildConfig": {
    "template": "minimal",
    "title": "My Liveposter Gallery",
    "description": "A collection of animated posters showcasing various animation modes",
    "favicon": "assets/favicon.ico",
    "customStyles": "assets/custom.css"
  },
  "posters": [
    {
      "id": "poster-hardcut",
      "configPath": "specs/demo1-hardcut.json",
      "name": "Hardcut Slideshow",
      "description": "Instant transitions between images",
      "enabled": true
    },
    {
      "id": "poster-fade",
      "configPath": "specs/demo2-fade.json",
      "name": "Fade Slideshow",
      "description": "Smooth crossfade transitions",
      "enabled": true
    },
    {
      "id": "poster-pan",
      "configPath": "specs/demo3-pan.json",
      "name": "Pan Slideshow",
      "description": "Cinematic panning effects",
      "enabled": true
    },
    {
      "id": "poster-lenticular",
      "configPath": "specs/demo4-lenticular.json",
      "name": "Lenticular Effect",
      "description": "Mouse-driven parallax animation",
      "enabled": true
    },
    {
      "id": "poster-parallax",
      "configPath": "specs/demo5-parallax.json",
      "name": "Parallax Layers",
      "description": "Scroll-triggered depth effects",
      "enabled": true
    },
    {
      "id": "poster-zoom",
      "configPath": "specs/demo6-zoom.json",
      "name": "Zoom Slideshow",
      "description": "Dynamic zoom animations",
      "enabled": true
    }
  ]
}

Reference: /packages/demo-server/public/example-poster-list-with-build.json

Features:

• Grid layout showing all posters simultaneously
• Custom title and description
• Favicon and custom CSS support
• Per-poster metadata
• Enable/disable control per poster

Example 2: Sequential Template Gallery

{
  "buildConfig": {
    "template": "sequential",
    "title": "Sequential Liveposter Gallery",
    "description": "A sequential presentation of animated posters with smart loading"
  },
  "posters": [
    {
      "id": "poster-1",
      "configPath": "specs/demo1-hardcut.json",
      "name": "Hardcut Transitions",
      "description": "Instant cuts between images with no transition effects"
    },
    {
      "id": "poster-2",
      "configPath": "specs/demo2-fade.json",
      "name": "Smooth Fades",
      "description": "Beautiful crossfade transitions between images"
    },
    {
      "id": "poster-3",
      "configPath": "specs/demo3-pan.json",
      "name": "Cinematic Panning",
      "description": "Ken Burns effect with dynamic panning movements"
    }
  ]
}

Reference: /packages/demo-server/public/example-poster-list-sequential.json

Features:

• One poster visible at a time
• Navigation controls (next/previous)
• Smart loading (preload adjacent posters)
• Full-screen presentation mode
• Progress indicators

Example 3: Custom Array Format

[
  {
    "spec": "specs/demo1-hardcut.json",
    "title": "Hard Cut Animation",
    "description": "Instant transitions - no fading or blending effects"
  },
  {
    "spec": "specs/demo2-fade.json",
    "title": "Smooth Fade Transitions",
    "description": "Beautiful crossfade effect with ease-in-out timing"
  },
  {
    "spec": "specs/demo3-pan.json",
    "title": "Pan Reveal Effect",
    "description": "Cinematic pan across wide images with video overlay"
  }
]

Reference: /packages/demo-server/public/example-poster-list-custom.json

Features:

• Array-based simplicity
• Per-poster metadata
• Custom titles and descriptions
• Easy to extend

Path Resolution

All paths in poster list files are resolved relative to the poster list file’s location.

Relative Paths

Given this structure:

website/
├── gallery.json          (poster list)
├── custom.css
└── posters/
    ├── slideshow1.json
    └── slideshow2.json

In gallery.json:

{
  "buildConfig": {
    "template": "minimal",
    "customStyles": "custom.css"
  },
  "posters": [
    {
      "id": "poster-1",
      "configPath": "posters/slideshow1.json"
    },
    {
      "id": "poster-2",
      "configPath": "posters/slideshow2.json"
    }
  ]
}

Absolute URLs

You can also use absolute URLs for specs hosted elsewhere:

{
  "posters": [
    {
      "id": "remote-poster",
      "configPath": "https://cdn.example.com/posters/spec.json"
    }
  ]
}

Template Options

minimal Template

Grid-based layout ideal for galleries and showcases.

Characteristics:

• All posters load and display simultaneously
• Grid layout (responsive)
• Posters play independently
• Scroll to view all
• Best for: Overview galleries, comparisons, showcases

Use when:

• You want to display multiple animations at once
• Users should see all options immediately
• Interactive exploration is desired
• Gallery or portfolio presentation

Example use case:

Portfolio website showing different animation styles
Demo gallery comparing effects
Marketing page showcasing capabilities

sequential Template

Single-poster view with navigation.

Characteristics:

• One poster visible at a time
• Previous/Next navigation
• Smart preloading (loads adjacent posters)
• Keyboard navigation support
• Progress indicators
• Best for: Presentations, stories, step-by-step guides

Use when:

• Content should be viewed in sequence
• Full focus on one animation at a time
• Story or tutorial format
• Presentation mode

Example use case:

Tutorial walking through different techniques
Story presentation
Conference/demo presentation
Slideshow-style experience

Build Integration

When using the advanced format with buildConfig, the Liveposter build system can generate static HTML pages.

Build Command Example

# Generate gallery from poster list
liveposter build --input gallery.json --output dist/

# Result: static HTML page with embedded posters

Generated Output

The build process creates:

• index.html - Main gallery page
• Embedded poster configurations
• CSS and JavaScript bundles
• Asset references

Build Options

The template choice affects the generated output:

minimal template:

• Generates grid layout
• All posters embedded in page
• Simultaneous playback

sequential template:

• Generates navigation UI
• Lazy loading setup
• Single-poster focus

Best Practices

Organization

Group related posters:

{
  "posters": [
    // Basic effects
    { "id": "fade", "configPath": "basic/fade.json" },
    { "id": "cut", "configPath": "basic/cut.json" },

    // Advanced effects
    { "id": "parallax", "configPath": "advanced/parallax.json" },
    { "id": "zoom", "configPath": "advanced/zoom.json" }
  ]
}

Use consistent naming:

• IDs: poster-effect-variant (e.g., poster-fade-slow)
• Paths: Organize by category in folders
• Names: Clear, descriptive display names

Performance

For minimal template:

• Limit to 6-10 posters per page (performance)
• Use enabled: false to temporarily disable posters
• Optimize images in all poster specs

For sequential template:

• No hard limit (only 1-2 load at a time)
• Preloading handles performance
• Ideal for large collections

Development Workflow

1. Start with simple array format:

   ["spec1.json", "spec2.json"]

2. Add metadata as needed:

   [
     { "spec": "spec1.json", "title": "Demo 1" }
   ]

3. Move to advanced format for production:

   {
     "buildConfig": { "template": "minimal" },
     "posters": [...]
   }

Template Selection

Choose “minimal” when:

• Gallery or portfolio
• Visual comparison needed
• Multiple animations should play together
• Marketing/showcase page
• Under 10 posters

Choose “sequential” when:

• Tutorial or educational content
• Story-driven presentation
• Many posters (10+)
• Focused experience desired
• Presentation mode needed

Migration Guide

Simple to Advanced

From:

[
  "specs/demo1.json",
  "specs/demo2.json"
]

To:

{
  "buildConfig": {
    "template": "minimal",
    "title": "My Gallery"
  },
  "posters": [
    {
      "id": "poster-1",
      "configPath": "specs/demo1.json",
      "name": "Demo 1"
    },
    {
      "id": "poster-2",
      "configPath": "specs/demo2.json",
      "name": "Demo 2"
    }
  ]
}

Custom to Advanced

From:

[
  {
    "spec": "specs/demo1.json",
    "title": "Demo 1"
  }
]

To:

{
  "buildConfig": {
    "template": "minimal"
  },
  "posters": [
    {
      "id": "poster-1",
      "configPath": "specs/demo1.json",
      "name": "Demo 1"
    }
  ]
}

Validation

Required Fields

Simple format:

• Array of strings OR objects with spec property

Advanced format:

• buildConfig.template (required)
• Each poster must have id and configPath

Common Issues

Invalid ID:

// Bad - spaces and special chars
{ "id": "my poster #1" }

// Good - valid CSS selector
{ "id": "my-poster-1" }

Invalid Path:

// Bad - absolute filesystem path
{ "configPath": "/home/user/spec.json" }

// Good - relative or URL
{ "configPath": "specs/spec.json" }
{ "configPath": "https://example.com/spec.json" }

Duplicate IDs:

// Bad - duplicate IDs
{
  "posters": [
    { "id": "poster-1", "configPath": "spec1.json" },
    { "id": "poster-1", "configPath": "spec2.json" }  // Error!
  ]
}

// Good - unique IDs
{
  "posters": [
    { "id": "poster-1", "configPath": "spec1.json" },
    { "id": "poster-2", "configPath": "spec2.json" }
  ]
}

Examples Repository

All example poster list files can be found in /packages/demo-server/public/:

• example-poster-list.json - Simple array format
• example-poster-list-custom.json - Custom array with metadata
• example-poster-list-with-build.json - Advanced format with minimal template
• example-poster-list-sequential.json - Advanced format with sequential template

See Also

• Poster Spec Reference - Complete poster spec documentation
• API Reference - API documentation
• Getting Started Guide - Quick start guide