Skip to main content
Glama

Audio Analysis & Dedupe

An MCP server that inspects an audio folder and answers two questions: what is inside these files?, and which of them are duplicates?

检查音频文件夹:文件里是什么(时长/采样率/声道/编码/码率),以及哪些是重复的 (完全重复、同音频不同容器、近似重复候选)。

Works with any MCP-compatible agent or client.

Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).

中文说明 · License: AGPL-3.0

Features

  • Library analysis. Size, duration, sample rate, channels, codec and bitrate for every file in a folder (recursively if you want).

  • Exact duplicates. Byte-identical files, grouped by SHA-256 with a suggested file to keep.

  • Same audio, different container. Files whose decoded PCM stream is identical (for example the same master exported as WAV, AIFF and AU) are reported separately.

  • Near-duplicate candidates. Name (with (1), - copy, (1) style suffixes normalised), duration and size are compared, with an explicit list of differences for each candidate pair.

  • Read-only by design. It never deletes, moves, renames or rewrites a file, and never touches a vendor database.

Related MCP server: disk-clean-mcp

Requirements

OS

macOS, Linux or Windows

Python

3.9 or newer

Optional

ffprobe on PATH (or SHADOW_FFPROBE) for formats outside WAV/AIFF/AU

Install

As a Codex plugin

codex plugin marketplace add shadowroommusic/audio-analysis-dedupe
codex plugin add audio-analysis-dedupe@shadowroom

In any other MCP client

{
  "mcpServers": {
    "audio-analysis-dedupe": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/path/to/audio-analysis-dedupe"
    }
  }
}

CLI only

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/shadow-audio-dedupe --help

Configuration

Option

Default

Used for

SHADOW_FFPROBE

auto-detected

path to ffprobe for non-PCM containers

--threshold

0.72

similarity threshold for near-duplicate candidates

--output

stdout

write the JSON report to a file

Tools

Tool

What it does

analyze_file

Analyse a single file (format, duration, sample rate, channels, bitrate)

dedupe_folder

Analyse a folder and group duplicates (recursive, threshold, max_candidates)

CLI equivalents: shadow-audio-dedupe analyze --path <file-or-folder> and shadow-audio-dedupe dedupe --folder <folder>.

Usage

# what is in this crate?
.venv/bin/shadow-audio-dedupe analyze --path ~/Music/Crate --output analysis.json

# what is duplicated, and how do the versions differ?
.venv/bin/shadow-audio-dedupe dedupe --folder ~/Music/Crate --threshold 0.72 --output duplicates.json

The dedupe report contains exact_groups, identical_audio_groups, candidates (each with reasons and differences) and a summary with the redundant file count and bytes.

Safety

  • Read-only: nothing is modified, and no vendor database is opened.

  • Reports are written only to the path you pass with --output (or to stdout).

Troubleshooting

Symptom

What to do

Metadata unavailable for MP3/FLAC

Install ffmpeg/ffprobe, or set SHADOW_FFPROBE to its path.

Everything looks like a near-duplicate

Raise --threshold (for example 0.85).

Very large folders are slow

Narrow the folder, or run analyze first to see what is inside.

Contributing

See CONTRIBUTING.md. Implementation notes live in docs/internals.md.

License

AGPL-3.0 — see LICENSE. Optional ffprobe usage is subject to the license of your local FFmpeg installation.

Available Tools

2 tools
analyze_fileB

Report size, duration, sample rate, channels, codec and bitrate for one audio file.

Inputs: path (required).

dedupe_folderB

Group exact SHA-256 duplicates and list near-duplicate candidates in a folder. Never deletes files.

Inputs: folder (required), recursive, threshold, max_candidates.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    analyze_file targets a single file's metadata, while dedupe_folder scans a folder for duplicates. The two purposes are clearly distinct with no overlapping behavior.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun snake_case pattern: analyze_file and dedupe_folder. The naming is predictable and readable.

    Tool Count3/5

    Only two tools for a server named audio-analysis-dedupe feels thin. The core actions are covered, but the surface is minimal and could benefit from more analysis options.

    Completeness3/5

    The server can analyze one file and detect duplicates, but it offers no batch analysis and no way to resolve duplicates (e.g., delete or move). This is a notable gap for a 'dedupe' tool, even if the no-delete behavior is intentional.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to analyze audio files, extracting tempo, key, beat drops, volume surges, high tones, loudness, brightness, and structure, and returning structured JSON and visualizations.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables users to ask natural-language questions about a local folder's contents, including file names, sizes, and timestamps, with rollups by type and age and cleanup suggestions for stale or large files. It returns metadata only and cannot read, move, or delete files.
      2
      33 PyPI
      1
      MIT