iComic authoring and encoding

This note describes the production workflow for provisional iComic draft 0.4.0. It is a working profile, not a claim that one codec or preset is best for every project. It also does not make the Gremmoire Reader or its tooling an open-source project.

What is working now

Reader Publisher’s iComic template produces an actual .icomic archive whose canonical root is comic.json. The export carries:

• included page records in binder order;
• page summaries and explicit accessible panel order;
• staged images and video with placement, fit, opacity, blend, effect, and reveal timing;
• ambient or step-triggered local audio cues;
• accessible descriptions for image/video content;
• optional cover and first-page opening artwork with a separate opening reveal;
• Reader-wide context and extended appendix entries;
• required/optional capabilities; and
• exact packaged byte sizes for every exported media variant.

The export runs through the Reader’s own 0.4.0 manifest validator before download. It remains a local, unpublished delivery package. Saving a Publisher draft and exporting .icomic are separate actions.

Publisher can also open a local .icomic through the actual Reader archive loader. It reconstructs pages and media placements from declared local fallbacks. A multi-variant import deliberately stages only each asset’s fallback and warns the author, because a delivery archive does not replace layered masters.

Design goal

The intended production system covers the complete path: inspect masters, make content-aware delivery recommendations, build the manifest, validate the work, package it reproducibly, and report what happened. Uploading occurs only after an explicit publish action; export itself never posts a work.

Encoding remains outside an ordinary Reader request or edge-worker response. It is long-running production work and should stay separate from playback.

Masters and deliverables

Keep source images, layered projects, editing timelines, WavPack or PCM audio masters, H.266/VVC or mezzanine video, and private production notes outside the .icomic archive.

The package contains only the local delivery assets the work needs:

WavPack and H.266/VVC can be authoring inputs, not current browser-delivery promises. Reader Publisher blocks WavPack from iComic export until it has a deterministic delivery conversion instead of preserving an unplayable cue.

Content-aware decisions

A newer codec is not automatically the correct codec. Recommendations should consider the source, target devices, and desired result, with author override:

• dimensions, bit depth, alpha, color profile, grain, line density, gradients, texture, and flat-color repetition for images;
• sample rate, channels, loudness, silence, transients, ambience, speech, and music for audio;
• frame size/rate, duration, alpha, motion, grain, cuts, and text for video; and
• browser/OS coverage, offline use, startup cost, quality, and package size.

Useful preset families include line-art, painted-page, lossless-art, voice, ambience, music, short-motion, high-motion, and web-balanced. Every preset should record its version and resolved settings.

0.4.0 asset contract

The optional assets catalog contains up to 10,000 logical assets and up to four ordered variants per asset. Each asset declares a unique ID, media kind, local fallback, ordered variants, and optional delivery profile. Every variant declares a local source and MIME type, plus optional codec and exact byte size.

The contract requires:

• kind is image, audio, or video;
• fallback appears in the variant list;
• delivery.selection, when supplied, is first-supported;
• MIME, codec, extension, role, and actual media agree;
• declared bytes, when present, exactly matches the archive entry;
• no source belongs to two logical assets or conflicting roles; and
• a holder with asset retains src equal to the declared fallback.

Reader Publisher beta creates one publisher-source variant per staged layer. That is a valid minimal ladder. A future encoder should emit more variants only when they add real compatibility or efficiency.

Authoring model

Treat every page as four connected records:

1. Readable core — summary, panel descriptions or text, and captions.
2. Visual composition — frame, fit, stacking, opacity, blend, and bounded effect.
3. Interaction — discrete reveal step, transition, and duration.
4. Media cues — page-entry or explicit step audio/video behavior.

The manifest’s readingOrder is independent of z. Arrange it as the page is meant to be understood, then control visual stacking separately. Meaning cannot depend on animation, compositing, sound, hover, or one codec.

Context entries are work-wide in the 0.4.0 iComic contract. Publisher may let an author create one while focused on a page, but export consolidates it into the Reader-wide appendix. Exact linked terms remain optional.

Deterministic production pipeline

1. Ingest — fingerprint masters without modifying them.
2. Inspect — collect technical metadata and content signals.
3. Plan — resolve target matrix, variants, fallback, dimensions, and quality.
4. Encode — use pinned tools and record complete settings.
5. Compare — generate review material; never promote an output only because it is smaller.
6. Select — record automated choices and author overrides.
7. Author — write IDs, summaries, reading order, capabilities, context, cues, and fallbacks.
8. Validate — verify accessibility, signatures, roles, sizes, limits, and capabilities.
9. Package — DEFLATE JSON/text and store already-compressed media.
10. Report — record hashes, sizes, settings, warnings, inventory, and validation.
11. Publish — upload only after separate deliberate confirmation.

The pipeline should fail before packaging or upload when an asset is missing, a signature/type/role conflicts, a declared byte size differs, a fallback bridge is invalid, an accessibility requirement is unmet, a required capability is unknown, or a safety limit is exceeded.

Report and reproducibility

A retained build report should include:

• tool, encoder, and preset versions;
• input fingerprints without embedding private masters;
• complete resolved encoding settings;
• output hash, MIME, codec, dimensions/duration, and byte size;
• rejected candidates and reasons;
• author overrides;
• capability and accessible-fallback review;
• manifest/archive validation and package hash; and
• upload result only when publishing was explicitly requested.

Given the same masters, configuration, and tools, the packager should make equivalent choices and produce a byte-stable archive wherever encoders permit.

Preflight checklist

• Confirm every included binder item is meant to become a page.
• Write a concise page summary and meaningful image/video descriptions.
• Check panel reading order separately from visual layer order.
• Test entry and step cues with autoplay denied and sound muted.
• Preview reduced motion, high contrast, largest text, panel mode, and page mode.
• Verify all files are local and all declared byte sizes are exact.
• Keep the editable Publisher draft, original .icomic, and masters together.
• Run the current Reader validator before making the file available.
• Use the separate explicit publish step only after reviewing the export.

Remaining production work

• content-aware multi-variant encoding and comparison UI;
• reproducible encoder reports and asset hashes;
• transcript/caption authoring tied directly to audio cues;
• lossless multi-variant re-import instead of fallback reconstruction;
• migration tooling for future schemas;
• representative device/browser performance profiles; and
• a separately reviewed upload destination and release workflow.

Source availability and bespoke work

The iComic specification and observable behavior may be discussed publicly. The Gremmoire Reader and its authoring/tooling source remain closed because they are designed around ValentineDesigns’ publishing process.

For a bespoke Reader or authoring workflow adapted to another site, contact [email protected]. A recipient may host, adapt, modify, and use the bespoke source copy supplied to them. That does not make the Gremmoire Reader or general toolchain open source.