vid-com

Video bitrate scanner & batch compressor CLI, with Sony ARW → JPEG conversion and safe interactive cleanup. Powered by FFmpeg with Apple hardware acceleration (hevc_videotoolbox).

视频码率扫描 & 批量压缩 CLI 工具，含 Sony ARW → JPEG 转换及安全交互式清理。基于 FFmpeg，使用 Apple 硬件加速（hevc_videotoolbox）。

Requirements / 依赖

• Node.js >= 16
• ffmpeg / ffprobe in PATH
• macOS (VideoToolbox hardware acceleration)

brew install ffmpeg

Installation / 安装

# Global install (recommended) / 全局安装（推荐）
npm install -g vid-com


## Commands / 命令

### find — Scan for high-bitrate videos / 扫描高码率视频

Scans a directory for videos exceeding a bitrate threshold and outputs a JSON list sorted by file size.

扫描目录，找出码率超过阈值的视频，输出 JSON 列表，按文件大小升序排列。

```bash
vid-com find --dir <dir> [options]

| Option | Description | Default | |--------|-------------|---------| | --dir | Directory to scan (required) / 扫描目录（必填） | — | | --threshold | Bitrate threshold in kbps / 码率阈值（kbps） | 4000 | | --output | Output JSON file path / 输出 JSON 文件路径 | bitrate_list.json | | --recursive | Recurse into subdirectories / 递归扫描子目录 | off |

vid-com find --dir ~/Videos --threshold 3000 --recursive --output dji.json

Output JSON format / 输出 JSON 格式：

[
  {
    "path": "/absolute/path/to/video.mp4",
    "bitrate_kbps": 12800,
    "size_mb": 3200.00
  }
]

compress — Batch compress / 批量压缩

Reads the JSON list from find, compresses files sequentially with a real-time progress bar.

读取 find 输出的 JSON 列表，串行压缩，实时显示进度条。

vid-com compress --input <json-file> [options]

| Option | Description | Default | |--------|-------------|---------| | --input | JSON list file (required) / JSON 列表文件（必填） | — | | --outdir | Output directory / 输出目录 | same as source / 原文件同目录 | | --suffix | Output filename suffix / 文件名后缀 | _compressed | | -q / --quality | Quality value 0–100, higher is better / 画质值（越高越好） | 65 | | --target | Fixed bitrate in kbps, overrides -q / 固定码率，指定后忽略 -q | — | | --audio | Audio bitrate in kbps / 音频码率（kbps） | 128 |

Encoder notes / 编码说明：

• Encoder / 编码器: hevc_videotoolbox (Apple hardware H.265)
• Decoder / 解码器: videotoolbox (hardware decode, lower CPU load)
• Pixel format / 像素格式: nv12 (native VideoToolbox format)
• Codec tag / codec tag: hvc1 (QuickTime / Final Cut / iOS compatible)

# Quality mode (default, recommended) / 画质模式（默认，推荐）
vid-com compress --input dji.json --outdir ./out

# Fixed bitrate mode / 固定码率模式
vid-com compress --input dji.json --target 8000 --outdir ./out

# Custom quality and audio bitrate / 自定义画质和音频码率
vid-com compress --input dji.json -q 50 --outdir ./out --suffix _h265 --audio 192

Progress bar example / 进度条示例：

▶  [3/79]  DJI_20260328141509_0169_D.MP4
   Source bitrate: 110001 kbps  →  Quality -q:v 65
   Output: /Volumes/QWER/out/DJI_20260328141509_0169_D_compressed.MP4
   [████████████░░░░░░░░░░░░░░░░░░]  42.3%  3.2x      ETA 87s

delete — Verify and delete original videos / 校验后删除原始视频

Reads the find JSON list, locates the _compressed.MP4 counterpart in the same directory, verifies source metadata via ffprobe, then prompts for deletion.

读取 JSON 列表，查找同目录下的 _compressed.MP4，通过 ffprobe 验证源信息后询问删除。

vid-com delete [--input <json-file>]

| Option | Description | Default | |--------|-------------|---------| | --input | JSON list from find / find 输出的 JSON | my_list.json |

Source metadata checks / 源信息对比（ffprobe）：

• Duration / 时长: difference must be ≤ 1 second / 差值须 ≤ 1 秒
• Capture time / 拍摄时间: creation_time must match exactly (preserved via -map_metadata 0)
• Any mismatch → auto-skipped, no deletion prompt / 任一不匹配则自动跳过

[3/79]
  Original  : /Volumes/QWER/DJI_0169.MP4
  Orig size : 3200.00 MB
  Compressed: /Volumes/QWER/DJI_0169_compressed.MP4
  Comp size : 800.00 MB
  Saved     : 2400.00 MB (75.0%)
  Duration  : 42.3s → 42.3s  ✓
  Captured  : 2026-03-28T14:15:09.000000Z  ✓
  Delete original? [y = yes / other = skip]: y
  -> DELETED

arw-convert — Sony ARW to JPEG / Sony ARW 转 JPEG

Batch-converts Sony .arw RAW files to JPEG using macOS built-in sips with multi-threaded parallel processing.

批量将索尼 .arw RAW 文件转换为 JPEG，使用 macOS 内置 sips 多线程并发处理。

vid-com arw-convert <source-dir> [output-dir]

| Argument | Description | Default | |----------|-------------|---------| | <source-dir> | Directory containing .arw files, searched recursively / 含 .arw 文件的目录（递归查找） | required | | [output-dir] | JPEG output directory, flat (no subdirectory structure) / JPEG 输出目录（平级输出） | ./converted_jpgs |

• Concurrency / 并发数: CPU cores − 1
• Output quality / 输出质量: JPEG quality 90
• Dependency / 依赖: macOS built-in sips, no extra install needed / macOS 内置，无需额外安装

vid-com arw-convert /Volumes/Untitled/DCIM /Volumes/QWER/out

arw-delete — Verify and delete ARW originals / 校验后删除 ARW 原始文件

Scans a directory for .arw files, finds a same-named .jpg, verifies pixel dimensions via sips, then prompts for deletion of the ARW.

扫描目录下所有 .arw 文件，查找同名 .jpg，通过 sips 验证像素尺寸后询问删除 ARW。

vid-com arw-delete --dir <dir>

| Option | Description | |--------|-------------| | --dir | Directory containing .arw files (required) / 含 .arw 文件的目录（必填） |

Source metadata check / 源信息对比（sips）：

• Pixel dimensions / 像素尺寸: width × height must match exactly / 必须完全一致
• Missing JPG or dimension mismatch → auto-skipped / JPG 不存在或尺寸不匹配则自动跳过

[12/80]
  ARW  : DSC00169.ARW
  Size : 24.50 MB
  JPG  : DSC00169.jpg  (8.20 MB)
  Dims : 7952×5304 vs 7952×5304  ✓
  Delete ARW? [y = yes / other = skip]: y
  -> DELETED

Typical workflow / 典型工作流

# Video workflow / 视频工作流
vid-com find --dir ~/Videos --recursive --output /tmp/list.json
vid-com compress --input /tmp/list.json --outdir ~/Videos/out
vid-com delete --input /tmp/list.json

# ARW workflow / ARW 工作流
vid-com arw-convert /Volumes/Untitled/DCIM /Volumes/QWER/out
vid-com arw-delete --dir /Volumes/Untitled/DCIM

Quality reference / 画质参考（-q:v）

| -q value | Effect / 效果 | |------------|---------------| | 80–90 | Near-lossless, large file / 接近无损，文件较大 | | 60–70 | Balanced quality/size (recommended) / 画质/尺寸均衡（推荐） | | 45–55 | Noticeable compression, archive use / 明显压缩，适合纯归档 | | < 40 | Visible quality loss / 肉眼可见质量损失 |

Help / 帮助

vid-com --help