Skip to content

Latest commit

 

History

History
44 lines (29 loc) · 2.43 KB

CLAUDE.md

File metadata and controls

44 lines (29 loc) · 2.43 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

mutant-note is a Python CLI tool for modifying audio file metadata using the Mutagen library. It provides an interactive terminal interface (via questionary) for editing tags on various audio formats, with optional format conversion via FFmpeg and automatic metadata lookup from TheAudioDB.

Running

# Activate venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows (repo was originally developed on Windows)

# Install dependencies
pip install -r requirements.txt

# Run the app
python app.py

FFmpeg must be installed and available on PATH for format conversion and WAV metadata writing.

Architecture

Three source files, no build step, no test suite:

  • app.py — Entry point and interactive CLI flow. Handles the menu loop, user prompts (single file vs album, batch vs per-file, manual vs automatic), format conversion via FFmpeg, and metadata retrieval from TheAudioDB API (https://www.theaudiodb.com/api/v1/json/123).

  • constants.py — All configuration data: supported file extensions, per-extension metadata capability maps (metadata_by_file_extension), metadata field names/labels (info_list/info_list_labels), empty metadata template (empty_info), and UI constants.

  • utils.py — Metadata writing logic. setMetadata() dispatches by extension to format-specific writers. Each format family has its own tag-mapping dict and setter function:

    • ID3 (MP3, WAV, AIF/AIFF) — setID3Tags() shared helper, used by setID3Metadata(), setWavMetadata(), setAIFMetadata()
    • Vorbis (FLAC, OGG, Opus) — simple_vorbis_map shared, setOggTags() shared helper for OGG/Opus, separate setFlacMetadata()
    • MP4 (MP4, M4A, M4B, M4P, M4V, 3GP) — simple_mp4_map, setMP4Metadata()
    • ASF (ASF, WMA, WMV) — asf_map, setASFMetadata()

Key patterns

  • Adding a new audio format requires changes in three places: file_extensions_supported and metadata_by_file_extension in constants.py, and a new case in setMetadata() in utils.py.
  • Cover art is always expected as JPEG (.jpg). Validated in app.py:validateJPGForCover.
  • Lyrics are read from a text file path, not inline text.
  • WAV metadata writing requires an FFmpeg round-trip (touchWav) to produce a WAV structure Mutagen can tag.