MediaCli

查看中文文档

MediaCli is a comprehensive multimedia file processing CLI tool. Specifically designed for photographers and media collectors, it leverages powerful tools like ffmpeg and exiftool to efficiently compress, convert, organize, rename, and manage image, video, and audio files.

Features

• Smart Organization: Organize photos and videos by date (EXIF metadata or file attributes).
• Batch Processing: Compress images, convert videos/audio, and rename files in bulk.
• File Management: Intelligent file moving, deletion, and directory flattening.
• Encoding Fixes: Detect and fix filename encoding issues (e.g., GBK, Shift-JIS) and smart unzip.
• Raw Workflow: Utilities to manage RAW + JPEG workflows.

Installation

Install globally via npm:

npm install mediac -g

Or run locally:

git clone https://github.com/mcxiaoke/media-cli.js.git
cd media-cli.js
npm install
npm start -- --help

Usage

Basic usage syntax:

mediac <command> <input> [options]

To see help for a specific command:

mediac <command> --help

Commands

This table is generated from the registered yargs commands (node mediac --help). The previously listed organize / oz command does not exist.

| Command | Aliases | Description | | -------------------- | ------------------------------------ | --------------------------------------------------------------------------------- | | compress | cs, cps | Compress images to target size/quality while preserving metadata. | | dcimr | dm, dcim | Rename media files based on EXIF Date/Time or file attributes. | | decode | dc | Decode text containing messy or invalid characters. | | execute [input] | run | Run standalone tasks — registered as a placeholder, not implemented yet. | | ffmpeg | transcode, aconv, vconv, avconv | Convert video/audio using FFmpeg presets. | | lrmove | lv | Move JPEG files that have matching RAW files to a separate folder. | | move | md | Move files to folders based on date patterns in filenames. | | moveup | mp | Flatten directories by moving files to parent/top folders. | | pick | pk | Smart photo selection for photo journals (filters by time/date distribution). | | prefix | pf, px | Batch rename by prepending directory names or custom strings. | | remove | rm, rmf | Delete files matching specific size, resolution, or name patterns. | | rename | fn, fxn | Advanced rename (fix encoding, regex replace, char cleanup, TC to SC). | | test (default) | tt | No-op command used to smoke-test the CLI. | | zipu | zipunicode | Smart Unzip detecting filename encoding automatically. |

FFmpeg Command

mediac ffmpeg <input> (aliases transcode / aconv / vconv / avconv) transcodes video and audio using presets, driven by a hardware-acceleration-aware engine. See docs/FFMPEG-USAGE.md for the full parameter reference and caveats.

Key points that reflect the current implementation:

• Dry-run by default. Without --doit the command only scans files, picks the hardware tier, builds the command and logs it — it writes nothing. Add --doit to actually transcode.
• --preset is required (no default). List available presets with --show-presets.
• Automatic hardware tiering. Per file it probes CUDA / QSV / AMF / D3D11VA / software-decode+ hardware-encode / pure CPU and gracefully degrades; the encoder is chosen by the resolved tier plus the preset's output codec family (never by input bit depth). Use --hwaccel / --decode-mode to steer it, and --strict to disable every fallback (unsupported files are skipped, not retried).
• Presets are YAML, layered & inheritable. Built-in single source is presets/default.yaml (h264 / hevc / av1 / vp9 / audio families); user layers live in ~/.mediac/presets.yaml and ./presets.yaml. Overriding a built-in name requires an explicit _override: true.
• Filters and extra encoder parameters live in the preset YAML, not on the command line. The --video-args / --audio-args / --filters options were removed in the S-4 refactor; use the preset fields instead: filters (with the {scaleFilter} placeholder), pre_filters / post_filters (three-segment filter chain), inputArgs / streamArgs / outputArgs. To change the encoder use --video-codec or --ffargs "vc=..." — injecting -c:v yourself is what the layering exists to prevent.
• Dedicated --metadata channel whose values may contain spaces; --ffargs uses ; : # as key/value separators (not commas).
• Built-in safety rails. Smart bitrate (never exceeds source, never upscales), temp-file writes with interrupt cleanup, and --delete-source-files only removes the source when a non-empty output exists (moved to the Recycle Bin after confirmation; never in dry-run).

# preview the exact command, then run it
mediac ffmpeg ./video.mp4 --preset hevc_2k
mediac ffmpeg ./video.mp4 --preset hevc_2k --doit

Decode Command Detailed Usage

The decode command is used to identify and fix encoding issues in text, particularly for filenames or text content that appears garbled due to encoding mismatches.

Usage

mediac decode [strings...] [options]

Options

| Option | Alias | Type | Description | | ------------- | ----- | ------- | -------------------------------------------- | | --from-enc | -f | string | Source encoding to try first | | --to-enc | -t | string | Target encoding to convert to | | --files | -i | array | Files to process (supports wildcards) | | --recursive | -r | boolean | Recursively process files in subdirectories |

Examples

1. Decode a single garbled string:

   mediac decode "乱码字符串"

2. Decode multiple strings:

   mediac decode "乱码1" "乱码2" "乱码3"

3. Decode with specific encoding settings:

   mediac decode --from-enc gbk --to-enc utf8 "乱码字符串"

4. Decode files:

   mediac decode --files *.txt

5. Recursively decode files in subdirectories:

   mediac decode --files **/*.txt --recursive

Supported Encodings

The decode command supports a wide range of encodings, including:

• UTF-8, UTF-16, UTF-32
• GBK, BIG5
• SHIFT_JIS, EUC-JP
• EUC-KR, CP949
• ISO-8859-1, ISO-8859-2

How It Works

The decode command uses an intelligent approach to detect and fix encoding issues:

1. It first analyzes the input text to identify potential encoding problems
2. It then tries different encoding combinations to find the best match
3. It evaluates the quality of each decoding attempt
4. It returns the best decoding result with confidence scores

This makes it particularly effective for fixing filenames that were encoded in one encoding and displayed in another, a common issue when transferring files between different systems.

Development

Prerequisites

• Node.js (v22+，见 package.json 的 engines)
• Tools: ffmpeg, ffprobe, exiftool must be installed and available in PATH for full functionality.

Scripts

• npm run check: Verify syntax.
• npm run lint: Lint code with ESLint.
• npm run test:package: Pack, install, and smoke-test the published CLI artifact.
• npm run lint:fix: Fix linting errors.
• npm run prettier:fix: Format code with Prettier.
• npm start: Run the CLI locally.

License

Copyright 2021-2026 @ Zhang Xiaoke.

Licensed under the Apache License 2.0.