mp3tagconv

A C library and CLI tool for converting MP3 ID3 tag encodings to UTF-8.

Automatically detects source encodings (EUC-KR, CP949, etc.) and converts garbled tags to proper UTF-8. Handles both ID3v1 and ID3v2 tags, with mojibake recovery for tags that were misencoded through Latin-1.

Features

• Automatic encoding detection via uchardet
• Two-pass encoding hint propagation for short fields that uchardet misdetects
• Mojibake recovery (UTF-8 → Latin-1 → original encoding → UTF-8)
• ID3v1.0/v1.1 and ID3v2.2/v2.3/v2.4 support (always writes ID3v2.4)
• Automatic v2.2/v2.3 to v2.4 upgrade on write
• Non-destructive by default (dry-run preview)
• Optional .bak backup before writing

Building

cmake -B build
cmake --build build

Dependencies

• uchardet - encoding detection
• iconv (glibc) - character conversion
• cmocka - unit tests (optional)
• CMake 3.14+, pkg-config, C11 compiler

On Debian/Ubuntu:

sudo apt install libuchardet-dev libcmocka-dev cmake pkg-config

Running tests

ctest --test-dir build

Usage

mp3tagconv [OPTIONS] [FILE ...]

Options

Option	Description
-e, --encoding ENC	Force source encoding (e.g. EUC-KR, CP949)
-w, --write	Write changes (default: dry-run preview)
-b, --no-backup	Don't create .bak files when writing
-m, --no-mojibake	Disable mojibake recovery
-v, --verbose	Increase verbosity (repeat for more)
-s, --stdin	Read MP3 data from stdin
-h, --help	Show help

If no files are given and --stdin is not set, reads file paths from stdin (one per line).

Examples

Preview tag conversions (dry-run):

mp3tagconv song.mp3

Convert and write changes with backup:

mp3tagconv -w song.mp3

Force a specific source encoding:

mp3tagconv -w -e EUC-KR song.mp3

Process multiple files from a directory:

find ~/music -name '*.mp3' | mp3tagconv -w

Library API

#include <mp3tagconv/converter.h>

m3tc_options opts;
m3tc_options_init(&opts);

m3tc_result result;
m3tc_convert_file("song.mp3", &opts, &result);

// Inspect result.v1_fields[], result.v2_fields[]
// Each field has: status, detected_enc, converted (UTF-8 string)

m3tc_result_free(&result);

License

MIT