@enslo/sd-metadata 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rikuto Nakao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# sd-metadata
+
+A TypeScript library to read and write metadata embedded in AI-generated images.
+
+## Features
+
+- **Multi-format Support**: PNG (tEXt / iTXt), JPEG (COM / Exif), WebP (Exif)
+- **Unified API**: Simple `read()` and `write()` functions work across all formats
+- **TypeScript Native**: Written in TypeScript with full type definitions included
+- **Zero Dependencies**: Works in Node.js and browsers without any external dependencies
+- **Format Conversion**: Seamlessly convert metadata between PNG, JPEG, and WebP
+- **Lossless Round-trip**: Preserves original metadata structure when converting back to native format
+
+## Installation
+
+```bash
+npm install @enslo/sd-metadata
+```
+
+## Tool Support
+
+| Tool | PNG | JPEG | WebP |
+| ------ | :---: | :----: | :----: |
+| [NovelAI](https://novelai.net/) * | ✅ | 🔄️ | ✅ |
+| [ComfyUI](https://github.com/comfyanonymous/ComfyUI) * | ✅ | 🔄️ | 🔄️ |
+| [AUTOMATIC1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui) | ⚠️ | ⚠️ | ⚠️ |
+| [Forge](https://github.com/lllyasviel/stable-diffusion-webui-forge) / [Forge Neo](https://github.com/neggles/sd-webui-forge-neoforge) | ✅ | ✅ | ✅ |
+| [InvokeAI](https://github.com/invoke-ai/InvokeAI) | ✅ | 🔄️ | 🔄️ |
+| [SwarmUI](https://github.com/Stability-AI/StableSwarmUI) * | ✅ | ✅ | ✅ |
+| [Civitai](https://civitai.com/) | ⚠️ | ✅ | ⚠️ |
+| [TensorArt](https://tensor.art/) | ✅ | 🔄️ | 🔄️ |
+| [Stability Matrix](https://github.com/LykosAI/StabilityMatrix) | ✅ | 🔄️ | 🔄️ |
+| [HuggingFace Space](https://huggingface.co/spaces) | ✅ | 🔄️ | 🔄️ |
+| [Ruined Fooocus](https://github.com/runew0lf/RuinedFooocus) | ✅ | 🔄️ | 🔄️ |
+| [Easy Diffusion](https://github.com/easydiffusion/easydiffusion) | ⚠️ | ⚠️ | ⚠️ |
+| [Fooocus](https://github.com/lllyasviel/Fooocus) | ⚠️ | ⚠️ | ⚠️ |
+
+**Legend:**
+
+- ✅ **Fully Supported** - Formats natively supported by the tool, verified with sample files
+- 🔄️ **Extended Support** - sd-metadata specific parsers, cross-format conversion supported
+- ⚠️ **Experimental** - Implemented from reference code, not verified with samples
+
+> [!NOTE]
+> \* Tools with known limitations. See [Known Limitations](#known-limitations) for details.
+>
+> [!TIP]
+> **Help us expand tool support!** We're actively collecting sample images from experimental tools (Easy Diffusion, Fooocus) and unsupported tools. If you have sample images generated by these or other AI tools, please consider contributing them! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Usage
+
+### Node.js Usage
+
+```typescript
+import { read, write } from 'sd-metadata';
+import { readFileSync, writeFileSync } from 'fs';
+
+// Read metadata from any supported format
+const imageData = readFileSync('image.png');
+const result = read(imageData);
+
+if (result.status === 'success') {
+  console.log('Tool:', result.tool);           // 'novelai', 'comfyui', etc.
+  console.log('Prompt:', result.prompt);
+  console.log('Model:', result.parameters?.model);
+  console.log('Size:', result.width, 'x', result.height);
+}
+```
+
+### Browser Usage
+
+```typescript
+import { read } from 'sd-metadata';
+
+// Handle file input
+const fileInput = document.querySelector('input[type="file"]');
+fileInput.addEventListener('change', async (e) => {
+  const file = e.target.files[0];
+  const arrayBuffer = await file.arrayBuffer();
+  const imageData = new Uint8Array(arrayBuffer);
+  
+  const result = read(imageData);
+  
+  if (result.status === 'success') {
+    document.getElementById('tool').textContent = result.tool;
+    document.getElementById('prompt').textContent = result.prompt;
+    document.getElementById('model').textContent = result.parameters?.model || 'N/A';
+  }
+});
+```
+
+### Format Conversion
+
+Convert metadata between different image formats:
+
+```typescript
+import { read, write } from 'sd-metadata';
+
+// Read from PNG
+const pngData = readFileSync('comfyui-output.png');
+const metadata = read(pngData);
+
+// Write to JPEG
+const jpegData = readFileSync('target.jpg');
+const result = write(jpegData, metadata);
+
+if (result.type === 'success') {
+  writeFileSync('output.jpg', result.data);
+  console.log('Metadata converted from PNG to JPEG');
+}
+```
+
+### Handling Different Result Types
+
+```typescript
+import { read } from 'sd-metadata';
+
+const result = read(imageData);
+
+switch (result.status) {
+  case 'success':
+    // Metadata successfully parsed
+    console.log(`Generated by ${result.tool}`);
+    console.log(`Prompt: ${result.prompt}`);
+    break;
+
+  case 'unrecognized':
+    // Format detected but not recognized as AI-generated
+    console.log('Not an AI-generated image');
+    // You can still access raw metadata for debugging:
+    console.log('Raw chunks:', result.raw);
+    break;
+
+  case 'empty':
+    // No metadata found
+    console.log('No metadata in this image');
+    break;
+
+  case 'unsupportedFormat':
+    // Not a PNG, JPEG, or WebP file
+    console.log('Unsupported image format');
+    break;
+
+  case 'invalid':
+    // Corrupted or invalid image data
+    console.log('Error:', result.message);
+    break;
+}
+```
+
+### Force Conversion for Unrecognized Formats
+
+When you have unrecognized metadata but still want to convert it:
+
+```typescript
+import { read, write } from 'sd-metadata';
+
+const source = read(unknownImage);
+// source.status === 'unrecognized'
+
+// Force blind conversion (preserves all metadata chunks/segments)
+const result = write(targetImage, source, { force: true });
+
+if (result.type === 'success') {
+  // Metadata successfully converted even though format wasn't recognized
+  console.log('Forced conversion succeeded');
+}
+```
+
+### Removing Metadata
+
+To strip all metadata from an image:
+
+```typescript
+import { write } from 'sd-metadata';
+
+const result = write(imageData, { status: 'empty' });
+if (result.type === 'success') {
+  writeFileSync('clean-image.png', result.data);
+}
+```
+
+## API Reference
+
+### `read(data: Uint8Array): ParseResult`
+
+Reads and parses metadata from an image file.
+
+**Returns:**
+
+- `{ status: 'success', tool, prompt, parameters, width, height, raw }` - Successfully parsed
+- `{ status: 'unrecognized', raw }` - Image has metadata but not from a known AI tool
+- `{ status: 'empty' }` - No metadata found
+- `{ status: 'unsupportedFormat' }` - Not a PNG, JPEG, or WebP file
+- `{ status: 'invalid', message }` - Corrupted or invalid image data
+
+### `write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult`
+
+Writes metadata to an image file.
+
+**Parameters:**
+
+- `data` - Target image file data (PNG, JPEG, or WebP)
+- `metadata` - ParseResult from `read()`
+  - `status: 'success'` or `'empty'` - Can write directly
+  - `status: 'unrecognized'` - Requires `force: true` option
+- `options` - Optional settings:
+  - `force?: boolean` - Required when writing `status: 'unrecognized'` metadata
+
+**Returns:**
+
+- `{ type: 'success', data }` - Successfully written
+- `{ type: 'unsupportedFormat' }` - Target is not PNG, JPEG, or WebP
+- `{ type: 'conversionFailed', message }` - Metadata conversion failed
+- `{ type: 'writeFailed', message }` - Failed to write metadata to image
+
+## Known Limitations
+
+> [!WARNING]
+> **ComfyUI JPEG/WebP**: While reading supports major custom node formats (e.g., `save-image-extended`), writing always uses the `comfyui-saveimage-plus` format. This format provides the best information preservation and is compatible with ComfyUI's native drag-and-drop workflow loading.
+>
+> [!WARNING]
+> **NovelAI WebP**: Auto-corrects corrupted UTF-8 in the Description field, which means WebP → PNG → WebP round-trip is not content-equivalent (but provides valid, readable metadata).
+>
+> [!WARNING]
+> **SwarmUI PNG→JPEG/WebP**: PNG files contain both ComfyUI workflow and SwarmUI parameters. When converting to JPEG/WebP, only parameters are preserved to match the native format. Metadata is fully preserved, but the ComfyUI workflow in the `prompt` chunk is lost.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Test coverage
+npm run test:coverage
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Result type for explicit error handling
+ */
+type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Helper functions for Result type
+ */
+declare const Result: {
+    ok: <T, E>(value: T) => Result<T, E>;
+    error: <T, E>(error: E) => Result<T, E>;
+};
+/**
+ * PNG text chunk (tEXt or iTXt)
+ */
+type PngTextChunk = TExtChunk | ITXtChunk;
+/**
+ * Source location of a metadata segment.
+ * Used for round-tripping: reading and writing back to the correct location.
+ */
+type MetadataSegmentSource = {
+    type: 'exifUserComment';
+} | {
+    type: 'exifImageDescription';
+    prefix?: string;
+} | {
+    type: 'exifMake';
+    prefix?: string;
+} | {
+    type: 'jpegCom';
+};
+/**
+ * A single metadata segment with source tracking
+ */
+interface MetadataSegment {
+    /** Source location of this segment */
+    source: MetadataSegmentSource;
+    /** Raw data string */
+    data: string;
+}
+/**
+ * Raw metadata for write-back (preserves original format)
+ */
+type RawMetadata = {
+    format: 'png';
+    chunks: PngTextChunk[];
+} | {
+    format: 'jpeg';
+    segments: MetadataSegment[];
+} | {
+    format: 'webp';
+    segments: MetadataSegment[];
+};
+/**
+ * tEXt chunk (Latin-1 encoded text)
+ */
+interface TExtChunk {
+    type: 'tEXt';
+    /** Chunk keyword (e.g., 'parameters', 'Comment') */
+    keyword: string;
+    /** Text content */
+    text: string;
+}
+/**
+ * iTXt chunk (UTF-8 encoded international text)
+ */
+interface ITXtChunk {
+    type: 'iTXt';
+    /** Chunk keyword */
+    keyword: string;
+    /** Compression flag (0=uncompressed, 1=compressed) */
+    compressionFlag: number;
+    /** Compression method (0=zlib/deflate) */
+    compressionMethod: number;
+    /** Language tag (BCP 47) */
+    languageTag: string;
+    /** Translated keyword */
+    translatedKeyword: string;
+    /** Text content */
+    text: string;
+}
+/**
+ * Known AI image generation software
+ */
+type GenerationSoftware = 'novelai' | 'comfyui' | 'swarmui' | 'tensorart' | 'stability-matrix' | 'invokeai' | 'forge-neo' | 'forge' | 'sd-webui' | 'sd-next' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
+/**
+ * Metadata format classification
+ *
+ * This represents the format/structure of the metadata, not the specific tool.
+ * Use this to determine which fields are available and how to interpret them.
+ */
+type MetadataFormat = 'novelai' | 'comfyui' | 'a1111' | 'invokeai' | 'swarmui';
+/**
+ * Base metadata fields shared by all tools
+ */
+interface BaseMetadata {
+    /** Format classification (for type narrowing) */
+    type: MetadataFormat;
+    /** Positive prompt */
+    prompt: string;
+    /** Negative prompt */
+    negativePrompt: string;
+    /** Model settings */
+    model?: ModelSettings;
+    /** Sampling settings */
+    sampling?: SamplingSettings;
+    /** Hires.fix settings (if applied) */
+    hires?: HiresSettings;
+    /** Upscale settings (if applied) */
+    upscale?: UpscaleSettings;
+    /** Image width */
+    width: number;
+    /** Image height */
+    height: number;
+}
+/**
+ * NovelAI-specific metadata
+ */
+interface NovelAIMetadata extends BaseMetadata {
+    type: 'novelai';
+    software: 'novelai';
+    /** V4 character prompts (when using character placement) */
+    characterPrompts?: CharacterPrompt[];
+    /** Use character coordinates for placement */
+    useCoords?: boolean;
+    /** Use character order */
+    useOrder?: boolean;
+}
+/**
+ * Character prompt with position (NovelAI V4)
+ */
+interface CharacterPrompt {
+    /** Character-specific prompt */
+    prompt: string;
+    /** Character position (normalized 0-1) */
+    center?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * ComfyUI-format metadata (ComfyUI, TensorArt, Stability Matrix)
+ *
+ * These tools use ComfyUI-compatible workflow format.
+ */
+interface ComfyUIMetadata extends BaseMetadata {
+    type: 'comfyui';
+    software: 'comfyui' | 'tensorart' | 'stability-matrix';
+    /** Full workflow JSON (for reproducibility) */
+    workflow?: unknown;
+}
+/**
+ * A1111-format metadata (SD WebUI, Forge, Forge Neo, Civitai)
+ */
+interface A1111Metadata extends BaseMetadata {
+    type: 'a1111';
+    software: 'sd-webui' | 'sd-next' | 'forge' | 'forge-neo' | 'civitai' | 'hf-space' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
+}
+/**
+ * InvokeAI-specific metadata
+ */
+interface InvokeAIMetadata extends BaseMetadata {
+    type: 'invokeai';
+    software: 'invokeai';
+}
+/**
+ * SwarmUI-specific metadata
+ */
+interface SwarmUIMetadata extends BaseMetadata {
+    type: 'swarmui';
+    software: 'swarmui';
+}
+/**
+ * Unified generation metadata (discriminated union)
+ *
+ * Use `metadata.type` to narrow by format, or `metadata.software` for specific tool:
+ * ```typescript
+ * if (metadata.type === 'comfyui') {
+ *   // TypeScript knows metadata.workflow exists
+ * }
+ * if (metadata.software === 'tensorart') {
+ *   // Specific tool within comfyui format
+ * }
+ * ```
+ */
+type GenerationMetadata = NovelAIMetadata | ComfyUIMetadata | A1111Metadata | InvokeAIMetadata | SwarmUIMetadata;
+/**
+ * Model settings
+ */
+interface ModelSettings {
+    /** Model name */
+    name?: string;
+    /** Model hash */
+    hash?: string;
+    /** VAE name */
+    vae?: string;
+}
+/**
+ * Sampling settings
+ */
+interface SamplingSettings {
+    /** Sampler name */
+    sampler?: string;
+    /** Scheduler (sometimes included in sampler, sometimes separate) */
+    scheduler?: string;
+    /** Sampling steps */
+    steps?: number;
+    /** CFG scale */
+    cfg?: number;
+    /** Random seed */
+    seed?: number;
+    /** CLIP skip layers */
+    clipSkip?: number;
+}
+/**
+ * Hires.fix settings
+ */
+interface HiresSettings {
+    /** Upscale factor */
+    scale?: number;
+    /** Upscaler name */
+    upscaler?: string;
+    /** Hires steps */
+    steps?: number;
+    /** Hires denoising strength */
+    denoise?: number;
+}
+/**
+ * Upscale settings (post-generation)
+ */
+interface UpscaleSettings {
+    /** Upscaler name */
+    upscaler?: string;
+    /** Scale factor */
+    scale?: number;
+}
+/**
+ * Parse result with 4-status design
+ *
+ * - `success`: Parsing succeeded, metadata and raw data available
+ * - `empty`: No metadata found in the file
+ * - `unrecognized`: Metadata exists but format is not recognized
+ * - `invalid`: File is corrupted or not a valid image
+ */
+type ParseResult = {
+    status: 'success';
+    metadata: GenerationMetadata;
+    raw: RawMetadata;
+} | {
+    status: 'empty';
+} | {
+    status: 'unrecognized';
+    raw: RawMetadata;
+} | {
+    status: 'invalid';
+    message?: string;
+};
+
+/**
+ * sd-metadata - Read and write AI-generated image metadata
+ */
+
+/**
+ * Result of the write operation
+ */
+type WriteResult = Result<Uint8Array, {
+    type: 'unsupportedFormat';
+} | {
+    type: 'conversionFailed';
+    message: string;
+} | {
+    type: 'writeFailed';
+    message: string;
+}>;
+/**
+ * Options for write operation
+ */
+interface WriteOptions {
+    /**
+     * Force blind conversion for unrecognized formats
+     *
+     * When true, converts raw chunks/segments between formats even when
+     * the generating software is unknown. Enables format conversion for
+     * unknown/future tools without parser implementation.
+     *
+     * When false (default), returns error for unrecognized formats.
+     *
+     * @default false
+     */
+    force?: boolean;
+}
+/**
+ * Read and parse metadata from an image
+ *
+ * Automatically detects the image format (PNG, JPEG, WebP) and parses
+ * any embedded generation metadata.
+ *
+ * @param data - Image file data
+ * @returns Parse result containing metadata and raw data
+ */
+declare function read(data: Uint8Array): ParseResult;
+/**
+ * Write metadata to an image
+ *
+ * Automatically detects the target image format and converts the metadata
+ * if necessary.
+ *
+ * @param data - Target image file data
+ * @param metadata - ParseResult from `read()` (must be 'success' or contain raw data)
+ * @param options - Write options (e.g., { force: true } for blind conversion)
+ * @returns New image data with embedded metadata
+ */
+declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult;
+
+export { type GenerationMetadata, type GenerationSoftware, type MetadataFormat, type ParseResult, type RawMetadata, type WriteOptions, type WriteResult, read, write };