Phonic #

A unified audio metadata tagging library for Dart that provides a format-agnostic interface for reading and writing audio metadata tags across different container formats. Work with MP3, FLAC, OGG, Opus, and MP4 files using a single, consistent API without needing to understand the complexities of ID3, Vorbis Comments, or MP4 atoms.

✨ Key Features #

• 🎵 Format Agnostic - Unified API across ID3v1, ID3v2.x, Vorbis Comments, MP4 atoms
• 🖼️ Smart Artwork - Lazy loading and memory-optimized image handling
• ⚡ Performance - Streaming operations for large collections
• 🔧 Type Safe - Strong typing with Dart enums and sealed classes
• 🛡️ Robust - Comprehensive error handling and validation
• 📊 Capability Aware - Format-specific constraint handling

📦 Supported Formats #

🔧 Installation #

Add phonic to your pubspec.yaml:

dependencies:
  phonic: <latest>

📖 Quick Start #

import 'package:phonic/phonic.dart';

// Load and read metadata
final audioFile = await Phonic.fromFile('song.mp3');
final title = audioFile.getTag(TagKey.title);
print('Title: ${title?.value}');

// Modify and save
audioFile.setTag(TitleTag('New Title'));
final updatedBytes = await audioFile.encode();
await File('updated_song.mp3').writeAsBytes(updatedBytes);

audioFile.dispose();

📚 Documentation #

Core Topics #

• Getting Started - Installation, setup, and basic usage
• Tag Management - Working with metadata fields and tag operations
• Artwork Handling - Embedded images, optimization, and lazy loading
• Streaming Operations - Batch processing and memory efficiency
• Error Handling - Exception handling and validation patterns

Advanced Topics #

• Tag Provenance - Track metadata origin and reliability
• Tag Normalization - Data cleaning and standardization
• Automatic Tag Conversion - Cross-format conversion details
• Supported Formats - Format capabilities and constraints
• Best Practices - Performance optimization and usage patterns

Reference #

• Tag Keys Reference - Complete metadata field reference
• Examples - Real-world use cases and integration patterns

🤝 Contributing #

We welcome contributions! Areas where help is needed:

• Additional format support (FLAC, OGG, MP4)
• Testing and bug fixes
• Documentation improvements
• Performance optimizations

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

Phonic - Because metadata should be simple, not format-dependent.