ss-tools-duck 1.0.0

package/README.md

@@ -0,0 +1,317 @@
+# SS_tools Duck — Node.js 隐写工具库
+
+将任意数据（文本、图片、视频、文件）隐藏在一张可爱的鸭子图片中，或从鸭子图中还原数据。
+
+完全对应 ComfyUI 插件 [SS_tools](../) 的 Python 实现，编码格式互相兼容。
+
+---
+
+## 目录
+
+- [快速开始](#快速开始)
+- [安装依赖](#安装依赖)
+- [命令行 CLI](#命令行-cli)
+- [编程 API](#编程-api)
+  - [encode — 编码](#encode--编码)
+  - [decode — 解码](#decode--解码)
+  - [video — 视频合成](#video--视频合成需-ffmpeg)
+  - [底层工具](#底层工具)
+- [与 Python 版互通](#与-python-版互通)
+- [参数说明](#参数说明)
+
+---
+
+## 快速开始
+
+```bash
+# 隐藏文字
+node duck-cli.js encode text secret.png --text="你好，世界" --password=mypass
+
+# 还原文字
+node duck-cli.js decode secret.png --password=mypass
+```
+
+---
+
+## 安装依赖
+
+```bash
+cd nodejs
+npm install
+```
+
+**依赖项：**
+
+| 包 | 用途 |
+|---|---|
+| `sharp` | PNG 像素读写 |
+| `fluent-ffmpeg` | 视频合成 / 解帧（需系统 ffmpeg） |
+| `glob` | CLI frames 命令路径展开 |
+
+> **视频功能**需要在系统中安装 [ffmpeg](https://ffmpeg.org/download.html) 并加入 `PATH`。
+> 运行 `node duck-cli.js check-ffmpeg` 验证是否可用。
+
+---
+
+## 命令行 CLI
+
+### encode text — 隐藏文本
+
+```bash
+node duck-cli.js encode text <输出.png> --text="内容" [--password=密码] [--title=标题] [--compress=2|6|8]
+
+# 从文件读取文本
+node duck-cli.js encode text out.png --text-file=secret.txt --password=abc
+```
+
+### encode image — 隐藏图片
+
+```bash
+node duck-cli.js encode image <输出.png> --input=<图片路径> [--password=密码] [--title=标题] [--compress=2|6|8]
+```
+
+### encode bytes — 隐藏任意文件
+
+```bash
+node duck-cli.js encode bytes <输出.png> --input=<文件路径> [--ext=扩展名] [--password=密码]
+
+# 隐藏 PDF
+node duck-cli.js encode bytes out.png --input=report.pdf
+```
+
+### encode video — 隐藏 MP4
+
+```bash
+node duck-cli.js encode video <输出.png> --input=<视频.mp4> [--password=密码] [--title=标题]
+```
+
+### encode frames — 帧序列 → 视频 → 鸭子图（需 ffmpeg）
+
+```bash
+node duck-cli.js encode frames <输出.png> --frames="./frames/*.png" --fps=30 [--audio=bgm.mp3]
+```
+
+### decode — 解码还原
+
+```bash
+node duck-cli.js decode <输入.png> [--password=密码] [--output=输出目录] [--json]
+
+# --json 只输出元数据，不写文件
+node duck-cli.js decode secret.png --password=abc --json
+```
+
+输出示例：
+```json
+{
+  "ext": "txt",
+  "filePath": "/path/to/duck_recovered.txt",
+  "text": "你好，世界",
+  "dataBytes": 15
+}
+```
+
+### check-ffmpeg — 检查 ffmpeg
+
+```bash
+node duck-cli.js check-ffmpeg
+```
+
+---
+
+## 编程 API
+
+```js
+const duck = require('./index');  // 或 require('./index.js')
+```
+
+### encode — 编码
+
+#### `encodeText(opts)` → `Promise<{ imageBuffer, filePath? }>`
+
+```js
+const { imageBuffer } = await duck.encodeText({
+  text:       '要隐藏的文字',
+  password:   'my_password',   // 省略 = 不加密
+  title:      '鸭子标题',      // 显示在图片右下角
+  compress:   2,               // 2 / 6 / 8，默认 2
+  outputPath: 'out.png',       // 省略 = 不写文件，只返回 Buffer
+});
+```
+
+#### `encodeImage(opts)` → `Promise<EncodeResult>`
+
+```js
+const imageData = fs.readFileSync('photo.jpg');
+const { filePath } = await duck.encodeImage({
+  image:      imageData,
+  compress:   6,
+  outputPath: 'duck_out.png',
+});
+```
+
+#### `encodeBytes(opts)` → `Promise<EncodeResult>`
+
+```js
+const pdfBytes = fs.readFileSync('report.pdf');
+await duck.encodeBytes({
+  rawBytes:   pdfBytes,
+  ext:        'pdf',
+  outputPath: 'duck_pdf.png',
+});
+```
+
+#### `encodeMp4(opts)` → `Promise<EncodeResult>`
+
+```js
+const mp4Buffer = fs.readFileSync('video.mp4');
+await duck.encodeMp4({
+  mp4Input:   mp4Buffer,          // Buffer 或文件路径字符串
+  password:   'secret',
+  outputPath: 'duck_video.png',
+});
+```
+
+#### `encodeImageSequence(opts)` → `Promise<{ imageBuffers, filePaths? }>`
+
+```js
+const frames = [buf1, buf2, buf3];  // 每帧一个 PNG/JPEG Buffer
+const { filePaths } = await duck.encodeImageSequence({
+  images:    frames,
+  outputDir: './output',
+});
+// → output/duck_000.png, duck_001.png, duck_002.png
+```
+
+---
+
+### decode — 解码
+
+#### `decodeDuckImage(opts)` → `Promise<DecodeResult>`
+
+```js
+const result = await duck.decodeDuckImage({
+  duckImage: fs.readFileSync('secret.png'),  // Buffer 或文件路径
+  password:  'my_password',
+  outputDir: './recovered',
+});
+
+console.log(result.ext);          // "txt" | "png" | "mp4" | "pdf" …
+console.log(result.text);         // 若是文本则已解码为字符串
+console.log(result.imageBuffer);  // 若是图片
+console.log(result.mp4Buffer);    // 若是视频
+console.log(result.filePath);     // 还原文件的路径
+```
+
+#### 便捷接口
+
+```js
+// 从文件路径
+const result = await duck.decodeFromFile('secret.png', 'password', './out');
+
+// 从 Buffer
+const result = await duck.decodeFromBuffer(pngBuffer, 'password', './out');
+```
+
+---
+
+### video — 视频合成（需 ffmpeg）
+
+#### `imagesToMp4(opts)` → `Promise<Buffer>`
+
+```js
+const frames = pngBuffers;  // PNG Buffer 数组
+const mp4Buf = await duck.imagesToMp4({
+  frames,
+  fps:        30,
+  audioPath:  'bgm.mp3',     // 可选
+  outputPath: 'output.mp4',  // 可选
+});
+```
+
+#### `mp4ToFrames(opts)` → `Promise<{ frames, fps }>`
+
+```js
+const { frames, fps } = await duck.mp4ToFrames({
+  mp4Input: fs.readFileSync('video.mp4'),
+  fps:      null,  // null = 原始帧率
+});
+```
+
+#### `encodeVideoFrames(opts)` → `Promise<EncodeResult>`
+
+帧序列一步编码为鸭子图：
+
+```js
+await duck.encodeVideoFrames({
+  frames:     pngBuffers,
+  fps:        24,
+  audioPath:  'bgm.wav',
+  password:   'secret',
+  outputPath: 'duck_video.png',
+});
+```
+
+---
+
+### 底层工具
+
+```js
+const {
+  buildFileHeader,
+  parseHeader,
+  exportDuckPayload,
+  embedPayloadLSB,
+  extractPayloadWithK,
+  bytesToBinaryImage,
+  binaryImageToBytes,
+  buildDuckImageBuffer,
+  requiredCanvasSize,
+} = require('./duck_payload_exporter');
+```
+
+详见 [index.d.ts](./index.d.ts) 获取完整类型定义。
+
+---
+
+## 与 Python 版互通
+
+Node.js 和 Python 版本使用**完全相同的二进制格式**，可以互相编解码：
+
+| Python（ComfyUI 节点）编码 → Node.js 解码 | ✅ 支持 |
+|---|---|
+| Node.js 编码 → Python（ComfyUI 节点）解码 | ✅ 支持 |
+
+对齐细节：
+
+| 常量 / 算法 | 值 |
+|---|---|
+| 水印跳过区域 | 左上角 `40% 宽 × 8% 高` |
+| bit 顺序 | 大端（高位优先）—— 对应 `np.unpackbits(bitorder="big")` |
+| 文件头格式 | `[has_pwd:1][pwdHash:32][salt:16][extLen:1][ext][dataLen:4 BE][data]` |
+| 长度前缀 | 4 字节大端整数，存储在图像 LSB 前 |
+| XOR 密钥流 | `SHA-256(password + counter)` 迭代生成 |
+
+---
+
+## 参数说明
+
+### `compress` 参数
+
+| 值 | 每通道隐藏 bit 数 | 视觉失真 | 最大容量（512×512 图） |
+|---|---|---|---|
+| `2` | 2 bit | 极低，肉眼不可见 | ~65 KB |
+| `6` | 6 bit | 低 | ~196 KB |
+| `8` | 8 bit | 中（颜色偏差明显） | ~262 KB |
+
+### `password` 参数
+
+- 空字符串 `""` 或省略：**不加密**，任何人可解码
+- 非空字符串：使用 SHA-256 + 随机 salt 的 XOR 流加密
+
+### 文件大小限制
+
+实际可隐藏的数据量取决于鸭子图的分辨率和 `compress` 值：
+
+$$容量(bytes) = \frac{(宽 × 高 - 水印区像素数) × 3 × k}{8} - 文件头长度$$
+
+其中 $k$ = compress 值（2/6/8），水印区为左上 40%×8% 区域。

package/duck-cli.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * duck-cli.js — SS_tools Duck 隐写命令行工具
+ *
+ * 用法：
+ *   node duck-cli.js encode text   [选项] <输出路径>
+ *   node duck-cli.js encode image  [选项] <输出路径>
+ *   node duck-cli.js encode bytes  [选项] <输出路径>
+ *   node duck-cli.js encode video  [选项] <输出路径>    （需系统 ffmpeg）
+ *   node duck-cli.js encode frames [选项] <输出路径>    （需系统 ffmpeg）
+ *   node duck-cli.js decode        [选项] <输入路径>
+ *   node duck-cli.js check-ffmpeg
+ *   node duck-cli.js help
+ *
+ * 完整帮助：node duck-cli.js help
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── 彩色输出 ─────────────────────────────────────────────────────────────────
+
+const C = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  red:    '\x1b[31m',
+  cyan:   '\x1b[36m',
+  gray:   '\x1b[90m',
+};
+
+function ok(msg)   { console.log(`${C.green}✅ ${msg}${C.reset}`); }
+function err(msg)  { console.error(`${C.red}❌ ${msg}${C.reset}`); }
+function info(msg) { console.log(`${C.cyan}ℹ  ${msg}${C.reset}`); }
+function warn(msg) { console.warn(`${C.yellow}⚠  ${msg}${C.reset}`); }
+
+// ─── 参数解析 ─────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        // 下一个 token 若不以 -- 开头则是值，否则是布尔
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+          flags[a.slice(2)] = next;
+          i++;
+        } else {
+          flags[a.slice(2)] = true;
+        }
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+
+  return { flags, positional };
+}
+
+// ─── 帮助文本 ─────────────────────────────────────────────────────────────────
+
+const HELP_TEXT = `
+${C.bold}SS_tools Duck 隐写 CLI${C.reset}
+
+${C.bold}用法${C.reset}
+  node duck-cli.js <命令> [子命令] [选项] [路径]
+
+${C.bold}命令${C.reset}
+
+  ${C.cyan}encode text${C.reset}  <输出.png>
+      将文本隐藏到鸭子图中
+      选项：
+        --text=<内容>         要隐藏的文本（与 --text-file 二选一）
+        --text-file=<路径>    从文件读取文本
+        --password=<密码>     加密密码（留空=不加密）
+        --title=<标题>        鸭子图标题
+        --compress=<2|6|8>    压缩比（默认：2）
+
+  ${C.cyan}encode image${C.reset}  <输出.png>
+      将图片隐藏到鸭子图中
+      选项：
+        --input=<路径>        输入图片路径（必填）
+        --password=<密码>
+        --title=<标题>
+        --compress=<2|6|8>
+
+  ${C.cyan}encode bytes${C.reset}  <输出.png>
+      将任意文件隐藏到鸭子图中
+      选项：
+        --input=<路径>        输入文件路径（必填）
+        --ext=<扩展名>        文件扩展名（如 pdf、zip；默认取输入文件扩展名）
+        --password=<密码>
+        --title=<标题>
+        --compress=<2|6|8>
+
+  ${C.cyan}encode video${C.reset}  <输出.png>
+      将 MP4 视频隐藏到鸭子图中（binpng 格式）
+      选项：
+        --input=<路径>        输入 MP4 文件路径（必填）
+        --password=<密码>
+        --title=<标题>
+        --compress=<2|6|8>
+
+  ${C.cyan}encode frames${C.reset}  <输出.png>
+      将图片帧序列合成为 MP4，再隐藏到鸭子图
+      需要系统安装 ffmpeg
+      选项：
+        --frames=<glob>       帧图片 glob（如 "frames/*.png"）
+        --fps=<帧率>          默认 24
+        --audio=<路径>        音频文件路径（可选）
+        --password=<密码>
+        --title=<标题>
+        --compress=<2|6|8>
+
+  ${C.cyan}decode${C.reset}  <输入.png>
+      从鸭子图中还原隐藏数据
+      选项：
+        --password=<密码>     加密密码
+        --output=<目录>       输出目录（默认：当前目录）
+        --json                只输出 JSON 元数据，不保存文件
+
+  ${C.cyan}check-ffmpeg${C.reset}
+      检查系统 ffmpeg 是否可用
+
+  ${C.cyan}help${C.reset}
+      显示本帮助
+
+${C.bold}示例${C.reset}
+
+  # 隐藏文本
+  node duck-cli.js encode text output.png --text="Hello 世界" --password=123
+
+  # 隐藏图片
+  node duck-cli.js encode image output.png --input=photo.jpg --compress=6
+
+  # 隐藏任意文件
+  node duck-cli.js encode bytes output.png --input=document.pdf
+
+  # 解码
+  node duck-cli.js decode output.png --password=123 --output=./result
+
+  # 合成视频并隐藏
+  node duck-cli.js encode frames output.png --frames="./frames/*.png" --fps=30
+
+${C.gray}注意：encode frames / encode video 需要系统安装 ffmpeg 并在 PATH 中可用${C.reset}
+`;
+
+// ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, positional } = parseArgs(argv);
+
+  const [cmd, sub] = positional;
+  const outputPath  = positional[2];
+
+  if (!cmd || cmd === 'help' || flags.help) {
+    console.log(HELP_TEXT);
+    return;
+  }
+
+  // ── check-ffmpeg ──────────────────────────────────────────────────────────
+  if (cmd === 'check-ffmpeg') {
+    const { checkFfmpegAvailable } = require('./duck_video');
+    const available = await checkFfmpegAvailable();
+    if (available) ok('ffmpeg 可用');
+    else err('ffmpeg 不可用，请安装后将其加入 PATH');
+    return;
+  }
+
+  // ── decode ────────────────────────────────────────────────────────────────
+  if (cmd === 'decode') {
+    const inputPath = positional[1];
+    if (!inputPath) { err('请提供输入文件路径'); process.exit(1); }
+    if (!fs.existsSync(inputPath)) { err(`文件不存在：${inputPath}`); process.exit(1); }
+
+    const { decodeFromFile } = require('./duck_decode');
+
+    const password  = flags.password || '';
+    const outputDir = flags.output   || process.cwd();
+
+    info(`正在解码：${inputPath} …`);
+    try {
+      const result = await decodeFromFile(inputPath, password, outputDir);
+
+      if (flags.json) {
+        const meta = {
+          ext:       result.ext,
+          filePath:  result.filePath  || null,
+          text:      result.text      || null,
+          dataBytes: result.data ? result.data.length : 0,
+        };
+        console.log(JSON.stringify(meta, null, 2));
+      } else {
+        ok(`解码成功（ext=${result.ext}）`);
+        if (result.text)     info(`文本内容：${result.text}`);
+        if (result.filePath) info(`文件已保存：${result.filePath}`);
+      }
+    } catch (e) {
+      err(`解码失败：${e.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // ── encode ────────────────────────────────────────────────────────────────
+  if (cmd === 'encode') {
+    if (!sub) { err('请指定编码子命令：text / image / bytes / video / frames'); process.exit(1); }
+    if (!outputPath) { err('请提供输出文件路径'); process.exit(1); }
+
+    const password = flags.password || '';
+    const title    = flags.title    || '';
+    const compress = parseInt(flags.compress || '2', 10);
+
+    // ── encode text ──────────────────────────────────────────────────────────
+    if (sub === 'text') {
+      let text = flags.text;
+      if (!text && flags['text-file']) {
+        if (!fs.existsSync(flags['text-file'])) { err(`文件不存在：${flags['text-file']}`); process.exit(1); }
+        text = fs.readFileSync(flags['text-file'], 'utf8');
+      }
+      if (!text) { err('请通过 --text 或 --text-file 提供文本'); process.exit(1); }
+
+      const { encodeText } = require('./duck_encode');
+      info('正在编码文本 …');
+      const { filePath } = await encodeText({ text, password, title, compress, outputPath });
+      ok(`已写出：${filePath}`);
+      return;
+    }
+
+    // ── encode image ─────────────────────────────────────────────────────────
+    if (sub === 'image') {
+      if (!flags.input) { err('请提供 --input'); process.exit(1); }
+      if (!fs.existsSync(flags.input)) { err(`文件不存在：${flags.input}`); process.exit(1); }
+
+      const { encodeImage } = require('./duck_encode');
+      const image = fs.readFileSync(flags.input);
+      info(`正在编码图片：${flags.input} …`);
+      const { filePath } = await encodeImage({ image, password, title, compress, outputPath });
+      ok(`已写出：${filePath}`);
+      return;
+    }
+
+    // ── encode bytes ─────────────────────────────────────────────────────────
+    if (sub === 'bytes') {
+      if (!flags.input) { err('请提供 --input'); process.exit(1); }
+      if (!fs.existsSync(flags.input)) { err(`文件不存在：${flags.input}`); process.exit(1); }
+
+      const { encodeBytes } = require('./duck_encode');
+      const rawBytes = fs.readFileSync(flags.input);
+      const ext      = flags.ext || path.extname(flags.input).replace('.', '') || 'bin';
+      info(`正在编码文件：${flags.input}（ext=${ext}）…`);
+      const { filePath } = await encodeBytes({ rawBytes, ext, password, title, compress, outputPath });
+      ok(`已写出：${filePath}`);
+      return;
+    }
+
+    // ── encode video ─────────────────────────────────────────────────────────
+    if (sub === 'video') {
+      if (!flags.input) { err('请提供 --input（MP4 文件路径）'); process.exit(1); }
+      if (!fs.existsSync(flags.input)) { err(`文件不存在：${flags.input}`); process.exit(1); }
+
+      const { encodeMp4 } = require('./duck_encode');
+      const mp4Input = fs.readFileSync(flags.input);
+      info(`正在编码视频：${flags.input} …`);
+      const { filePath } = await encodeMp4({ mp4Input, password, title, compress, outputPath });
+      ok(`已写出：${filePath}`);
+      return;
+    }
+
+    // ── encode frames ────────────────────────────────────────────────────────
+    if (sub === 'frames') {
+      const { glob } = await import('glob').catch(() => {
+        // Node 18 之前无内置 glob，尝试 fast-glob
+        return require('fast-glob').then ? require('fast-glob') : { glob: null };
+      });
+
+      // 展开 glob 路径
+      const frameGlob = flags.frames;
+      if (!frameGlob) { err('请提供 --frames="<glob>"'); process.exit(1); }
+
+      let framePaths;
+      try {
+        // 若系统 Node 18+，用内置 fs.glob 或 glob 包
+        const { globSync } = require('glob');
+        framePaths = globSync(frameGlob, { absolute: true }).sort();
+      } catch {
+        // fallback：直接当文件路径
+        framePaths = frameGlob.split(',').map(p => p.trim()).filter(Boolean);
+      }
+
+      if (framePaths.length === 0) { err(`没有匹配的帧文件：${frameGlob}`); process.exit(1); }
+      info(`找到 ${framePaths.length} 帧`);
+
+      const frames = framePaths.map(p => fs.readFileSync(p));
+      const fps    = parseFloat(flags.fps || '24');
+      const audio  = flags.audio || null;
+
+      const { checkFfmpegAvailable, encodeVideoFrames } = require('./duck_video');
+      if (!(await checkFfmpegAvailable())) {
+        err('ffmpeg 不可用，请安装后重试');
+        process.exit(1);
+      }
+
+      info(`正在合成视频（${fps}fps）并编码 …`);
+      const { filePath } = await encodeVideoFrames({ frames, fps, audioPath: audio, password, title, compress, outputPath });
+      ok(`已写出：${filePath}`);
+      return;
+    }
+
+    err(`未知子命令：${sub}，请使用 text / image / bytes / video / frames`);
+    process.exit(1);
+  }
+
+  err(`未知命令：${cmd}`);
+  console.log(`运行 ${C.cyan}node duck-cli.js help${C.reset} 查看帮助`);
+  process.exit(1);
+}
+
+main().catch(e => {
+  err(e.message || String(e));
+  process.exit(1);
+});