iComic authoring and encoding

This note lays out the intended production workflow for provisional iComic draft 0.3.1. Think of it as a working profile rather than a claim that one codec or preset is best for every comic. It also does not make the Gremmoire Reader or its tooling an open-source project.

Design goal

The working idea is one authoring system that handles the complete production path. It inspects masters, chooses and tunes suitable delivery encodes, builds the manifest from a template, validates the whole work, and packages it reproducibly. Uploading happens only after an explicit publish step.

That system may take several forms:

• a closed local CLI or desktop application for private production;
• a separate queued encoding service when the workload genuinely benefits from remote compute; or
• a bespoke variation built around another site’s publishing workflow.

Encoding stays outside an ordinary Reader request or a Cloudflare Worker response. It is expensive, long-running production work, and it should remain 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 delivery assets the work actually needs. For 0.3.1, the principal targets are:

WavPack and H.266/VVC are accepted as authoring inputs where useful. They are not current browser-delivery promises.

Content-aware decisions

A preset is not automatically correct just because its codec is newer. The tool should recommend formats based on the source and target instead of enforcing one format everywhere. The author should always be able to override the result.

Useful inspection signals include:

• dimensions, bit depth, alpha, color profile, grain, line density, gradients, photographic texture, and repeated flat color for images;
• sample rate, channels, peak and integrated loudness, silence, transient density, ambience, speech, and music for audio;
• frame size/rate, duration, alpha, motion, grain, cuts, text, and animation characteristics for video; and
• intended browsers, operating systems, devices, offline use, and quality/size priorities for the publication.

The authoring report should keep both automated measurements and manual choices. Experience and preference are still legitimate inputs, especially when two encodes are numerically close but look or sound different.

Preset families

Presets should describe intent while keeping their encoder settings auditable. A practical initial set could include:

• line-art: protects hard edges, fine hatching, text, and limited palettes;
• painted-page: balances gradients, texture, and subtle color;
• lossless-art: keeps a lossless delivery asset where source fidelity justifies it;
• voice: prioritizes intelligibility and stable loudness;
• ambience: preserves spatial texture while allowing aggressive compression;
• music: uses more conservative audio settings and channel handling;
• short-motion: optimized for brief animated panels and fast startup;
• high-motion: spends bitrate where motion and grain would otherwise break; and
• web-balanced: a general compatibility/efficiency profile when no specialist preset is appropriate.

Every preset needs a version and a complete resolved-settings record. If a preset changes later, an old package must still remain reproducible.

Draft 0.3.1 asset catalog

The manifest’s optional top-level assets array contains logical media. It may hold no more than 10,000 entries, and each entry may hold one to four variants:

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

The contract is:

• id is nonempty and unique;
• kind is image, audio, or video;
• fallback is a relative local path and appears in variants;
• delivery.selection is first-supported;
• delivery.profile records the authoring profile without granting a decoder;
• variants contains one to four entries in preference order;
• every variant has nonempty src and type, with optional codecs;
• the declared MIME, codec, extension, and actual media must agree;
• duplicate variant sources are not allowed; and
• one source must not represent conflicting logical assets or roles.

Image backgrounds, image/video panels, and audio cues may reference a logical asset through asset. The same holder must keep a baseline src exactly equal to that asset’s fallback. This lets an older Reader display or play the intended compatibility file.

Deterministic production pipeline

The authoring system should use a fixed, inspectable order:

1. Ingest — copy or fingerprint masters without modifying the originals.
2. Inspect — collect technical metadata and content signals.
3. Plan — resolve profile, target matrix, variants, dimensions, quality, and compatibility fallback for every logical asset.
4. Encode — produce temporary candidates with pinned encoder versions and complete commands/settings in the report.
5. Compare — measure outputs and generate visual/audio review material. Never promote a smaller encode solely because it is smaller.
6. Select — accept automated choices or record author overrides.
7. Template — write stable IDs, ordered variants, fallbacks, MIME/codec declarations, and content references into comic.json.
8. Validate — verify signatures, dimensions, duration, role, fallback bridges, accessibility text, limits, and browser-target expectations.
9. Package — write a reproducible .icomic, storing already-compressed media and compressing JSON/text.
10. Report — emit checksums, sizes, encoder settings, warnings, overrides, package inventory, and validation results.
11. Upload — only after a deliberate confirmation, send the finished package and publication metadata to its configured destination.

The pipeline should fail before packaging or upload if:

• an asset is missing;
• a signature conflicts with its declaration;
• a fallback is not present;
• an accessibility requirement is unmet; or
• a safety limit is exceeded.

Report and reproducibility

A retained build report should include:

• tool and preset versions;
• input fingerprints without embedding private masters;
• encoder identity and complete resolved settings;
• output hashes, dimensions/duration, MIME, codec, and byte size;
• rejected candidates and the reason each was rejected;
• manual overrides and short author notes;
• manifest and archive validation results;
• target-browser compatibility summary; and
• package hash and upload result, when upload was requested.

Given the same masters, configuration, and tool versions, the packager should produce equivalent media choices. It should also produce a byte-stable archive wherever the underlying encoders permit it.

Reader compatibility

The Reader chooses the first locally supplied variant that appears supported. Where practical, it retries later ordered variants if decoding fails. This is a compatibility aid, not a substitute for target testing.

The authoring system should test the real browser/device matrix relevant to a release. It should also avoid fallback ladders that add weight without useful coverage. A one-variant FLAC effect or PNG line-art page can be correct, just as an AV1/H.264 pair can be correct for a motion panel.

The format and Reader can expand their compatibility layers over time, but they should not introduce arbitrary executable plugins, remote asset fetching, or silent heavyweight decoder downloads.

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’ own work and publishing process.

For a bespoke Reader or authoring workflow adapted to another site, contact [email protected]. Once a bespoke source copy has been supplied, its recipient is free to host, adapt, modify, and otherwise use that delivered source as they wish. This applies to the supplied bespoke copy and does not make the Gremmoire Reader or general toolchain open source.