[Feature]: Native Windows Binary for ID3v2 Tool (FLAC ID3v2 Support on Windows)

[Andreas-Garcia]

Feature Description

Provide native Windows support for writing ID3v2 metadata tags to FLAC files without requiring WSL (Windows Subsystem for Linux).

Currently, the id3v2 command-line tool is not available as a native Windows binary, which prevents writing ID3v2 metadata tags to FLAC files on Windows without WSL. This limitation affects Windows users, CI pipelines, and local development.

Problem Statement

Current Issues:

• Writing ID3v2 tags to FLAC files fails on Windows without WSL installed
• Users encounter FileCorruptedError when attempting to write ID3v2 metadata to FLAC files
• Windows CI only runs e2e tests (unit/integration tests skipped) due to missing id3v2 tool
• Local Windows development requires complex WSL setup for full test coverage

Technical Background:

1. Mutagen limitation: The mutagen Python library's ID3 class corrupts FLAC file structure when writing ID3v2 tags, causing "Not a valid FLAC file" errors
2. External tool requirement: FLAC files require external tools (id3v2 or mid3v2) to properly handle FLAC's metadata block structure
3. Format-specific: This only affects FLAC files with ID3v2 tags; MP3 files work fine with mutagen

Current Workaround Issues:

The installation script (scripts/install-system-dependencies-windows.ps1) attempts to install id3v2 via WSL, but this approach has significant limitations:

• ❌ Requires system restart in most cases (not possible in CI)
• ❌ Complex setup (DISM configuration, Ubuntu distribution setup)
• ❌ Often fails in CI environments
• ❌ WSL installation attempts frequently fail due to restart requirements
• ❌ Manual WSL setup often required even after script execution

Error Example:

from audiometa import update_metadata, UnifiedMetadataKey, MetadataFormat

# This will fail on Windows without WSL:
update_metadata(
    "file.flac",
    {UnifiedMetadataKey.TITLE: "Test Title"},
    metadata_format=MetadataFormat.ID3V2
)
# Raises: FileCorruptedError: External tool id3v2 not found...

Proposed Solution

Option 1: Native Windows Binary (Preferred)

• Research if a native Windows build of id3v2 exists or can be created
• Evaluate mid3v2 (mutagen-tools) as a Windows-compatible alternative
• Bundle or provide Windows-specific installation instructions for native binary
• Pros: No WSL dependency, simpler installation, works in CI
• Cons: May require building/maintaining Windows binaries

Implementation considerations:

• Investigate if mid3v2 from mutagen-tools works on Windows natively
• If needed, explore building id3v2 as a native Windows executable
• Update scripts/install-system-dependencies-windows.ps1 to use native binary
• Ensure CI compatibility for full test coverage on Windows

Alternatives Considered

Option 2: Pure Python Implementation

• Research if mutagen can be fixed or if a pure Python FLAC ID3v2 writer can be implemented
• Pros: No external dependencies, cross-platform
• Cons: Significant development effort, may not match external tool reliability

Option 3: Improve WSL Installation

• Enhance WSL installation script reliability
• Better documentation for manual WSL setup
• Pre-install WSL in CI runners
• Pros: Uses existing tool, minimal code changes
• Cons: Still requires WSL, complex setup, restart requirements

Option 4: Alternative Tool for Windows

• Find Windows-compatible alternatives to id3v2/mid3v2
• Examples: PowerShell scripts, Windows-native tag editors
• Pros: Native Windows support
• Cons: May require significant code changes

### Feature Scope

Metadata Format Support (ID3v1, ID3v2, Vorbis, RIFF)

### Use Case

```python
# Current behavior on Windows (without WSL) - FAILS:
from audiometa import update_metadata, UnifiedMetadataKey, MetadataFormat

update_metadata(
    "test.flac",
    {UnifiedMetadataKey.TITLE: "Test Title"},
    metadata_format=MetadataFormat.ID3V2
)
# Raises: FileCorruptedError: External tool id3v2 not found...

# Desired behavior - WORKS on all platforms including Windows:
from audiometa import update_metadata, UnifiedMetadataKey, MetadataFormat

update_metadata(
    "test.flac",
    {UnifiedMetadataKey.TITLE: "Test Title"},
    metadata_format=MetadataFormat.ID3V2
)
# Successfully writes ID3v2 tags to FLAC file on Windows (no WSL required)
`

Compatibility Considerations

• This feature would require changes to existing API
• This feature would be backward compatible
• This feature would require new dependencies
• This feature would require external tools

Additional Context

**Related Code:**

- Installation script: `scripts/install-system-dependencies-windows.ps1` (lines 125-348)
- ID3v2 manager: `audiometa/manager/_rating_supporting/id3v2/_Id3v2Manager.py` (lines 712-811)
- Dependency config: `system-dependencies-prod.toml` (lines 55-63)
- Documentation: `README.md` (lines 220-223)

**References:**

- [ID3v2 specification](https://id3.org/id3v2.3.0)
- [Mutagen documentation](https://mutagen.readthedocs.io/)
- [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install)
- [id3v2 tool source](https://id3v2.sourceforge.net/)

**Impact Details:**

- **Affected formats**: FLAC files with ID3v2 tags only
- **MP3 files**: Work correctly (use mutagen directly)
- **Other formats**: Not affected (use format-specific tools)
- **Reading metadata**: Works fine (uses mutagen for reading)
- **Writing metadata**: Fails for FLAC + ID3v2 combination on Windows without WSL

**Environment:**

- **OS**: Windows (all versions)
- **Python**: All supported versions
- **Library version**: All versions
- **WSL**: Not installed (or installation failed)

**Priority**: Medium-High - Affects Windows users trying to write ID3v2 tags to FLAC files, but workaround exists (WSL) and MP3 files work fine.