TagValidationException class final

Exception thrown when tag validation fails due to constraint violations.

This exception is raised when the Phonic library detects that a tag value violates the constraints or capabilities of a target container format. This can occur when:

• Text fields exceed maximum length limits (e.g., ID3v1's 30-character limit)
• Numeric values fall outside allowed ranges (e.g., rating not in 0-100 range)
• Required fields are missing or empty when they shouldn't be
• Field formats don't match expected patterns (e.g., invalid ISO-8601 dates)
• Container format doesn't support the specified tag type
• Multi-valued tags are used with single-value-only containers

The exception includes the specific tagKey that failed validation and a reason describing why the validation failed, making it easy to identify and correct the problematic data.

Usage Examples

Basic Exception Creation

throw TagValidationException(
  TagKey.title,
  'Title exceeds maximum length of 30 characters for ID3v1',
  context: 'value: "This is a very long title that exceeds the limit"'
);

Exception Handling by Tag Type

try {
  audioFile.setTag(RatingTag(150)); // Invalid rating > 100
} on TagValidationException catch (e) {
  if (e.tagKey == TagKey.rating) {
    print('Rating validation failed: ${e.reason}');
    // Provide corrected value
    audioFile.setTag(RatingTag(100));
  }
} on PhonicException catch (e) {
  // Handle other Phonic exceptions
  print('Other error: ${e.message}');
}

Validation Error Logging

void logValidationError(TagValidationException e) {
  logger.warning('Tag validation failed for ${e.tagKey}: ${e.reason}');
  if (e.context != null) {
    logger.debug('Validation context: ${e.context}');
  }
}

Batch Validation with Error Collection

List<TagValidationException> validateTags(List<MetadataTag> tags) {
  final errors = <TagValidationException>[];

  for (final tag in tags) {
    try {
      validateTag(tag);
    } on TagValidationException catch (e) {
      errors.add(e);
    }
  }

  return errors;
}

Container-Specific Validation

void validateForId3v1(MetadataTag tag) {
  if (tag is TitleTag && tag.value.length > 30) {
    throw TagValidationException(
      TagKey.title,
      'Title length ${tag.value.length} exceeds ID3v1 limit of 30 characters',
      context: 'container: ID3v1, value: "${tag.value}"'
    );
  }
}

Error Recovery

When catching TagValidationException, applications should:

1. Log the validation error with tag key and reason for debugging
2. Determine if the value can be automatically corrected (truncation, clamping)
3. Provide user feedback about which fields need correction
4. Offer suggestions for valid values or formats
5. Consider skipping problematic tags while preserving others

Common Validation Scenarios

Length Constraints

• ID3v1: 30 characters for most text fields, 28 for comment with track
• ID3v2: Generally unlimited, but some implementations have practical limits
• Vorbis: No strict limits, but very large values may cause issues
• MP4: Varies by atom type, generally generous limits

Value Range Constraints

• Rating: Must be 0-100 (normalized from format-specific ranges)
• Track/Disc Numbers: Must be positive integers
• BPM: Must be positive, typically 1-999
• Year: Should be reasonable 4-digit year (e.g., 1900-2100)

Format Constraints

• Date Fields: Must be valid ISO-8601 format for dateRecorded
• ISRC: Must match ISRC format pattern (CC-XXX-YY-NNNNN)
• Genre: Some formats have predefined genre lists

Container Support Constraints

• ID3v1: Limited field support (no BPM, lyrics, artwork, etc.)
• Multi-valued: Some containers don't support multiple values for certain fields
• Custom Fields: Not all containers support custom/freeform fields

Thread Safety

TagValidationException instances are immutable and thread-safe.