iComic format — provisional draft 0.3.1

This specification is provisional. It lets the Reader and the authoring workflow be tested together, but it is not yet a stable interchange or archival standard. Fields, limits, profiles, and migration rules may change before a stable release.

Think of iComic as a page-first interactive-comic format, not a video file wearing a comic interface. Each page owns a set of layered panels and moves through discrete reveal steps.

Animation, audio, backgrounds, captions, haptics, and optional depth can respond to those steps. The essential page must still remain readable without any of them.

Working identity

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.3.1"
}

The main development container is .icomic. Underneath the custom extension, it is an ordinary ZIP archive. Ordinary .zip files also remain accepted during development.

Draft 0.3.1 adds two things: a bounded media catalog and ordered local alternatives. The current Reader can still read drafts 0.3 and 0.2, but those drafts do not gain guarantees for fields they never declared.

Media-profile principle

The formats named here are first-class options, not universal winners. Results depend on the source, content, encoder, chosen quality, target browser and operating system, and the author’s experience and preference.

In practice, flat line art may need a different choice from painted pages, and voice may need a different choice from ambience or short motion panels.

Draft 0.3.1 standardizes the combinations worth optimizing deeply while keeping fallbacks explicit and ordered. The format and Reader may add compatibility layers where practical, but packages cannot assume that every browser includes every decoder. The Reader will not silently download a heavyweight decoder just to play an optional variant.

Current first-class delivery targets are:

WavPack and H.266/VVC can be useful authoring/master inputs, especially when their quality-to-size trade-offs suit the source. They are not 0.3.1 browser-delivery promises. An authoring tool may accept them, then produce the ordered web-delivery variants declared in the package.

Animated AVIF and GIF remain outside the current static-image contract.

Minimum manifest

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.3.1",
  "id": "my-comic",
  "title": "My Comic",
  "pages": [
    {
      "id": "page-1",
      "panels": [
        {
          "id": "page-1-art",
          "type": "image",
          "src": "assets/pages/page-001.webp",
          "alt": "Describe the page art here."
        }
      ]
    }
  ]
}

The assets catalog is optional. A single-source manifest remains valid, and its src fields resolve exactly as before.

Recommended archive layout

my-comic.icomic                    # ZIP file with a custom extension
|-- comic.json                    # REQUIRED at archive root
|-- assets/
|   |-- panels/
|   |   |-- bush.avif
|   |   `-- bush.webp
|   |-- backgrounds/
|   |   |-- dusk.avif
|   |   `-- dusk.webp
|   |-- audio/
|   |   |-- rain.opus
|   |   |-- rain.m4a
|   |   `-- branch-snap.flac
|   `-- video/
|       |-- branch-rattle-av1.webm
|       `-- branch-rattle-h264.mp4
`-- README.txt                    # Optional production notes; ignored

The current archive rules are straightforward:

• Put the preferred manifest, comic.json, at the archive root. story.json, manifest.json, and reader.json remain development aliases.
• Include exactly one recognized root manifest.
• Keep asset paths relative, /-separated, and case-sensitive.
• A leading ./ is normalized away.
• Absolute paths, parent traversal, backslashes, controls, null bytes, ambiguous names, and duplicate paths are rejected.
• Encrypted entries and nested-container semantics are unsupported.
• Store and DEFLATE are the only accepted ZIP methods.
• A media path must match a selected sibling or archive entry. Unmatched, absolute, and protocol-based values are blanked instead of fetched.

Packaging performance

The Reader opens comic.json first. It then resolves media for the page being viewed, and it may warm a bounded part of the next page while idle.

For ZIP compression, use this working split:

• Use Store for AVIF, WebP, PNG, JPEG, FLAC, Opus, AAC/M4A, MP3, MP4, WebM, and other media that is already compressed. DEFLATE usually saves little on these files and adds extraction work.
• Use DEFLATE for comic.json and other small JSON or text files.
• Treat PCM WAV as an exception. Test whether DEFLATE is worthwhile, or choose a lossless delivery codec instead of assuming it behaves like compressed media.

Keep authoring masters outside the .icomic. The future packer should choose this profile deterministically and record every decision in its report.

Media delivery and asset catalog

Top-level assets

assets is an optional array of logical media assets. One manifest may declare at most 10,000 assets. Each asset may declare at most four ordered variants.

{
  "assets": [
    {
      "id": "page-1-art",
      "kind": "image",
      "fallback": "assets/pages/page-001.webp",
      "delivery": {
        "profile": "web-balanced",
        "selection": "first-supported"
      },
      "variants": [
        {
          "src": "assets/pages/page-001.avif",
          "type": "image/avif"
        },
        {
          "src": "assets/pages/page-001.webp",
          "type": "image/webp"
        }
      ]
    }
  ]
}

Each asset uses these fields:

Each variant uses these fields:

There are three important path rules:

• Do not duplicate a src within one asset.
• Do not bind one path to several logical assets.
• Do not assign the same path conflicting media roles.

A declared type is a claim the package must satisfy. It cannot be used to disguise an extension.

delivery.profile is a short authoring label recorded for inspection. It does not grant features or choose a decoder.

The only 0.3.1 selection mode is first-supported. Variants are tried in manifest order, subject to the browser’s declared support and successful decoding. If delivery data is omitted, it normalizes to an empty profile and first-supported.

Referencing a logical asset

An image background, image/video panel, or audio cue may add an asset field:

{
  "type": "image",
  "asset": "page-1-art",
  "src": "assets/pages/page-001.webp"
}

The reference must exist, and its kind must match how it is used:

• Image backgrounds and image panels require image.
• Video panels require video.
• Audio cues require audio.

For draft compatibility, src remains required on media-bearing content. It must exactly equal the referenced asset’s fallback.

This gives older Readers a usable baseline file, while 0.3.1 Readers may select a better supported variant. The fallback is not a fifth hidden variant.

For page media and pixel budgets, all alternatives count as one logical asset. The largest alternative is used for that logical asset’s accounting instead of summing equivalent encodings. Every stored byte still counts toward archive and entry limits.

Fully annotated example

JSON cannot contain comments, so notes follow the example.

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.3.1",
  "id": "bush-at-dusk-test",
  "title": "Bush at Dusk — Interaction Test",
  "creator": "ValentineDesigns",
  "description": "A non-canon technical sample for reveals and media selection.",
  "language": "en",
  "direction": "ltr",

  "assets": [
    {
      "id": "dusk-background",
      "kind": "image",
      "fallback": "assets/backgrounds/dusk.webp",
      "delivery": {
        "profile": "web-balanced",
        "selection": "first-supported"
      },
      "variants": [
        { "src": "assets/backgrounds/dusk.avif", "type": "image/avif" },
        { "src": "assets/backgrounds/dusk.webp", "type": "image/webp" }
      ]
    },
    {
      "id": "bush-art",
      "kind": "image",
      "fallback": "assets/panels/bush.webp",
      "delivery": {
        "profile": "web-balanced",
        "selection": "first-supported"
      },
      "variants": [
        { "src": "assets/panels/bush.avif", "type": "image/avif" },
        { "src": "assets/panels/bush.webp", "type": "image/webp" }
      ]
    },
    {
      "id": "rain-bed",
      "kind": "audio",
      "fallback": "assets/audio/rain.m4a",
      "delivery": {
        "profile": "web-balanced",
        "selection": "first-supported"
      },
      "variants": [
        {
          "src": "assets/audio/rain.opus",
          "type": "audio/ogg",
          "codecs": "opus"
        },
        {
          "src": "assets/audio/rain.m4a",
          "type": "audio/mp4",
          "codecs": "mp4a.40.2"
        }
      ]
    },
    {
      "id": "branch-snap",
      "kind": "audio",
      "fallback": "assets/audio/branch-snap.flac",
      "delivery": {
        "profile": "lossless-effects",
        "selection": "first-supported"
      },
      "variants": [
        {
          "src": "assets/audio/branch-snap.flac",
          "type": "audio/flac"
        }
      ]
    },
    {
      "id": "branch-motion",
      "kind": "video",
      "fallback": "assets/video/branch-rattle-h264.mp4",
      "delivery": {
        "profile": "web-balanced",
        "selection": "first-supported"
      },
      "variants": [
        {
          "src": "assets/video/branch-rattle-av1.webm",
          "type": "video/webm",
          "codecs": "av01.0.08M.08"
        },
        {
          "src": "assets/video/branch-rattle-h264.mp4",
          "type": "video/mp4",
          "codecs": "avc1.4D401F"
        }
      ]
    }
  ],

  "experimental": {
    "customContainer": true,
    "animatedPanels": true,
    "audioCues": true,
    "dynamicBackgrounds": true,
    "depth": true,
    "timedReveals": true
  },

  "presentation": {
    "fit": "contain",
    "startMode": "panel",
    "pageGap": 18
  },

  "pages": [
    {
      "id": "dusk-page",
      "label": "Dusk / three reveals",
      "aspectRatio": "2/3",

      "background": {
        "type": "image",
        "asset": "dusk-background",
        "src": "assets/backgrounds/dusk.webp",
        "fit": "cover",
        "depth": -2
      },

      "cues": [
        {
          "id": "rain-bed-cue",
          "type": "audio",
          "trigger": "enter",
          "asset": "rain-bed",
          "src": "assets/audio/rain.m4a",
          "volume": 0.3,
          "loop": true,
          "channel": "ambience"
        }
      ],

      "panels": [
        {
          "id": "bush",
          "type": "image",
          "asset": "bush-art",
          "src": "assets/panels/bush.webp",
          "alt": "A dense bush moving against the still dusk.",
          "frame": {
            "x": 5,
            "y": 8,
            "width": 90,
            "height": 46,
            "rotation": 0,
            "radius": 1.5
          },
          "fit": "cover",
          "depth": 1,
          "z": 2,
          "reveal": {
            "atStep": 0,
            "transition": "fade",
            "durationMs": 500
          },
          "animation": {
            "type": "drift",
            "durationMs": 8000,
            "amount": 0.35
          }
        },
        {
          "id": "branches",
          "type": "video",
          "asset": "branch-motion",
          "src": "assets/video/branch-rattle-h264.mp4",
          "alt": "Branches rattle and settle.",
          "frame": { "x": 5, "y": 8, "width": 90, "height": 46 },
          "fit": "cover",
          "depth": 2,
          "z": 3,
          "reveal": {
            "atStep": 1,
            "transition": "focus",
            "durationMs": 240
          },
          "playback": {
            "autoplay": true,
            "muted": true,
            "loop": false,
            "playsInline": true
          },
          "cues": [
            {
              "id": "branch-snap-cue",
              "type": "audio",
              "trigger": "reveal",
              "asset": "branch-snap",
              "src": "assets/audio/branch-snap.flac",
              "delayMs": 80,
              "volume": 0.65,
              "channel": "effects"
            },
            {
              "id": "branch-caption",
              "type": "caption",
              "trigger": "reveal",
              "text": "Branches rattle.",
              "durationMs": 1800
            }
          ]
        },
        {
          "id": "figure",
          "type": "image",
          "src": "assets/panels/figure.webp",
          "alt": "A tired figure rises behind the bush.",
          "frame": { "x": 12, "y": 33, "width": 76, "height": 58 },
          "fit": "contain",
          "depth": 3,
          "z": 4,
          "reveal": {
            "atStep": 2,
            "transition": "rise",
            "durationMs": 650
          }
        }
      ]
    }
  ]
}

The first image or media alternative is the preferred encoding. The baseline fallback stays authoritative for older Readers.

The FLAC effect uses one variant because lossless quality is intentional in that case. A package does not need to manufacture alternatives that add no practical value.

Top-level fields

Each context entry uses a stable id, short label, title, and concise body. An optional exact term links matching words in text panels to a hover/focus preview and click/tap appendix entry; optional details supplies the expanded explanation. The same text-only shape is used by prose Reader documents. Entries without term remain available from Comic margins.

experimental

The current boolean declarations are:

• customContainer
• animatedPanels
• audioCues
• dynamicBackgrounds
• depth
• timedReveals

These fields describe expectations. They are not security permissions. A Reader may disable an enhancement, but it must still expose the readable core.

presentation

Page, panel, background, and cue fields

Page

Background

{
  "type": "image",
  "asset": "dusk-background",
  "src": "assets/backgrounds/dusk.webp",
  "fit": "cover",
  "depth": -1
}

Recognized background types are color, gradient, image, and dynamic. The optional asset field is valid only for an image background.

dynamic remains a placeholder category. Its value accepts only a narrow, sanitized color/gradient grammar. Network-capable CSS functions and URL/data/blob schemes fall back safely.

Panel

Frames use page-relative percentages. Reveal steps are nonnegative integers.

Recognized transitions are:

• none
• fade
• rise
• slide-left
• slide-right
• ink
• focus

Decorative animation types are:

• none
• drift
• pulse
• float
• pan
• breathe

Decorative animation must not carry information that disappears under reduced motion.

Playback hints are autoplay, muted, loop, and playsInline. Browser autoplay and codec rules override these hints.

Cue

{
  "id": "soft-signal",
  "type": "audio",
  "trigger": "reveal",
  "asset": "signal-audio",
  "src": "assets/audio/signal.m4a",
  "text": "Optional visible caption",
  "delayMs": 0,
  "volume": 0.65,
  "loop": false,
  "channel": "effects"
}

Recognized cue types are:

• audio
• tone
• background
• vibrate
• caption

Only an audio cue may reference an audio asset. The common current triggers are enter and reveal.

Channel replacement, crossfade, persistence, loop lifetime, and mastering metadata remain provisional.

The current Reader dispatches cues for every panel revealed on the same step. It cancels pending delayed cues when another reveal begins or the page changes.

Current safety and resource limits

The current rejection ceilings are:

• 500 MB selected custom-container file;
• 10,000 pages;
• 10,000 logical assets and four variants per logical asset;
• 100 author-context entries;
• 2,048 characters per media source path;
• 80 MB per expanded entry;
• 1.5 GB total expanded archive;
• 100:1 maximum compression ratio;
• 50,000 archive entries;
• 2 MB root manifest;
• 256 panels per page and 20,000 panels plus cues per work;
• four video panels, 128 total cues, and 16 sound cues per page;
• 16,384 pixels per raster axis, 20 megapixels per raster item, and 24 megapixels per rendered page.

These are safety limits, not performance promises. A valid package may still be too demanding for a particular phone, browser, or operating system.

Reader conformance principles

A future conforming Reader should:

1. Show essential visual and text content without sound, haptics, animation, depth, sensors, or a particular optional codec.
2. Preserve author-defined reveal order while allowing a complete page reveal.
3. Respect reduced motion and mute settings immediately.
4. Provide keyboard and button navigation independent of gestures.
5. Never execute arbitrary scripts, HTML, CSS, plugins, or network calls from an iComic.
6. Select only bounded local variants and warn about unsupported required features rather than silently losing comic-critical content.
7. Expose authored alt text, captions, and reading order.
8. Tear down media, timers, sensors, decoders, and temporary URLs when leaving a work.

Packaging checklist

• Put one recognized manifest at the archive root, preferably comic.json.
• Set schemaVersion to 0.3.1 when using assets, per-asset delivery, or asset.
• Use unique page, panel, cue, and logical-asset IDs.
• Use relative /-separated paths with exact filename case.
• Keep every referenced fallback in its asset’s ordered variant list.
• Make each media-bearing src exactly match its referenced fallback.
• Declare accurate MIME types and codec strings, then test every variant.
• Include meaningful alt text and visible captions/transcripts.
• Test the package with sound off, reduced motion on, and depth off.
• Test current Chromium, Firefox, and Safari-family targets where relevant.
• Test both panel and page modes, largest UI text, and high contrast.
• Keep masters and private production material outside the .icomic.
• Store already-compressed media; compress JSON/text.
• Stay well below safety ceilings on representative target devices.
• Do not include scripts, remote URLs, credentials, or encrypted entries.
• Retain the deterministic packer report with the publication master.

See Authoring and encoding for the planned content-aware encoding, validation, packaging, and upload workflow.

Source availability and bespoke Readers

The iComic specification and observable behavior may be discussed publicly. The Gremmoire Reader and its authoring/tooling source remain closed.

The implementation is tuned around ValentineDesigns’ work and publishing workflow. Publishing it as a general-purpose codebase would imply portability and support that it is not designed to provide.

For a bespoke Reader or authoring workflow adapted to another site, contact [email protected].

A recipient who receives a bespoke source copy is free to host, adapt, modify, and otherwise use that supplied source as they wish. This permission applies to the delivered bespoke copy. It does not make the Gremmoire Reader or the general toolchain open source.

Open format questions

• Final MIME type, naming, ownership, and long-term version negotiation.
• Stable migration rules and unsupported-version behavior.
• Asset hashes, integrity, deduplication, and reproducible profile metadata.
• Whether large works need a compiled index or streaming/chunked container.
• Branching and localization without making progress state opaque.
• Typed backgrounds and a constrained animation/effect vocabulary.
• Audio bus, mastering, captions, transcripts, and deterministic loop lifetime.
• Screen-reader panel order and reveal announcements.
• Creator-intended crop, zoom, orientation, and optional parallax bounds.
• Which capabilities become required, optional, or safely ignorable.
• Signing and provenance without DRM or mandatory online checks.