@enslo/sd-metadata 1.8.1 → 2.0.1

package/README.ja.md

@@ -11,7 +11,7 @@ AI生成画像に埋め込まれたメタデータを読み書きするための
 ## 特徴
 
 - **マルチフォーマット対応**: PNG (tEXt / iTXt)、JPEG (COM / Exif)、WebP (Exif)
-- **統一API**: シンプルな `read()` と `write()` 関数で全フォーマットに対応
+- **シンプルAPI**: `read()`、`write()`、`embed()`、`stringify()` — 4つの関数で全ユースケースをカバー
 - **TypeScriptネイティブ**: TypeScriptで書かれており、型定義を完全同梱
 - **ゼロ依存**: Node.jsとブラウザで外部依存なしで動作
 - **フォーマット変換**: PNG、JPEG、WebP間でメタデータをシームレスに変換
@@ -29,17 +29,22 @@ npm install @enslo/sd-metadata
 | ------ | :---: | :----: | :----: |
 | [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) | ✅ | ✅ | ✅ |
+| [Stable Diffusion WebUI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) | ✅ | ✅ | ✅ |
+| [Forge](https://github.com/lllyasviel/stable-diffusion-webui-forge) | ✅ | ✅ | ✅ |
+| [Forge Classic](https://github.com/Haoming02/sd-webui-forge-classic/tree/classic) | ✅ | ✅ | ✅ |
+| [Forge Neo](https://github.com/Haoming02/sd-webui-forge-classic/tree/neo) | ✅ | ✅ | ✅ |
+| [reForge](https://github.com/Panchovix/stable-diffusion-webui-reForge) | ✅ | ✅ | ✅ |
+| [EasyReforge](https://github.com/Zuntan03/EasyReforge) | ✅ | ✅ | ✅ |
+| [SD.Next](https://github.com/vladmandic/automatic) | ✅ | ✅ | ✅ |
 | [InvokeAI](https://github.com/invoke-ai/InvokeAI) | ✅ | 🔄️ | 🔄️ |
-| [SwarmUI](https://github.com/Stability-AI/StableSwarmUI) * | ✅ | ✅ | ✅ |
+| [SwarmUI](https://github.com/mcmonkeyprojects/SwarmUI) * | ✅ | ✅ | ✅ |
 | [Civitai](https://civitai.com/) | ⚠️ | ✅ | ⚠️ |
 | [TensorArt](https://tensor.art/) | ✅ | 🔄️ | 🔄️ |
 | [Stability Matrix](https://github.com/LykosAI/StabilityMatrix) | ✅ | 🔄️ | 🔄️ |
 | [HuggingFace Space](https://huggingface.co/spaces) | ✅ | 🔄️ | 🔄️ |
+| [Fooocus](https://github.com/lllyasviel/Fooocus) | ⚠️ | ⚠️ | ⚠️ |
 | [Ruined Fooocus](https://github.com/runew0lf/RuinedFooocus) | ✅ | 🔄️ | 🔄️ |
 | [Easy Diffusion](https://github.com/easydiffusion/easydiffusion) | ⚠️ | ⚠️ | ⚠️ |
-| [Fooocus](https://github.com/lllyasviel/Fooocus) | ⚠️ | ⚠️ | ⚠️ |
 
 **凡例:**
 
@@ -90,10 +95,9 @@ const { read } = require('@enslo/sd-metadata');
 ### Node.jsでの使用
 
 ```typescript
-import { read, write } from '@enslo/sd-metadata';
-import { readFileSync, writeFileSync } from 'fs';
+import { read, stringify } from '@enslo/sd-metadata';
+import { readFileSync } from 'fs';
 
-// サポートされている任意のフォーマットからメタデータを読み込み
 const imageData = readFileSync('image.png');
 const result = read(imageData);
 
@@ -103,24 +107,30 @@ if (result.status === 'success') {
   console.log('Model:', result.metadata.model?.name);
   console.log('Size:', result.metadata.width, 'x', result.metadata.height);
 }
+
+// 読みやすいテキストにフォーマット（任意のstatusで動作）
+const text = stringify(result);
+if (text) {
+  console.log(text);
+}
 ```
 
 ### ブラウザでの使用
 
 ```typescript
-import { read } from '@enslo/sd-metadata';
+import { read, softwareLabels } from '@enslo/sd-metadata';
 
 // ファイル入力を処理
 const fileInput = document.querySelector('input[type="file"]');
 fileInput.addEventListener('change', async (e) => {
   const file = e.target.files[0];
   if (!file) return;
-  
+
   const arrayBuffer = await file.arrayBuffer();
   const result = read(arrayBuffer);
-  
+
   if (result.status === 'success') {
-    document.getElementById('tool').textContent = result.metadata.software;
+    document.getElementById('tool').textContent = softwareLabels[result.metadata.software];
     document.getElementById('prompt').textContent = result.metadata.prompt;
     document.getElementById('model').textContent = result.metadata.model?.name || 'N/A';
   }
@@ -149,7 +159,7 @@ if (result.status === 'success') {
 > 本番環境では `@latest` の代わりに特定のバージョンを指定してください：
 >
 > ```text
-> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@1.8.1/dist/index.js
+> https://cdn.jsdelivr.net/npm/@enslo/sd-metadata@2.0.1/dist/index.js
 > ```
 
 ### 応用例
@@ -180,8 +190,7 @@ if (parseResult.status === 'success') {
 }
 ```
 
-> [!TIP]
-> このライブラリはメタデータの読み書きのみを扱います。実際の画像フォーマット変換（ピクセルのデコード/エンコード）には、[sharp](https://www.npmjs.com/package/sharp)、[jimp](https://www.npmjs.com/package/jimp)、ブラウザCanvas APIなどの画像処理ライブラリを使用してください。
+> **Tip:** このライブラリはメタデータの読み書きのみを扱います。実際の画像フォーマット変換（ピクセルのデコード/エンコード）には、[sharp](https://www.npmjs.com/package/sharp)、[jimp](https://www.npmjs.com/package/jimp)、ブラウザCanvas APIなどの画像処理ライブラリを使用してください。
 
 </details>
 
@@ -264,16 +273,14 @@ if (result.ok) {
 </details>
 
 <details>
-<summary>WebUIフォーマットでメタデータを書き込む</summary>
+<summary>カスタムメタデータの埋め込み</summary>
 
-SD WebUI (A1111) フォーマットでカスタムメタデータを作成して埋め込み：
+A1111フォーマットでカスタムメタデータを作成して埋め込み：
 
 ```typescript
-import { writeAsWebUI } from '@enslo/sd-metadata';
+import { embed } from '@enslo/sd-metadata';
 
-// カスタムメタデータをゼロから作成
 const metadata = {
-  software: 'sd-webui',
   prompt: 'masterpiece, best quality, 1girl',
   negativePrompt: 'lowres, bad quality',
   width: 512,
@@ -288,53 +295,76 @@ const metadata = {
 };
 
 // 任意の画像フォーマット（PNG、JPEG、WebP）に書き込み
-const result = writeAsWebUI(imageData, metadata);
+const result = embed(imageData, metadata);
 if (result.ok) {
   writeFileSync('output.png', result.value);
 }
 ```
 
-> [!TIP]
-> `writeAsWebUI` は以下の場合に特に便利です：
->
-> - プログラムで生成した画像に生成パラメータを埋め込みたい場合
-> - ツール固有フォーマットからWebUI互換フォーマットにメタデータを変換する場合
-> - WebUIで読み取り可能なメタデータを出力するツールを構築する場合
+`extras` で設定行に任意のキーバリューを追加できます：
+
+```typescript
+const result = embed(imageData, {
+  ...metadata,
+  extras: {
+    Version: 'v1.10.0',
+    'Lora hashes': 'abc123',
+  },
+});
+```
+
+> **Tip:** extras のキーが構造化フィールド（例：`Steps`）と一致する場合、extras の値が元の位置で構造化フィールドを上書きします。新しいキーは末尾に追加されます。
+
+`EmbedMetadata` はすべての `GenerationMetadata` バリアントのサブセットなので、パース結果のメタデータをそのまま渡せます — `characterPrompts` を持つ NovelAI も含めて：
+
+```typescript
+import { read, embed } from '@enslo/sd-metadata';
+
+const result = read(novelaiPng);
+if (result.status === 'success') {
+  // NovelAI（や他のツール）のメタデータをそのまま利用可能
+  const output = embed(blankJpeg, result.metadata);
+}
+```
 
 </details>
 
 <details>
 <summary>表示用にメタデータをフォーマット</summary>
 
-**どのツールのメタデータであっても**、統一されたWebUIフォーマットのテキストに変換できます。ツール間の差異（NovelAI、ComfyUI、Forgeなど）を吸収し、一貫したテキスト形式に正規化します：
+`ParseResult` を読みやすい文字列に変換します。ステータスに応じて最適な表現を自動選択します：
 
 ```typescript
-import { read, formatAsWebUI } from '@enslo/sd-metadata';
+import { read, stringify } from '@enslo/sd-metadata';
 
 const result = read(imageData);
-if (result.status === 'success') {
-  // どのツールでもOK: NovelAI, ComfyUI, Forge, InvokeAI, etc.
-  const text = formatAsWebUI(result.metadata);
+const text = stringify(result);
+if (text) {
   console.log(text);
-  
-  // 常に統一されたWebUIフォーマットで出力:
+
+  // 'success' の場合: WebUIフォーマットで出力:
   // masterpiece, best quality, 1girl
   // Negative prompt: lowres, bad quality
   // Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, Model: model.safetensors
+  //
+  // 'unrecognized' の場合: 生のメタデータテキストを出力
+  // 'empty' / 'invalid' の場合: 空文字列を返す
 }
 ```
 
-> [!NOTE]
-> どのツールで生成された画像であっても、`formatAsWebUI` は共通の生成パラメータを抽出し、標準化された形式に整形します。ツール固有のフォーマットを意識することなく、ユーザーにメタデータを表示するのに最適です。
-
 </details>
 
 ## APIリファレンス
 
-### `read(input: Uint8Array | ArrayBuffer): ParseResult`
+### `read(input: Uint8Array | ArrayBuffer, options?: ReadOptions): ParseResult`
 
 画像ファイルからメタデータを読み込み、パースします。
 
+**パラメータ:**
+
+- `input` - 画像ファイルデータ（PNG、JPEG、またはWebP）
+- `options` - オプションの読み込み設定（詳細は[型ドキュメント](./docs/types.ja.md)を参照）
+
 **戻り値:**
 
 - `{ status: 'success', metadata, raw }` - パース成功
@@ -366,16 +396,14 @@ if (result.status === 'success') {
   - `'conversionFailed'`: メタデータ変換に失敗（例：互換性のないフォーマット）
   - `'writeFailed'`: 画像へのメタデータ埋め込みに失敗
 
-### `writeAsWebUI(input: Uint8Array | ArrayBuffer, metadata: GenerationMetadata): WriteResult`
+### `embed(input: Uint8Array | ArrayBuffer, metadata: EmbedMetadata | GenerationMetadata): WriteResult`
 
-SD WebUI (A1111) フォーマットで画像にメタデータを書き込みます。
+SD WebUI (A1111) フォーマットでカスタムメタデータを画像に埋め込みます。
 
 **パラメータ:**
 
 - `input` - ターゲット画像ファイルデータ（PNG、JPEG、またはWebP）
-- `metadata` - 埋め込む生成メタデータ
-  - 任意のツールからでも、カスタム作成でも可能
-  - 自動的にWebUIフォーマットに変換される
+- `metadata` - 埋め込む `EmbedMetadata` または `GenerationMetadata`（`extras` で任意のキーバリューを追加可能）
 
 **戻り値:**
 
@@ -390,65 +418,37 @@ SD WebUI (A1111) フォーマットで画像にメタデータを書き込みま
 - 他のツールからWebUI互換フォーマットにメタデータを変換
 - WebUIで読み取り可能なメタデータを出力するアプリケーションの構築
 
-### `formatAsWebUI(metadata: GenerationMetadata): string`
+### `stringify(input: ParseResult | EmbedMetadata | GenerationMetadata): string`
 
-メタデータをSD WebUI (A1111) フォーマットのテキストにフォーマットします。
+メタデータを読みやすい文字列に変換します。`ParseResult`、`EmbedMetadata`、`GenerationMetadata` のいずれも受け付けます。
 
 **パラメータ:**
 
-- `metadata` - 任意のツールからの生成メタデータ
+- `input` - `ParseResult`、`EmbedMetadata`、または `GenerationMetadata`
 
 **戻り値:**
 
-- WebUIフォーマットの文字列（プレーンテキスト）
-
-**出力フォーマット:**
-
-```text
-positive prompt
-[NovelAIのキャラクタープロンプト]
-Negative prompt: negative prompt
-Steps: 20, Sampler: Euler a, CFG scale: 7, Seed: 12345, Size: 512x768, ...
-```
+- `ParseResult` の場合: `success` → WebUIフォーマット、`unrecognized` → 生テキスト、`empty`/`invalid` → 空文字列
+- `EmbedMetadata` / `GenerationMetadata` の場合: WebUIフォーマットのテキスト
 
 **ユースケース:**
 
-- ユーザーに一貫したフォーマットでメタデータを表示
-- 生成パラメータをテキストとしてコピー
-- 生成設定のログ出力やデバッグ
+- 画像ビューアやギャラリーでの生成パラメータ表示
+- メタデータをクリップボードに読みやすいテキストとしてコピー
+- パース結果のログ出力やデバッグ
+- `EmbedMetadata` の事前プレビュー（埋め込み前の確認用）
 
-### `formatRaw(raw: RawMetadata): string`
+### `softwareLabels: Record<GenerationSoftware, string>`
 
-生のメタデータをプレーンテキストとしてフォーマットします。
-
-**パラメータ:**
-
-- `raw` - `ParseResult` から得られた生のメタデータ（`result.raw`）
-
-**戻り値:**
-
-- メタデータのプレーンテキスト内容（複数エントリは空行で区切られる）
-
-**ユースケース:**
-
-- 認識できないメタデータをユーザーに表示
-- 生のメタデータ内容の素早い確認
-- パース失敗時のフォールバック表示
-
-**例:**
+`GenerationSoftware` の識別子から表示用の名前への読み取り専用マッピング。
 
 ```typescript
-import { read, formatAsWebUI, formatRaw } from '@enslo/sd-metadata';
+import { softwareLabels } 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;
+if (result.status === 'success') {
+  console.log(softwareLabels[result.metadata.software]);
+  // => "NovelAI", "ComfyUI", "Stable Diffusion WebUI", etc.
 }
 ```
 
@@ -468,22 +468,26 @@ type ParseResult =
   | { status: 'invalid'; message?: string };
 ```
 
-### `GenerationMetadata`
+### `BaseMetadata`
 
-`read()` 関数が返す統一されたメタデータ構造。`software` フィールドで区別される3つのメタデータ型のユニオン型です。
+全メタデータ型で共有される共通フィールド。このインターフェースは `EmbedMetadata` の基盤でもあります。
 
-**共通フィールド（全タイプで利用可能）:**
+```typescript
+interface BaseMetadata {
+  prompt: string;
+  negativePrompt: string;
+  width: number;
+  height: number;
+  model?: ModelSettings;
+  sampling?: SamplingSettings;
+  hires?: HiresSettings;
+  upscale?: UpscaleSettings;
+}
+```
 
-全てのメタデータ型にはこれらの基本フィールドが含まれます：
+### `GenerationMetadata`
 
-- `prompt: string` - ポジティブプロンプトテキスト
-- `negativePrompt: string` - ネガティブプロンプトテキスト
-- `width: number` - 画像の幅（ピクセル）
-- `height: number` - 画像の高さ（ピクセル）
-- `model?: ModelSettings` - モデル情報（name、hash、VAE）
-- `sampling?: SamplingSettings` - サンプリングパラメータ（seed、steps、CFG、sampler、scheduler、clipSkip）
-- `hires?: HiresSettings` - Hires.fix設定（適用されている場合）
-- `upscale?: UpscaleSettings` - アップスケール設定（適用されている場合）
+`read()` 関数が返す統一されたメタデータ構造。`software` フィールドで区別される3つのメタデータ型のユニオン型です。全タイプが `BaseMetadata` を拡張しています。
 
 **メタデータ型のバリアント:**
 
@@ -498,7 +502,7 @@ type ParseResult =
   - `nodes: ComfyNodeGraph`（comfyui/tensorart/stability-matrixでは必須）
   - `nodes?: ComfyNodeGraph`（swarmuiではオプション - PNGフォーマットのみ）
 
-- **`StandardMetadata`** (`software: 'sd-webui' | 'forge' | 'invokeai' | 'civitai' | ...`)  
+- **`StandardMetadata`** (`software: 'sd-webui' | 'forge' | 'forge-classic' | 'reforge' | 'invokeai' | ...`)
   ツール固有の拡張なしのベースラインメタデータ。ほとんどのSD WebUIベースのツールで使用。
 
 **型定義:**
@@ -545,6 +549,29 @@ if (result.status === 'success') {
 
 各メタデータ型の詳細なインターフェース定義については[型ドキュメント](./docs/types.ja.md)を参照してください。
 
+### `GenerationSoftware`
+
+サポートされている全ソフトウェア識別子の文字列リテラルユニオン型。`softwareLabels` のキー型として使用します。
+
+```typescript
+type GenerationSoftware =
+  | 'novelai' | 'comfyui' | 'swarmui' | 'tensorart' | 'stability-matrix'
+  | 'sd-webui' | 'forge' | 'forge-classic' | 'forge-neo' 
+  | 'reforge'| 'easy-reforge' | 'sd-next' | 'civitai' | 'hf-space'
+  | 'invokeai' | 'easydiffusion' | 'fooocus' | 'ruined-fooocus';
+```
+
+### `EmbedMetadata`
+
+`embed()` と `stringify()` で使用するユーザー作成カスタムメタデータ型。`GenerationMetadata` が既知のAIツールからのパース結果を表すのに対し、`EmbedMetadata` はユーザーが独自にメタデータを組み立てるための型です。`BaseMetadata` にオプションのキャラクタープロンプトと設定行への任意キーバリュー（`extras`）を追加。
+
+```typescript
+type EmbedMetadata = BaseMetadata &
+  Pick<NovelAIMetadata, 'characterPrompts'> & {
+    extras?: Record<string, string | number>;
+  };
+```
+
 ### `RawMetadata`
 
 ラウンドトリップ変換のために元のメタデータ構造を保持します。
@@ -556,42 +583,28 @@ type RawMetadata =
   | { format: 'webp'; segments: MetadataSegment[] };
 ```
 
-> [!TIP]
-> TypeScriptユーザー向け：全ての型はエクスポートされており、インポートして使用できます。
->
-> ```typescript
-> import type { 
->   ParseResult, 
->   GenerationMetadata, 
->   ModelSettings, 
->   SamplingSettings 
-> } from '@enslo/sd-metadata';
-> ```
->
-> IDEのIntelliSenseを使用して自動補完とインラインドキュメントを活用してください。
-
 `ModelSettings`、`SamplingSettings`、フォーマット固有の型を含む全てのエクスポート型の詳細なドキュメントについては、[型ドキュメント](./docs/types.ja.md)を参照してください。
 
 ## 開発
 
 ```bash
 # 依存関係をインストール
-npm install
+pnpm install
 
 # テストを実行
-npm test
-
-# ウォッチモード
-npm run test:watch
-
-# テストカバレッジ
-npm run test:coverage
+pnpm test
 
 # ビルド
-npm run build
+pnpm build
 
 # リント
-npm run lint
+pnpm lint
+
+# 型チェック
+pnpm typecheck
+
+# デモサイト起動
+pnpm demo
 ```
 
 ## ライセンス