[Feature]: Add OGG Audio Format Support" labels

[Andreas-Garcia]

Feature Description

Add support for reading and writing metadata from OGG audio files (.ogg extension). OGG files use Vorbis comments for metadata, which is already partially implemented in the codebase for FLAC files. This feature would extend the existing Vorbis metadata manager to support OGG file structure and add OGG to the list of supported audio formats.

Problem Statement

Currently, AudioMeta supports MP3, FLAC, and WAV files, but OGG files are not supported. When users try to read or write metadata from OGG files, they receive a FileTypeNotSupportedError. OGG is a popular open-source audio format commonly used for music and podcasts, and many users have OGG files in their collections that they cannot manage with AudioMeta.

The CHANGELOG.md already mentions "OGG file support is planned but not yet implemented" for the Vorbis format, indicating this is a planned feature.

Proposed Solution

Extend the existing Vorbis metadata manager and add OGG file format support:

1. File Format Registration:

   • Add .ogg extension to MetadataFormat.get_priorities() with Vorbis as the primary metadata format
   • Update _AudioFile validation to accept .ogg files
   • Add OGG file validation (check for OGG page structure)

2. Vorbis Manager Extensions:

   • Extend _VorbisManager to handle OGG file structure (OGG pages vs FLAC blocks)
   • Update _extract_mutagen_metadata() to parse Vorbis comments from OGG files
   • Modify metadata writing to use appropriate tools for OGG (mutagen or vorbiscomment tool)
   • Handle OGG-specific file structure differences from FLAC

3. Technical Information:

   • Add OGG support to get_duration_in_sec() in _AudioFile
   • Add OGG support for bitrate, sample rate, and channels extraction
   • Update get_audio_format_name() to return "OGG" for .ogg files

4. External Tools:

   • Document requirements for OGG support (mutagen already supports OGG)
   • Consider using vorbiscomment tool for writing (similar to how metaflac is used for FLAC)
   • Ensure proper tool detection and error handling

5. Documentation Updates:

   • Update README.md to include OGG in supported formats tables
   • Update CHANGELOG.md to reflect OGG support
   • Update format capability documentation
   • Update error handling guide to include OGG examples

6. Testing:

   • Add unit tests for OGG file validation
   • Add integration tests for reading/writing OGG metadata
   • Add tests for technical info extraction from OGG files
   • Add E2E tests for complete OGG workflows
   • Create test fixtures with sample OGG files

Alternatives Considered

1. Separate OGG Manager: Create a dedicated _OggManager class instead of extending _VorbisManager. Rejected because OGG uses Vorbis comments, so sharing the Vorbis manager logic makes more sense.

2. Using Only Mutagen: Rely entirely on mutagen for both reading and writing. Rejected because the current implementation uses external tools (metaflac) for FLAC to preserve proper key casing and avoid corruption. Similar approach should be considered for OGG.

3. Deferring OGG Support: Wait until more formats are requested. Rejected because OGG is a common format and the infrastructure (Vorbis comments) is already partially implemented.

Feature Scope

Metadata Format Support (ID3v1, ID3v2, Vorbis, RIFF) - Specifically extending Vorbis support to OGG files

Audio Format Support (MP3, FLAC, WAV) - Adding OGG as a new supported audio format

Use Case

from audiometa import get_unified_metadata, update_metadata, get_duration_in_sec
from audiometa.utils.metadata_format import MetadataFormat

# Read metadata from OGG file
metadata = get_unified_metadata("song.ogg")
print(metadata.get(UnifiedMetadataKey.TITLE))  # "Song Title"
print(metadata.get(UnifiedMetadataKey.ARTISTS))  # ["Artist Name"]

# Write metadata to OGG file
update_metadata("song.ogg", {
    UnifiedMetadataKey.TITLE: "New Title",
    UnifiedMetadataKey.ARTISTS: ["New Artist"],
    UnifiedMetadataKey.ALBUM: "New Album"
}, metadata_format=MetadataFormat.VORBIS)

# Get technical information
duration = get_duration_in_sec("song.ogg")
print(f"Duration: {duration} seconds")

# Read only Vorbis metadata from OGG
vorbis_metadata = get_unified_metadata("song.ogg", metadata_format=MetadataFormat.VORBIS)

Compatibility Considerations

• This feature would be backward compatible
• This feature would require new dependencies (no new Python dependencies - mutagen already supports OGG)
• This feature would require external tools (potentially vorbiscomment tool, similar to metaflac for FLAC)

Backward Compatibility: Adding OGG support is fully backward compatible. Existing code will continue to work unchanged. The only change is that .ogg files will no longer raise FileTypeNotSupportedError.

Dependencies: No new Python dependencies required. Mutagen (already a dependency) supports OGG files.

External Tools: May require vorbiscomment tool for writing metadata (similar to how metaflac is used for FLAC). This should be documented in system dependencies and installation instructions.

Additional Context

Current State

• Vorbis metadata format is already implemented for FLAC files
• _VorbisManager exists and handles Vorbis comments
• The manager currently uses custom FLAC parsing and metaflac tool for writing
• OGG files use the same Vorbis comment format but have a different file structure (OGG pages vs FLAC blocks)

Technical Considerations

1. File Structure Differences:

   • FLAC uses metadata blocks (STREAMINFO, VORBIS_COMMENT, etc.)
   • OGG uses pages with packet structure
   • Vorbis comments are embedded differently in each format

2. Reading Metadata:

   • Mutagen can read OGG Vorbis comments, but may not preserve key casing (similar to FLAC)
   • May need custom parsing for OGG pages to preserve original key casing
   • Or use mutagen with case-insensitive handling (already implemented)

3. Writing Metadata:

   • Option 1: Use mutagen directly (simpler, but may have casing issues)
   • Option 2: Use vorbiscomment external tool (similar to metaflac approach)
   • Option 3: Custom OGG page manipulation (complex, may cause corruption)

4. File Validation:

   • OGG files start with "OggS" magic bytes
   • Need to validate OGG page structure
   • Handle corrupted or invalid OGG files gracefully

Implementation Steps

1. Add .ogg extension support in metadata_format.py
2. Update _AudioFile to validate OGG files
3. Extend _VorbisManager to detect and handle OGG files
4. Implement OGG-specific reading (using mutagen or custom parsing)
5. Implement OGG-specific writing (using mutagen or vorbiscomment)
6. Add technical info extraction for OGG files
7. Add comprehensive tests
8. Update documentation

Related Code Locations

• audiometa/utils/metadata_format.py - Add .ogg to priorities
• audiometa/_audio_file.py - Add OGG validation and technical info
• audiometa/manager/_rating_supporting/vorbis/_VorbisManager.py - Extend for OGG support
• audiometa/test/helpers/vorbis/ - May need OGG-specific test helpers
• README.md - Update supported formats tables
• CHANGELOG.md - Document OGG support addition
• docs/ERROR_HANDLING_GUIDE.md - Add OGG examples

References

• OGG Container Format Specification
• Vorbis Comment Specification
• Mutagen documentation for OGG support
• Current FLAC Vorbis implementation as reference

[github-actions]

👋 Welcome to AudioMeta Python! Thank you for opening an issue.

Please make sure you've:

• Checked the README for documentation
• Searched existing issues to see if this has been reported
• Used the appropriate issue template

We'll review your issue and get back to you soon!