@enslo/sd-metadata 1.1.0 → 1.2.0

package/README.md

@@ -151,7 +151,7 @@ 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.0.2/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.2.0/dist/index.js
 > ```
 
 ### Format Conversion
@@ -247,6 +247,66 @@ if (result.ok) {
 }
 ```
 
+### Writing Metadata in WebUI Format
+
+Create and embed custom metadata in SD WebUI (A1111) format:
+
+```typescript
+import { writeAsWebUI } from '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
+
+### Formatting Metadata for Display
+
+Convert metadata to human-readable text in WebUI format:
+
+```typescript
+import { read, formatAsWebUI } from 'sd-metadata';
+
+const result = read(imageData);
+if (result.status === 'success') {
+  // Convert to WebUI format text
+  const text = formatAsWebUI(result.metadata);
+  console.log(text);
+  
+  // Output example:
+  // 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]
+> `formatAsWebUI` provides a tool-agnostic standard format for displaying generation metadata. It works with metadata from any supported tool (NovelAI, ComfyUI, etc.) and formats it consistently.
+
 ## API Reference
 
 ### `read(data: Uint8Array): ParseResult`
@@ -283,6 +343,56 @@ Writes metadata to an image file.
 - `{ ok: false, error: { type: string, message?: string } }` - Failed
   - `type`: `'unsupportedFormat'`, `'conversionFailed'`, or `'writeFailed'`
 
+### `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'` or `'writeFailed'`
+
+**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
+
 ## Type Reference
 
 This section provides an overview of the main types. For complete type definitions, see [Type Documentation](./docs/types.md).

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,93 @@ 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 '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 '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;
+
+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, read, write, writeAsWebUI };