Media Metadata Surgery v0.1.2

Precision-focused, fully offline CLI for viewing, editing, and stripping metadata from any media or document file.

The core engine is Go — fast, correct, zero dependencies. Distribution via pip.

What's new in v0.1.2

v0.1.1 supported only JPEG read-only.
v0.1.2 expands to 28 formats across 4 media categories:

Installation

pip install surgery

Or build from source (requires Go 1.21+):

git clone https://github.com/ankit-chaubey/media-metadata-surgery
cd media-metadata-surgery
go build -o surgery ./cli

Commands

view — read metadata

surgery view photo.jpg
surgery view --json audio.mp3
surgery view --verbose document.pdf

Output (JPEG):

File  : photo.jpg
Format: JPEG

── EXIF ──
  Make:                          vivo               [editable]
  Model:                         vivo T1 5G         [editable]
  DateTimeOriginal:              2026:02:04 18:44:10
  GPSLatitude:                   18 deg 20' 47.19"
  GPSLongitude:                  84 deg 25' 25.39"

── IPTC ──
  Keywords:                      travel, india

Output (MP3):

File  : song.mp3
Format: MP3

── ID3v2.4.0 ──
  Title:                         Bohemian Rhapsody    [editable]
  Artist:                        Queen                [editable]
  Album:                         A Night at the Opera [editable]
  Year:                          1975
  Genre:                         Rock

edit — update metadata

# Set fields (in-place)
surgery edit --set "Artist=John Doe" --set "Title=My Song" audio.mp3

# Write to new file
surgery edit --set "Make=Canon" --out edited.jpg photo.jpg

# Delete a field
surgery edit --delete UserComment photo.jpg

# Preview without writing
surgery edit --dry-run --set "Title=Report 2024" document.docx

Editable fields by format

strip — remove metadata

# Remove all metadata (in-place)
surgery strip photo.jpg

# Remove to new file
surgery strip --out clean.jpg photo.jpg

# Remove only GPS coordinates
surgery strip --gps-only photo.jpg

# Remove all EXCEPT EXIF
surgery strip --keep exif photo.jpg

# Preview
surgery strip --dry-run audio.mp3

Privacy use-case — strip location before uploading:

surgery strip --gps-only holiday_photo.jpg

info — detect format

surgery info video.mkv

File            : video.mkv
Detected Format : Matroska MKV  (id: mkv)
Media Type      : video
Can View        : true
Can Edit        : false
Can Strip       : false
Notes           : EBML-based container. View only in v0.1.2.

formats — list all formats

surgery formats
surgery formats --type audio

Format ID    Name                   Type        View  Edit  Strip  Extensions
──────────────────────────────────────────────────────────────────────────────
jpeg         JPEG                   image       ✓     ✓     ✓      .jpg .jpeg
png          PNG                    image       ✓     ✓     ✓      .png
mp3          MP3                    audio       ✓     ✓     ✓      .mp3
flac         FLAC                   audio       ✓     ✓     ✓      .flac
mp4          MP4                    video       ✓     ✓     ✓      .mp4
pdf          PDF                    document    ✓     ✓     ✓      .pdf
docx         DOCX                   document    ✓     ✓     ✓      .docx
...
             TOTAL                              28    9     13     (28 formats)

batch — process directories

# View all files
surgery batch view ./photos

# View recursively as JSON
surgery batch view --json --recursive ./media

# Strip all files, output to new directory
surgery batch strip --out ./clean ./photos

# Strip recursively in-place
surgery batch strip --recursive ./photos

# Apply copyright to all editable files
surgery batch edit --set "Copyright=ACME Corp 2024" ./docs

# Dry-run
surgery batch edit --dry-run --set "Author=Ankit" ./documents

Capability matrix

Security & privacy

• All operations are fully offline — no network access
• No background processes, no telemetry
• Viewing never modifies files
• --out always writes to a new file
• --dry-run previews changes before any write

Project structure

media-metadata-surgery/
├── cli/main.go              # Commands: view, edit, strip, info, formats, batch
├── core/
│   ├── types.go             # Handler interface, Metadata, MetaField, options
│   ├── detect.go            # Magic-byte + extension format detection (28 formats)
│   ├── output.go            # Text + JSON printer
│   ├── image/image.go       # JPEG/PNG/GIF/WebP/TIFF/BMP/HEIC/SVG handlers
│   ├── audio/audio.go       # MP3/FLAC/OGG/Opus/M4A/WAV/AIFF handlers
│   ├── video/video.go       # MP4/MOV/MKV/WebM/AVI/WMV/FLV handlers
│   └── document/document.go # PDF/DOCX/XLSX/PPTX/ODT/EPUB handlers
├── surgery/
│   ├── __init__.py
│   ├── __main__.py
│   └── bin/surgery          # Compiled binary (bundled at release)
├── go.mod / go.sum
├── setup.py / pyproject.toml
└── README.md

License

Apache License 2.0

Author

Ankit Chaubey — https://github.com/ankit-chaubey

Philosophy

Precision over features. Correctness over speed. Transparency over magic.