MediaTaggerBot

Portfolio · GitHub profile

MediaTaggerBot is a local-first workflow for standardizing audio and music-video libraries when a wrong match is more costly than an unresolved file.

MediaTaggerBot turns inconsistent local filenames and tags into a predictable library structure:

Artist - Title - Genre.ext
Artist - Title - Genre - Subgenre.ext

Built for Windows, it combines public metadata with local evidence, records why each match was accepted, and places dry-run review and conservative apply gates between identification and file mutation.

Confidence is a write control, not just a score. Evidence may propose a match, but only a complete scan and conservative gate can authorize a write. Uncertain files remain visible for review instead of being forced into a best guess.

Operational evidence

This design is informed by a separate private operating workflow applied to a 38,171-file library. Its latest reconciled checkpoint records 838 verified or already-current metadata outcomes, zero matched-row readback mismatches, zero unmanifested eligible files, and 15 preservation-sensitive cases held closed rather than forced through a write.

Those aggregate results are validation evidence, not a claim that every library file was corrected. Private media, paths, catalog evidence, and operating records are not included in this repository.

Workflow safeguards

• Evidence hierarchy: embedded stable IDs and acoustic fingerprints outrank text matching.
• Safe operating modes: preflight, recursive scan, and dry-run precede any write operation.
• Conservative apply gate: apply-safe rejects ambiguous, weakly corroborated, fallback-genre, or incomplete-scan candidates.
• Transaction discipline: a durable SQLite journal, source-change checks, metadata readback, and rename verification make partial failures visible.
• Operational resilience: bounded retries, provider-specific circuit breakers, cache integrity checks, single-instance ownership, and graceful stop requests.
• Recovery evidence: rollback manifests restore filenames; diagnostics are allowlisted, size-bounded, and redacted.

recursive scan
    -> identity evidence
    -> confidence and ambiguity gates
    -> dry-run review
    -> journaled metadata write and verification
    -> verified rename

Quick start

Requirements:

• Windows 10 or later
• 64-bit CPython 3.11–3.14
• Network access for Python dependencies and enabled metadata providers
• Optional: fpcalc, ffprobe/FFmpeg, and ExifTool; see tools/README.md

The easiest path is to clone the repository and run Start_MediaTaggerBot.bat. The launcher creates a project-local virtual environment and installs the exact hash-checked dependencies in requirements.lock.txt.

For a manual setup:

py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e .
copy config\config.example.toml config\config.toml
.venv\Scripts\python -m mediataggerbot --mode preflight

Set paths.media_root and a meaningful project.contact value in the generated config/config.toml. API credentials can also be provided through ACOUSTID_CLIENT_KEY, LASTFM_API_KEY, and DISCOGS_USER_TOKEN environment variables.

Project-wide paths, matching thresholds, provider rate limits, naming rules, and verification policy are centralized in the TOML file; credentials can remain in environment variables.

Recommended operating sequence

1. Back up the media you intend to test.
2. Run Repair/check and set the media root.
3. Run Preflight, then Scan-only.
4. Review a Dry-run and its exception reports.
5. Test Apply-safe on a small, backed-up sample before widening scope.

apply-all intentionally accepts weaker evidence and should not be treated as the default. A limited, interrupted, excluded, or otherwise incomplete traversal blocks apply modes.

Safety and privacy boundary

• The application changes files only in an explicit apply mode.
• Filename rollback does not restore overwritten embedded metadata; backups remain the recovery source.
• Enabled providers may receive artist/title, identifiers, fingerprints, duration, or release context needed for matching. No media file is uploaded by this code.
• Runtime configuration, logs, caches, reports, diagnostics, and media are excluded from version control.
• Use the project only with media you are authorized to inspect and modify.

See API and integration notes and operations for the implementation boundary.

Development

py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m compileall -q src scripts tests
.venv\Scripts\python -m pytest -q

The test suite uses controlled provider responses and temporary media fixtures. It does not require live API credentials.

Status

MediaTaggerBot v0.5.7 is a local application, not a managed metadata service. Review the configuration and dry-run output for your environment before any mutation.

License

Copyright © 2026 Gateway Information Group LLC. All rights reserved. Limited evaluation rights are described in LICENSE.md. Third-party packages and optional tools remain under their respective licenses.