@enslo/sd-metadata 1.1.1 → 1.3.0

package/README.md

@@ -4,6 +4,8 @@
 [![npm downloads](https://img.shields.io/npm/dm/@enslo/sd-metadata.svg)](https://www.npmjs.com/package/@enslo/sd-metadata)
 [![license](https://img.shields.io/npm/l/@enslo/sd-metadata.svg)](https://github.com/enslo/sd-metadata/blob/main/LICENSE)
 
+🇯🇵 **[日本語版はこちら](./README.ja.md)**
+
 A TypeScript library to read and write metadata embedded in AI-generated images.
 
 ## Features
@@ -88,7 +90,7 @@ const { read } = require('@enslo/sd-metadata');
 ### Node.js Usage
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 import { readFileSync, writeFileSync } from 'fs';
 
 // Read metadata from any supported format
@@ -106,7 +108,7 @@ if (result.status === 'success') {
 ### Browser Usage
 
 ```typescript
-import { read } from 'sd-metadata';
+import { read } from '@enslo/sd-metadata';
 
 // Handle file input
 const fileInput = document.querySelector('input[type="file"]');
@@ -151,15 +153,18 @@ if (result.status === 'success') {
 > For production use, pin to a specific version instead of `@latest`:
 >
 > ```text
-> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.1.1/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.3.0/dist/index.js
 > ```
 
-### Format Conversion
+### Advanced Examples
+
+<details>
+<summary>Format Conversion</summary>
 
 Convert metadata between different image formats:
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 
 // Read metadata from PNG
 const pngData = readFileSync('comfyui-output.png');
@@ -182,10 +187,13 @@ if (parseResult.status === 'success') {
 > [!TIP]
 > This library handles metadata read/write only. For actual image format conversion (decoding/encoding pixels), use image processing libraries like [sharp](https://www.npmjs.com/package/sharp), [jimp](https://www.npmjs.com/package/jimp), or browser Canvas API.
 
-### Handling Different Result Types
+</details>
+
+<details>
+<summary>Handling Different Result Types</summary>
 
 ```typescript
-import { read } from 'sd-metadata';
+import { read } from '@enslo/sd-metadata';
 
 const result = read(imageData);
 
@@ -215,31 +223,37 @@ switch (result.status) {
 }
 ```
 
-### Force Conversion for Unrecognized Formats
+</details>
 
-When you have unrecognized metadata but still want to convert it:
+<details>
+<summary>Preserving Unrecognized Metadata</summary>
+
+When converting images with metadata from unsupported tools, you can still preserve the original metadata:
 
 ```typescript
-import { read, write } from 'sd-metadata';
+import { read, write } from '@enslo/sd-metadata';
 
 const source = read(unknownImage);
 // source.status === 'unrecognized'
 
-// Force blind conversion (preserves all metadata chunks/segments)
+// Preserve all original metadata chunks/segments
 const result = write(targetImage, source, { force: true });
 
 if (result.ok) {
-  // Metadata successfully converted even though format wasn't recognized
-  console.log('Forced conversion succeeded');
+  // Original metadata preserved in the new image
+  console.log('Metadata preserved successfully');
 }
 ```
 
-### Removing Metadata
+</details>
+
+<details>
+<summary>Removing Metadata</summary>
 
 To strip all metadata from an image:
 
 ```typescript
-import { write } from 'sd-metadata';
+import { write } from '@enslo/sd-metadata';
 
 const result = write(imageData, { status: 'empty' });
 if (result.ok) {
@@ -247,6 +261,74 @@ if (result.ok) {
 }
 ```
 
+</details>
+
+<details>
+<summary>Writing Metadata in WebUI Format</summary>
+
+Create and embed custom metadata in SD WebUI (A1111) format:
+
+```typescript
+import { writeAsWebUI } from '@enslo/sd-metadata';
+
+// Create custom metadata from scratch
+const metadata = {
+  software: 'sd-webui',
+  prompt: 'masterpiece, best quality, 1girl',
+  negativePrompt: 'lowres, bad quality',
+  width: 512,
+  height: 768,
+  sampling: {
+    steps: 20,
+    sampler: 'Euler a',
+    cfg: 7,
+    seed: 12345,
+  },
+  model: { name: 'model.safetensors' },
+};
+
+// Write to any image format (PNG, JPEG, WebP)
+const result = writeAsWebUI(imageData, metadata);
+if (result.ok) {
+  writeFileSync('output.png', result.value);
+}
+```
+
+> [!TIP]
+> `writeAsWebUI` is particularly useful when:
+>
+> - Creating images programmatically and want to embed generation parameters
+> - Converting metadata from proprietary formats to WebUI-compatible format
+> - Building tools that need to output WebUI-readable metadata
+
+</details>
+
+<details>
+<summary>Formatting Metadata for Display</summary>
+
+Convert metadata from **any supported tool** to a unified, human-readable WebUI format. This normalizes the differences between tools (NovelAI, ComfyUI, Forge, etc.) into a consistent text format:
+
+```typescript
+import { read, formatAsWebUI } from '@enslo/sd-metadata';
+
+const result = read(imageData);
+if (result.status === 'success') {
+  // Works with any tool: NovelAI, ComfyUI, Forge, InvokeAI, etc.
+  const text = formatAsWebUI(result.metadata);
+  console.log(text);
+  
+  // Always outputs in consistent WebUI format:
+  // masterpiece, best quality, 1girl
+  // Negative prompt: lowres, bad quality
+  // Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, Model: model.safetensors
+}
+```
+
+> [!NOTE]
+> Regardless of which tool generated the image, `formatAsWebUI` extracts the common generation parameters and formats them in a standardized way. This is ideal for displaying metadata to users without worrying about tool-specific formats.
+
+</details>
+
 ## API Reference
 
 ### `read(data: Uint8Array): ParseResult`
@@ -275,13 +357,101 @@ Writes metadata to an image file.
   - `status: 'success'` or `'empty'` - Can write directly
   - `status: 'unrecognized'` - Requires `force: true` option
 - `options` - Optional settings:
-  - `force?: boolean` - Required when writing `status: 'unrecognized'` metadata (blind conversion)
+  - `force?: boolean` - Enables writing unrecognized metadata (preserves original data as-is)
+
+**Returns:**
+
+- `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
+- `{ ok: false, error: { type, message? } }` - Failed. `type` is one of:
+  - `'unsupportedFormat'`: Target image is not PNG, JPEG, or WebP
+  - `'conversionFailed'`: Metadata conversion failed (e.g., incompatible format)
+  - `'writeFailed'`: Failed to embed metadata into the image
+
+### `writeAsWebUI(data: Uint8Array, metadata: GenerationMetadata): WriteResult`
+
+Writes metadata to an image in SD WebUI (A1111) format.
+
+**Parameters:**
+
+- `data` - Target image file data (PNG, JPEG, or WebP)
+- `metadata` - Generation metadata to embed
+  - Can be from any tool or custom-created
+  - Automatically converted to WebUI format
 
 **Returns:**
 
 - `{ ok: true, value: Uint8Array }` - Successfully written (returns new image data)
-- `{ ok: false, error: { type: string, message?: string } }` - Failed
-  - `type`: `'unsupportedFormat'`, `'conversionFailed'`, or `'writeFailed'`
+- `{ ok: false, error: { type, message? } }` - Failed. `type` is one of:
+  - `'unsupportedFormat'`: Target image is not PNG, JPEG, or WebP
+  - `'writeFailed'`: Failed to embed metadata into the image
+
+**Use cases:**
+
+- Creating custom metadata for programmatically generated images
+- Converting metadata from other tools to WebUI-compatible format
+- Building applications that output WebUI-readable metadata
+
+### `formatAsWebUI(metadata: GenerationMetadata): string`
+
+Formats metadata as human-readable text in SD WebUI (A1111) format.
+
+**Parameters:**
+
+- `metadata` - Generation metadata from any tool
+
+**Returns:**
+
+- Human-readable string in WebUI format (plain text)
+
+**Output format:**
+
+```text
+positive prompt
+[character prompts for NovelAI]
+Negative prompt: negative prompt
+Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, ...
+```
+
+**Use cases:**
+
+- Displaying metadata to users in a consistent format
+- Copying generation parameters as text
+- Logging or debugging generation settings
+
+### `formatRaw(raw: RawMetadata): string`
+
+Formats raw metadata as plain text.
+
+**Parameters:**
+
+- `raw` - Raw metadata from `ParseResult` (`result.raw`)
+
+**Returns:**
+
+- Plain text content from the metadata (multiple entries separated by blank lines)
+
+**Use cases:**
+
+- Displaying unrecognized metadata to users
+- Quick inspection of raw metadata content
+- Fallback display when parsing fails
+
+**Example:**
+
+```typescript
+import { read, formatAsWebUI, formatRaw } from '@enslo/sd-metadata';
+
+const result = read(imageData);
+
+switch (result.status) {
+  case 'success':
+    console.log(formatAsWebUI(result.metadata));
+    break;
+  case 'unrecognized':
+    console.log(formatRaw(result.raw));
+    break;
+}
+```
 
 ## Type Reference
 
@@ -401,7 +571,7 @@ type RawMetadata =
 >
 > Use your IDE's IntelliSense for auto-completion and inline documentation.
 
-For detailed documentation of all exported types including `BaseMetadata`, `ModelSettings`, `SamplingSettings`, and format-specific types, see the [Type Documentation](./docs/types.md).
+For detailed documentation of all exported types including `ModelSettings`, `SamplingSettings`, and format-specific types, see the [Type Documentation](./docs/types.md).
 
 ## Development
 

package/dist/index.d.ts

@@ -305,7 +305,28 @@ type ParseResult = {
 };
 
 /**
- * sd-metadata - Read and write AI-generated image metadata
+ * Read API for sd-metadata
+ *
+ * Handles reading and parsing metadata from images.
+ * Automatically detects image format and extracts embedded generation metadata.
+ */
+
+/**
+ * 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 API for sd-metadata
+ *
+ * Handles writing metadata to images with automatic format conversion.
+ * Supports PNG, JPEG, and WebP formats.
  */
 
 /**
@@ -337,16 +358,6 @@ interface WriteOptions {
      */
     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
  *
@@ -360,4 +371,124 @@ declare function read(data: Uint8Array): ParseResult;
  */
 declare function write(data: Uint8Array, metadata: ParseResult, options?: WriteOptions): WriteResult;
 
-export { type CharacterPrompt, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteOptions, type WriteResult, read, write };
+/**
+ * WebUI (A1111) format writer for sd-metadata
+ *
+ * Converts any GenerationMetadata to SD WebUI (A1111) plain text format
+ * and writes it to PNG, JPEG, or WebP images.
+ */
+
+/**
+ * Write metadata to an image in SD WebUI format
+ *
+ * Converts the provided GenerationMetadata to SD WebUI (A1111) plain text
+ * format and embeds it into the image. This allows you to:
+ * - Create custom metadata from scratch
+ * - Modify existing metadata
+ * - Convert metadata from any tool to SD WebUI-compatible format
+ *
+ * The metadata is stored differently based on image format:
+ * - PNG: `parameters` tEXt/iTXt chunk (encoding auto-selected based on content)
+ * - JPEG/WebP: Exif UserComment field
+ *
+ * @param data - Target image file data (PNG, JPEG, or WebP)
+ * @param metadata - Generation metadata to embed
+ * @returns New image data with embedded metadata, or error
+ *
+ * @example
+ * ```typescript
+ * import { writeAsWebUI } from '@enslo/sd-metadata';
+ *
+ * // Create custom metadata
+ * const metadata = {
+ *   software: 'sd-webui',
+ *   prompt: 'masterpiece, 1girl',
+ *   negativePrompt: 'lowres, bad quality',
+ *   width: 512,
+ *   height: 768,
+ *   sampling: { steps: 20, sampler: 'Euler a', cfg: 7, seed: 12345 },
+ *   model: { name: 'model.safetensors' },
+ * };
+ *
+ * // Embed into image
+ * const result = writeAsWebUI(imageData, metadata);
+ * if (result.ok) {
+ *   writeFileSync('output.png', result.value);
+ * }
+ * ```
+ */
+declare function writeAsWebUI(data: Uint8Array, metadata: GenerationMetadata): WriteResult;
+
+/**
+ * A1111-format metadata serialization utilities
+ *
+ * Converts GenerationMetadata to A1111 (SD WebUI) plain text format.
+ */
+
+/**
+ * Format metadata as SD WebUI (A1111) plain text
+ *
+ * Converts GenerationMetadata to human-readable text in the SD WebUI format.
+ * This provides a standard, tool-agnostic way to display generation metadata
+ * without needing to manually read individual properties.
+ *
+ * The output format follows the A1111/SD WebUI convention:
+ * ```
+ * positive prompt
+ * [character prompts for NovelAI]
+ * Negative prompt: negative prompt
+ * Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, ...
+ * ```
+ *
+ * @param metadata - Generation metadata from any tool
+ * @returns Human-readable text in SD WebUI format
+ *
+ * @example
+ * ```typescript
+ * import { read, formatAsWebUI } from '@enslo/sd-metadata';
+ *
+ * const result = read(imageData);
+ * if (result.status === 'success') {
+ *   const text = formatAsWebUI(result.metadata);
+ *   console.log(text);
+ *   // Output:
+ *   // masterpiece, 1girl
+ *   // Negative prompt: low quality, bad anatomy
+ *   // Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, Model: model.safetensors
+ * }
+ * ```
+ */
+declare function formatAsWebUI(metadata: GenerationMetadata): string;
+
+/**
+ * Raw metadata serialization utilities
+ *
+ * Formats RawMetadata as human-readable plain text.
+ */
+
+/**
+ * Format raw metadata as plain text
+ *
+ * Extracts text content from RawMetadata and returns it as a simple string.
+ * Multiple entries are separated by double newlines.
+ *
+ * This is useful for displaying unrecognized metadata to end users
+ * without needing to manually iterate over chunks or segments.
+ *
+ * @param raw - Raw metadata from ParseResult
+ * @returns Plain text content from the metadata
+ *
+ * @example
+ * ```typescript
+ * import { read, formatRaw } from '@enslo/sd-metadata';
+ *
+ * const result = read(imageData);
+ * if (result.status === 'unrecognized') {
+ *   console.log(formatRaw(result.raw));
+ *   // Output: the raw text content without prefixes
+ * }
+ * ```
+ */
+declare function formatRaw(raw: RawMetadata): string;
+
+export { type CharacterPrompt, type GenerationMetadata, type HiresSettings, type ITXtChunk, type MetadataSegment, type MetadataSegmentSource, type ModelSettings, type ParseResult, type PngTextChunk, type RawMetadata, type SamplingSettings, type TExtChunk, type UpscaleSettings, type WriteOptions, type WriteResult, formatAsWebUI, formatRaw, read, write, writeAsWebUI };