halfsize 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.1.4
+
+- Batch mode: `halfsize a.mp4 b.mp4 --to 10mb` compresses several files in a row
+- `--for discord|whatsapp|wechat|email|twitter` picks the platform's upload cap for you
+- `--no-audio` drops the audio track and spends the bits on video instead
+- Streams are mapped explicitly, so cover art and extra tracks cannot be picked by mistake
+- Mono audio stays mono instead of being silently upmixed to stereo
+
+## 0.1.3
+
+- Two-pass progress now spans both passes and shows `pass 1/2`
+- `--web --port <n>` to pick a port
+- Pass logs are cleaned up even when an encode fails
+
+## 0.1.2
+
+- npm release is live
+- CI badge in the README
+
+## 0.1.1
+
+- `--version` no longer falls through to the help screen
+- Force CFR so two-pass encodes of Matroska/VFR sources stay on target
+- Always emit MP4 from the CLI, even for MKV/AVI sources
+
+## 0.1.0
+
+- First release: exact target size, resolution ladder, two-pass H.264/H.265
+- SSIM sampling and VMAF measurement with a plain-language verdict
+- Local web app with drag and drop, platform presets, and a share card
+- `--json`, `--dry-run`, `--doctor`, and `--no-verify`

package/README.md

@@ -40,7 +40,7 @@ It computes the bitrate, picks the resolution that actually fits, encodes twice,
 the result with **SSIM** and **VMAF** so you know whether it still looks the same.
 
 ```
-  halfsize 0.1.0
+  halfsize 0.1.4
 
   source.mp4
   23.2 MB  8s  1920x1080  30.00 fps  h264
@@ -87,6 +87,12 @@ be downloaded, `halfsize` uses your system install instead.
 # compress to a size
 npx halfsize video.mp4 --to 25mb
 
+# or just name the app you are uploading to
+npx halfsize video.mp4 --for discord
+
+# several files in one go
+npx halfsize clip1.mp4 clip2.mp4 clip3.mp4 --to 10mb
+
 # smaller file, same quality budget
 npx halfsize video.mp4 --to 10mb --codec h265
 
@@ -123,6 +129,13 @@ machine**; nothing is sent anywhere.
 After each run you can download a **share card** (the image at the top of this README) with the
 real numbers on it.
 
+### Use it from an agent
+
+The repo ships a skill in [`skills/halfsize/SKILL.md`](skills/halfsize/SKILL.md). Drop that
+folder into your agent's skills directory (for Claude Code: `.claude/skills/halfsize/`) and the
+agent can turn "make this fit in 25 MB" into a compression plus a measured quality report,
+instead of guessing a bitrate.
+
 ## How it works
 
 1. **Probe.** Read duration, resolution, frame rate, audio bitrate, rotation, and HDR metadata.
@@ -155,10 +168,12 @@ or bitrate. It is not magic, but it is a much better answer than "trust me".
 halfsize <file> [options]
 
   --to <size>       Target size: 25mb, 700k, 1.5gb
+  --for <app>       Target cap for discord, whatsapp, wechat, email, twitter
   --crf <n>         Quality mode instead of size mode (18 best, 23 balanced, 28 small)
   --codec <name>    h264 (default, maximum compatibility) or h265 (about 30% smaller)
   --preset <name>   ultrafast .. veryslow (default: medium)
   --out <file>      Output path
+  --no-audio        Drop the audio track
   --no-verify       Skip SSIM/VMAF
   --no-downscale    Never reduce resolution (the target may then be missed)
   --json            Machine-readable result
@@ -172,6 +187,9 @@ halfsize <file> [options]
 
 Sizes accept `b`, `k`/`kb`, `m`/`mb`, `g`/`gb`, with or without a space. No unit means MB.
 
+`--for` uses the current free-tier caps: `discord` 10 MB, `whatsapp` 16 MB, `wechat` 25 MB,
+`email` 20 MB, `twitter` 512 MB. Caps change, so `--to` always overrides.
+
 Exit codes: `0` success, `1` error. `--json` returns the plan, the measured quality, and the
 target accuracy, which makes it easy to wrap in a script.
 
@@ -211,12 +229,15 @@ at the same quality but can be awkward in some editors and older hardware. Defau
 Yes. It is plain Node.js and FFmpeg.
 
 **Can I batch a folder?**
-Not built in yet. A shell loop works today:
+Yes. List the files, or let your shell expand them:
 
 ```bash
-for f in *.mp4; do npx halfsize "$f" --to 25mb; done
+npx halfsize *.mp4 --to 25mb
 ```
 
+Each file gets its own plan and verdict, a failure does not stop the rest, and `--json` returns
+`{ "files": [ ... ] }`. `--out` is allowed only when there is a single input.
+
 **Why "halfsize"?**
 Because the honest answer to "how much smaller will it get?" is usually "about half, or a lot
 more than half". The tool reports the real number either way.
@@ -224,12 +245,11 @@ more than half". The tool reports the real number either way.
 ## Roadmap
 
 - Hardware encoding (NVENC / QSV / VideoToolbox) as an opt-in fast path
-- Batch mode and a folder watcher
+- A folder watcher that compresses new files as they appear
 - Subtitle and multiple audio track passthrough
 - HDR-to-SDR tonemapping, so iPhone HDR clips keep their colors
 - AV1 (`libsvtav1`) when the source is already AV1-friendly
 - A single-file binary, so Node.js is not required
-- Presets for specific platform caps (WeChat, Discord, email, X, Bluesky)
 
 If you want one of these, open an issue and say which. Pull requests are welcome; see
 [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -251,6 +271,8 @@ it to a target, probes the output, and asserts the size and SSIM. No fixtures in
 
 MIT. Use it, fork it, ship it.
 
+See [CHANGELOG.md](CHANGELOG.md) for what changed.
+
 ---
 
 If `halfsize` saved you from guessing a bitrate, a star helps the next person find it.

package/README.zh-CN.md

@@ -39,7 +39,7 @@ npx halfsize 婚礼.mp4 --to 25mb
 画质到底还在不在。
 
 ```
-  halfsize 0.1.0
+  halfsize 0.1.4
 
   source.mp4
   23.2 MB  8s  1920x1080  30.00 fps  h264
@@ -84,6 +84,12 @@ npx halfsize 婚礼.mp4 --to 25mb
 # 压到指定大小
 npx halfsize video.mp4 --to 25mb
 
+# 或者直接说你要传到哪里
+npx halfsize video.mp4 --for discord
+
+# 一次压好几个
+npx halfsize clip1.mp4 clip2.mp4 clip3.mp4 --to 10mb
+
 # 更小的文件，H.265
 npx halfsize video.mp4 --to 10mb --codec h265
 
@@ -118,6 +124,12 @@ npx halfsize --web
 
 每次压完可以生成一张**分享图**（就是本文最上面那张），上面是这次真实的数字。
 
+### 给 agent 用
+
+仓库里带了 [`skills/halfsize/SKILL.md`](skills/halfsize/SKILL.md)。把整个文件夹放进你的
+agent 技能目录（Claude Code 是 `.claude/skills/halfsize/`），agent 就能把「把这个视频压到
+25 MB」变成一次压缩加一份画质报告，而不是瞎猜码率。
+
 ## 它怎么工作
 
 1. **探测。** 读取时长、分辨率、帧率、音频码率、旋转信息、HDR 标记。
@@ -146,10 +158,12 @@ VMAF 是 Netflix 提出的感知质量指标，比 PSNR 或「码率多少」更
 halfsize <file> [options]
 
   --to <size>       目标大小：25mb、700k、1.5gb
+  --for <app>       按平台上限：discord、whatsapp、wechat、email、twitter
   --crf <n>         质量模式，不按大小（18 最好，23 均衡，28 更小）
   --codec <name>    h264（默认，兼容性最好）或 h265（大约再小 30%）
   --preset <name>   ultrafast .. veryslow（默认 medium）
   --out <file>      输出路径
+  --no-audio        去掉音轨
   --no-verify       跳过 SSIM/VMAF 检测
   --no-downscale    绝不降分辨率（可能会压不到目标）
   --json            机器可读结果
@@ -163,6 +177,9 @@ halfsize <file> [options]
 
 大小支持 `b`、`k`/`kb`、`m`/`mb`、`g`/`gb`，中间可以有空格。不写单位按 MB 算。
 
+`--for` 用的是当前免费档上限：`discord` 10 MB、`whatsapp` 16 MB、`wechat` 25 MB、
+`email` 20 MB、`twitter` 512 MB。平台上限会变，写死不如随时用 `--to` 覆盖。
+
 退出码：`0` 成功，`1` 出错。`--json` 会返回方案、画质测量和目标误差，方便包进脚本。
 
 ## 安装说明
@@ -198,24 +215,26 @@ H.264 到处都能播，包括老安卓机和浏览器。H.265 同画质大约
 能。就是 Node.js + FFmpeg，没有平台特定的东西。
 
 **能批量压一个文件夹吗？**
-还没内置。现在可以用一行 shell：
+能。直接把文件列出来，或者让 shell 展开：
 
 ```bash
-for f in *.mp4; do npx halfsize "$f" --to 25mb; done
+npx halfsize *.mp4 --to 25mb
 ```
 
+每个文件单独出方案和结论，某个失败不影响后面的，`--json` 返回 `{ "files": [ ... ] }`。
+多个输入时不能用 `--out`。
+
 **为什么叫 halfsize？**
 因为「能小多少」的诚实答案通常是「差不多一半，或者远不止一半」。它每次都会把真实数字告诉你。
 
 ## 路线图
 
 - 硬件编码（NVENC / QSV / VideoToolbox）作为可选的快速路径
-- 批量模式与文件夹监听
+- 文件夹监听，新文件一出现就自动压
 - 字幕和多音轨原样保留
 - HDR 转 SDR（让 iPhone 拍的 HDR 视频保住颜色）
 - 源已经是 AV1 时改用 AV1（`libsvtav1`）
 - 单文件二进制，不依赖 Node.js
-- 面向具体平台上限的预设（微信、Discord、邮件、X、Bluesky）
 
 想要哪个就开 issue 说一声。欢迎 PR，见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
@@ -236,6 +255,8 @@ node bin/halfsize.mjs --web
 
 MIT。随便用，随便改，随便发布。
 
+版本变化见 [CHANGELOG.md](CHANGELOG.md)。
+
 ---
 
 如果 `halfsize` 帮你少猜了一次码率，点个 star 能让下一个人也找到它。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halfsize",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Compress any video to an exact target size, locally, and prove the quality did not drop.",
   "type": "module",
   "bin": {
@@ -22,6 +22,8 @@
     "src",
     "web",
     "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/src/cli.mjs

@@ -7,13 +7,15 @@ import { encode } from "./encode.mjs";
 import { measureQuality, verdict } from "./quality.mjs";
 import { bytes, duration, bitrate, ratio, parseSize, clock } from "./human.mjs";
 
-const VERSION = "0.1.3";
+const VERSION = "0.1.4";
 
 const HELP = `
   halfsize ${VERSION} - compress a video to an exact size, and prove it still looks the same.
 
   Usage
     halfsize <file> --to 25mb          Compress to a target size
+    halfsize <file> --for discord      Use a platform's upload limit
+    halfsize a.mp4 b.mp4 --to 10mb     Compress several files in a row
     halfsize <file> --to 25mb --codec h265
     halfsize <file> --crf 23           Quality-first mode
     halfsize --web                     Open the local app
@@ -22,10 +24,12 @@ const HELP = `
 
   Options
     --to <size>       Target size: 25mb, 700k, 1.5gb
+    --for <app>       Target cap for discord, whatsapp, wechat, email, twitter
     --crf <n>         Quality mode (18 best / 23 balanced / 28 small)
     --codec <name>    h264 (default, compatible) or h265 (smaller)
     --preset <name>   ultrafast..veryslow (default: medium)
     --out <file>      Output path
+    --no-audio        Drop the audio track
     --no-verify       Skip the SSIM/VMAF check
     --no-downscale    Never reduce resolution
     --json            Machine-readable result
@@ -40,7 +44,26 @@ const HELP = `
     resolution, encodes twice, then measures the result with SSIM and VMAF.
 `;
 
-const DEFAULTS = { codec: "h264", preset: "medium", verify: true, downscale: true };
+const DEFAULTS = { codec: "h264", preset: "medium", verify: true, downscale: true, audio: true };
+
+// Current upload caps as people hit them. Caps change, so --to always wins if a
+// preset is wrong for your account tier.
+const PLATFORMS = {
+  discord: { bytes: 10 * 1_000_000, label: "Discord free (10 MB)" },
+  whatsapp: { bytes: 16 * 1_000_000, label: "WhatsApp media (16 MB)" },
+  wechat: { bytes: 25 * 1_000_000, label: "WeChat video (25 MB)" },
+  email: { bytes: 20 * 1_000_000, label: "Email attachment (20 MB)" },
+  twitter: { bytes: 512 * 1_000_000, label: "X / Twitter (512 MB)" },
+};
+
+function platformFor(name) {
+  const key = String(name || "").toLowerCase();
+  const found = PLATFORMS[key];
+  if (!found) {
+    throw new Error(`Unknown platform "${name}". Use one of: ${Object.keys(PLATFORMS).join(", ")}.`);
+  }
+  return { key, ...found };
+}
 
 function parseArgs(argv) {
   const args = { _: [], flags: { ...DEFAULTS } };
@@ -52,10 +75,12 @@ function parseArgs(argv) {
     else if (a === "--dry-run") args.flags.dryRun = true;
     else if (a === "--no-verify") args.flags.verify = false;
     else if (a === "--no-downscale") args.flags.downscale = false;
+    else if (a === "--no-audio") args.flags.audio = false;
     else if (a === "--web") args.flags.web = true;
     else if (a === "--doctor") args.flags.doctor = true;
     else if (a === "--port") args.flags.port = Number(argv[++i]);
     else if (a === "--to") args.flags.to = argv[++i];
+    else if (a === "--for") args.flags.for = argv[++i];
     else if (a === "--crf") args.flags.crf = Number(argv[++i]);
     else if (a === "--codec") args.flags.codec = argv[++i];
     else if (a === "--preset") args.flags.preset = argv[++i];
@@ -81,18 +106,53 @@ export async function main(argv) {
   if (flags.doctor) return doctor();
   if (flags.web) return startWeb(flags.port);
 
-  const input = path.resolve(args._[0]);
-  if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
-  if (!flags.to && flags.crf === undefined) {
-    throw new Error("Pick a target: --to 25mb, or use --crf 23 for quality mode.");
+  if (flags.to && flags.for) throw new Error("Use --to or --for, not both.");
+  const platform = flags.for ? platformFor(flags.for) : null;
+  if (!flags.to && !platform && flags.crf === undefined) {
+    throw new Error("Pick a target: --to 25mb, --for discord, or --crf 23 for quality mode.");
+  }
+  if (flags.out && args._.length > 1) {
+    throw new Error("--out only works with one input file. It would overwrite itself in a batch.");
+  }
+
+  const inputs = args._.map((file) => path.resolve(file));
+  const targetBytes = platform ? platform.bytes : flags.to ? parseSize(flags.to) : null;
+  const batch = inputs.length > 1;
+
+  const results = [];
+  let failed = 0;
+  for (const input of inputs) {
+    try {
+      results.push(await processFile(input, flags, targetBytes, platform, batch));
+    } catch (err) {
+      failed++;
+      results.push({ input: { file: input }, error: err?.message || String(err) });
+      if (!flags.json) console.error(`\n  x ${path.basename(input)}: ${err?.message || err}`);
+      if (process.env.HALFSIZE_DEBUG) console.error(err?.stack);
+    }
   }
 
-  const targetBytes = flags.to ? parseSize(flags.to) : null;
+  if (flags.json) {
+    console.log(JSON.stringify(batch ? { files: results } : results[0], null, 2));
+  } else if (batch && !flags.dryRun) {
+    printBatch(results);
+  }
+
+  if (failed) process.exitCode = 1;
+}
+
+async function processFile(input, flags, targetBytes, platform, batch) {
+  if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
+
   const info = await probe(input);
 
   if (targetBytes && targetBytes >= info.sizeBytes) {
-    console.log(`\n  This file is already ${bytes(info.sizeBytes)}, smaller than the ${bytes(targetBytes)} target.\n`);
-    return;
+    if (batch) {
+      console.log(`\n  ${path.basename(input)} already fits (${bytes(info.sizeBytes)}), skipped.`);
+    } else {
+      console.log(`\n  This file is already ${bytes(info.sizeBytes)}, smaller than the ${bytes(targetBytes)} target.\n`);
+    }
+    return { input: { file: input, bytes: info.sizeBytes }, targetBytes, skipped: "already-smaller" };
   }
 
   const plan = planEncode(info, {
@@ -101,17 +161,20 @@ export async function main(argv) {
     codec: flags.codec,
     preset: flags.preset,
     downscale: flags.downscale,
+    audio: flags.audio,
   });
 
-  const outPath = flags.out
-    ? path.resolve(flags.out)
-    : defaultOutput(input, flags, plan);
+  const outPath = flags.out ? path.resolve(flags.out) : defaultOutput(input, flags, plan);
 
-  if (!flags.json) printPlan(info, plan, flags, outPath);
+  if (!flags.json) printPlan(info, plan, flags, outPath, platform, !batch);
 
   if (flags.dryRun) {
-    if (flags.json) console.log(JSON.stringify({ info, plan, out: outPath }, null, 2));
-    return;
+    return {
+      info,
+      plan,
+      out: outPath,
+      dryRun: true,
+    };
   }
 
   const progress = new Progress(Boolean(process.stdout.isTTY) && !flags.json, info.duration);
@@ -123,7 +186,7 @@ export async function main(argv) {
   }
 
   let quality = { ssim: null, vmaf: null };
-  if (flags.verify && !flags.noVerify) {
+  if (flags.verify) {
     if (!flags.json) process.stdout.write(`  measuring quality `);
     quality = await measureQuality(input, outPath, info.duration);
     if (!flags.json) process.stdout.write(`\r${" ".repeat(40)}\r`);
@@ -142,19 +205,34 @@ export async function main(argv) {
     elapsedMs: result.elapsedMs,
   };
 
-  if (flags.json) {
-    console.log(JSON.stringify(summary, null, 2));
-    return;
-  }
+  if (!flags.json) printResult(summary, outPath);
+  return summary;
+}
 
-  printResult(summary, outPath);
+function printBatch(results) {
+  const done = results.filter((r) => r.output);
+  const skipped = results.filter((r) => r.skipped);
+  const errors = results.filter((r) => r.error);
+  console.log("");
+  if (done.length) {
+    const before = done.reduce((sum, r) => sum + r.input.bytes, 0);
+    const after = done.reduce((sum, r) => sum + r.output.bytes, 0);
+    console.log(`  ${done.length} compressed   ${bytes(before)} -> ${bytes(after)}   ${ratio(before, after)} smaller`);
+  }
+  if (skipped.length) console.log(`  ${skipped.length} skipped (already under target)`);
+  if (errors.length) console.log(`  ${errors.length} failed`);
+  console.log("");
 }
 
 function defaultOutput(input, flags, plan) {
   const dir = path.dirname(input);
   const ext = path.extname(input);
   const base = path.basename(input, ext);
-  const tag = flags.to ? String(flags.to).replace(/\s+/g, "").toLowerCase() : `crf${flags.crf}`;
+  const tag = flags.for
+    ? String(flags.for).toLowerCase()
+    : flags.to
+      ? String(flags.to).replace(/\s+/g, "").toLowerCase()
+      : `crf${flags.crf}`;
   return path.join(dir, `${base}.${tag}.mp4`);
 }
 
@@ -162,16 +240,18 @@ function line(label, value) {
   console.log(`  ${label.padEnd(10)} ${value}`);
 }
 
-function printPlan(info, plan, flags, outPath) {
-  console.log("");
-  console.log(`  halfsize ${VERSION}`);
+function printPlan(info, plan, flags, outPath, platform, showHeader = true) {
   console.log("");
+  if (showHeader) {
+    console.log(`  halfsize ${VERSION}`);
+    console.log("");
+  }
   console.log(`  ${path.basename(info.file)}`);
   console.log(
     `  ${bytes(info.sizeBytes)}  ${duration(info.duration)}  ${info.video.width}x${info.video.height}  ${info.video.fps.toFixed(2)} fps  ${info.video.codec}`,
   );
   console.log("");
-  if (plan.mode === "size") line("target", bytes(plan.targetBytes));
+  if (plan.mode === "size") line("target", platform ? `${bytes(plan.targetBytes)}  (${platform.label})` : bytes(plan.targetBytes));
   else line("mode", `CRF ${plan.crf}`);
   line(
     "plan",

package/src/encode.mjs

@@ -15,6 +15,10 @@ function buildFilters(plan) {
 
 function baseArgs(input, plan, passlog) {
   const args = ["-hide_banner", "-y", "-i", input];
+  // Map exactly the streams we mean to encode. Without this, ffmpeg can pick a
+  // cover art / thumbnail stream on files that carry one.
+  args.push("-map", "0:v:0");
+  if (plan.audioKbps) args.push("-map", "0:a:0?");
   const filters = buildFilters(plan);
   if (filters) args.push("-vf", filters);
   args.push("-fps_mode", "cfr");
@@ -28,7 +32,7 @@ function baseArgs(input, plan, passlog) {
 
 function audioArgs(plan) {
   if (!plan.audioKbps) return ["-an"];
-  return ["-c:a", "aac", "-b:a", `${plan.audioKbps}k`, "-ac", "2"];
+  return ["-c:a", "aac", "-b:a", `${plan.audioKbps}k`, "-ac", String(plan.audioChannels === 1 ? 1 : 2)];
 }
 
 export async function encode(input, output, plan, info, onProgress = () => {}) {

package/src/plan.mjs

@@ -62,6 +62,8 @@ export function planEncode(info, options = {}) {
 
   if (!info.duration) throw new Error("Could not read the duration of this file.");
 
+  const audioChannels = info.audio?.channels === 1 ? 1 : 2;
+
   if (options.crf !== undefined) {
     return {
       mode: "quality",
@@ -74,7 +76,8 @@ export function planEncode(info, options = {}) {
       height: info.video.height,
       fps: capFps(info.video.fps),
       videoKbps: null,
-      audioKbps: audioBitrate(info, 2000),
+      audioKbps: options.audio === false ? 0 : audioBitrate(info, 2000),
+      audioChannels,
       targetBytes: null,
       twoPass: false,
       downscaled: false,
@@ -87,7 +90,7 @@ export function planEncode(info, options = {}) {
   if (!options.targetBytes) throw new Error("A target size is required.");
 
   const totalKbps = ((options.targetBytes * 8) / info.duration / 1000) * 0.97;
-  const audioKbps = audioBitrate(info, totalKbps);
+  const audioKbps = options.audio === false ? 0 : audioBitrate(info, totalKbps);
   const videoKbps = Math.max(40, Math.round(totalKbps - audioKbps));
   const fps = capFps(info.video.fps);
 
@@ -131,6 +134,7 @@ export function planEncode(info, options = {}) {
     fps,
     videoKbps,
     audioKbps,
+    audioChannels,
     targetBytes: options.targetBytes,
     twoPass: Boolean(codec.twoPass),
     downscaled,