Media library naming scanner & organizer — deep scan + old→new preview + rename/move. Works on local disks, cloud drives, and any NAS — ZSpace, Synology, QNAP, UGREEN, TerraMaster, ASUSTOR, WD My Cloud, Lenovo, Hikvision, TrueNAS, Unraid, OpenMediaVault, and more. Built for a global audience: Chinese (cn) and English/Plex (plex) naming conventions, localized output, and configurable library folders.

Naming conventions live in media-naming-guide. The core is pure Python and backend-agnostic; NAS access goes through adapters (e.g. ZSpace via zspace-cli).

Supported scenarios

Anything that can be listed as {path, name, is_dir} works with the scanner. Mounting as a local folder is the simplest integration.

Naming convention profiles

Pick the ruleset that matches your library:

Folders are configurable — use --movie-zone / --series-zone to match your own layout. The cn profile defaults to 电影 and 剧集; the plex profile defaults to Movies and TV Shows.

Install

pip install media-manager-skill            # local mode, zero deps
pip install "media-manager-skill[zspace]"  # ZSpace mode (bundles zspace-cli)

# CLI entry point
mm-scan --source local /path/to/library

No install needed to try it: python scripts/scan.py --source local /path/to/library (this repo ships the full implementation).

Quick start

# Chinese library (default profile cn, folders 电影/剧集)
mm-scan /path/to/library

# English / Plex library
mm-scan --profile plex ~/Movies

# ZSpace NAS
zs check
mm-scan --source zspace /path/to/library

# English output (auto-detected from locale if not set)
mm-scan --lang en /path/to/library

# JSON output (machine-readable problem codes)
mm-scan --json /path/to/library > /tmp/issues.json

# old→new rename suggestions
mm-scan --preview /path/to/library

# Custom folder names
mm-scan --profile plex --movie-zone Films --series-zone Shows ~/Videos

CLI options

What it does

• Deep-scans a media library (movies / series) against the selected naming convention
• Detects: invalid folder/file names, watermarks/site tags, censorship-evasion characters (cn), placeholders, folder/file name mismatches, PT/Scene raw names, duplicates
• Outputs an old→new preview (--preview) before you rename/move in bulk
• JSON output uses stable problem codes (see below); CLI/terminal output is localized
• Pluggable sources: local filesystem (default) or ZSpace NAS (--source zspace)

Problem codes (JSON contract)

--json emits a list of issues. Each item: {path, name, is_dir, problems, new_name} where problems is a list of stable machine-readable codes (they never change across locales):

For human-readable text, map codes through PROBLEM_MESSAGES[code][lang] (exported by the package) or just run the CLI without --json.

Pairing with other tools

Use before Jellyfin / Emby / MoviePilot / nas-tools / ZSpace media ingesting or scraping to surface naming problems in one pass. See docs/integrations.md.

As an Agent Skill

cp -r SKILL.md scripts ~/your-project/skills/media-manager/

Then ask your agent: "scan naming issues in ~/Movies" (local/plex) or "scan naming issues in /path/to/library" (ZSpace).

Repository layout

media-manager-skill/
├── SKILL.md          # Agent skill entry (workflow + gotchas)
├── scripts/
│   └── scan.py       # Thin wrapper (same core, runnable without install)
├── src/
│   └── media_manager_skill/
│       ├── scan.py   # Core implementation (profiles, i18n, CLI)
│       └── __init__.py
├── tests/            # pytest suite (cn + plex + i18n)
└── docs/
    └── integrations.md

How it works & limitations

• Core validation is pure Python (regex + rules), backend-agnostic — local, cloud, any NAS
• ZSpace mode reads the desktop client login via zspace-cli; the macOS client must be online
• Other NAS / cloud: mount as a local folder, or write a small walker adapter
• Naming conventions come from media-naming-guide
• Unofficial project, intended for personal libraries

License

MIT