fix: Surface unified Tag view over all metadata sources (#6)

src/TagLibSharp2/Core/CombinedTag.cs

@@ -0,0 +1,144 @@
+// Copyright (c) 2025-2026 Stephen Shaw and contributors
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+namespace TagLibSharp2.Core;
+
+/// <summary>
+/// A tag facade that exposes a unified view over multiple underlying <see cref="Tag"/>
+/// instances in priority order.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Getters return the first non-null/non-empty value from the ordered list of tags.
+/// Pictures are unioned across members and deduplicated on (PictureType, MimeType,
+/// PictureData).
+/// </para>
+/// <para>
+/// Writes are no-ops on this base facade; callers wanting mutation should operate
+/// on the underlying tags directly. Format-specific subclasses (e.g. the FLAC tag
+/// view) override individual members to forward writes to the appropriate storage.
+/// </para>
+/// <para>
+/// The motivating case is an MP3 file that carries both an ID3v2 tag
+/// (https://id3.org/id3v2.4.0-structure) and an ID3v1 tag (https://id3.org/ID3v1).
+/// ID3v2 is authoritative when both are present, but ID3v1-only fields must still
+/// surface through the unified view so legacy data is not silently lost.
+/// </para>
+/// </remarks>
+public class CombinedTag : Tag
+{
+	readonly Tag?[] _tags;
+
+	/// <summary>
+	/// Initializes a new <see cref="CombinedTag"/> with the supplied tags in
+	/// priority order. The first non-null tag's value wins for each field.
+	/// </summary>
+	/// <param name="tags">Tags in priority order. Null entries are allowed and ignored.</param>
+	public CombinedTag (params Tag?[] tags)
+	{
+		_tags = tags ?? [];
+	}
+
+	/// <summary>
+	/// Gets the underlying tags in priority order. Null entries are preserved.
+	/// </summary>
+	protected IReadOnlyList<Tag?> Tags => _tags;
+
+	T? FirstNonDefault<T> (Func<Tag, T?> selector, Func<T?, bool> isDefault)
+	{
+		foreach (var tag in _tags) {
+			if (tag is null)
+				continue;
+			var value = selector (tag);
+			if (!isDefault (value))
+				return value;
+		}
+		return default;
+	}
+
+	string? FirstNonEmptyString (Func<Tag, string?> selector) =>
+		FirstNonDefault (selector, string.IsNullOrEmpty);
+
+	uint? FirstNonNullUInt (Func<Tag, uint?> selector) =>
+		FirstNonDefault<uint?> (selector, v => !v.HasValue);
+
+	/// <inheritdoc/>
+	public override TagTypes TagType {
+		get {
+			var types = TagTypes.None;
+			foreach (var tag in _tags) {
+				if (tag is not null)
+					types |= tag.TagType;
+			}
+			return types;
+		}
+	}
+
+	/// <inheritdoc/>
+	public override string? Title {
+		get => FirstNonEmptyString (t => t.Title);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override string? Artist {
+		get => FirstNonEmptyString (t => t.Artist);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override string? Album {
+		get => FirstNonEmptyString (t => t.Album);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override string? Year {
+		get => FirstNonEmptyString (t => t.Year);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override string? Comment {
+		get => FirstNonEmptyString (t => t.Comment);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override string? Genre {
+		get => FirstNonEmptyString (t => t.Genre);
+		set { }
+	}
+
+	/// <inheritdoc/>
+	public override uint? Track {
+		get => FirstNonNullUInt (t => t.Track);
+		set { }
+	}
+
+	/// <inheritdoc/>
+#pragma warning disable CA1819 // Properties should not return arrays - Tag API contract
+	public override IPicture[] Pictures {
+		get {
+			var merged = new List<IPicture> ();
+			var seen = new HashSet<(PictureType, string, BinaryData)> ();
+			foreach (var tag in _tags) {
+				if (tag is null)
+					continue;
+				foreach (var p in tag.Pictures) {
+					if (seen.Add ((p.PictureType, p.MimeType, p.PictureData)))
+						merged.Add (p);
+				}
+			}
+			return [.. merged];
+		}
+		set { }
+	}
+#pragma warning restore CA1819
+
+	/// <inheritdoc/>
+	public override BinaryData Render () => BinaryData.Empty;
+
+	/// <inheritdoc/>
+	public override void Clear () { }
+}

src/TagLibSharp2/Core/MediaFile.cs

@@ -386,7 +386,7 @@ static MediaFileResult OpenFlac (ReadOnlyMemory<byte> data)
 		if (!result.IsSuccess)
 			return MediaFileResult.Failure (result.Error!);
 
-		return MediaFileResult.Success (result.File!, result.File!.VorbisComment, MediaFormat.Flac);
+		return MediaFileResult.Success (result.File!, result.File!.Tag, MediaFormat.Flac);
 	}
 
 	static MediaFileResult OpenOggVorbis (ReadOnlyMemory<byte> data)
@@ -413,11 +413,7 @@ static MediaFileResult OpenMp3 (ReadOnlyMemory<byte> data)
 		if (!result.IsSuccess)
 			return MediaFileResult.Failure (result.Error!);
 
-		// Prefer ID3v2 tag, fall back to ID3v1
-		Tag? tag = result.File!.Id3v2Tag is not null
-			? result.File.Id3v2Tag
-			: result.File.Id3v1Tag;
-		return MediaFileResult.Success (result.File, tag, MediaFormat.Mp3);
+		return MediaFileResult.Success (result.File!, result.File!.Tag, MediaFormat.Mp3);
 	}
 
 	static MediaFileResult OpenWav (ReadOnlyMemory<byte> data)

src/TagLibSharp2/Mpeg/Mp3File.cs

@@ -88,7 +88,7 @@ public sealed class Mp3File : IMediaFile
 	public bool HasId3v2Tag => Id3v2Tag is not null;
 
 	/// <inheritdoc />
-	public Tag? Tag => (Tag?)Id3v2Tag ?? Id3v1Tag;
+	public Tag? Tag => new CombinedTag (Id3v2Tag, Id3v1Tag);
 
 	/// <inheritdoc />
 	IMediaProperties? IMediaFile.AudioProperties => Properties;

src/TagLibSharp2/Xiph/FlacFile.cs

@@ -271,8 +271,10 @@ public string? Comment {
 	/// </summary>
 	public AudioProperties Properties { get; }
 
+	FlacTag? _tag;
+
 	/// <inheritdoc />
-	public Tag? Tag => VorbisComment;
+	public Tag? Tag => _tag ??= new FlacTag (this);
 
 	/// <inheritdoc />
 	IMediaProperties? IMediaFile.AudioProperties => Properties;

src/TagLibSharp2/Xiph/FlacTag.cs

@@ -0,0 +1,119 @@
+// Copyright (c) 2025-2026 Stephen Shaw and contributors
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+using TagLibSharp2.Core;
+
+namespace TagLibSharp2.Xiph;
+
+/// <summary>
+/// Unified tag view over a <see cref="FlacFile"/>'s metadata.
+/// </summary>
+/// <remarks>
+/// <para>
+/// FLAC can store pictures in two spec-defined locations:
+/// </para>
+/// <list type="bullet">
+///   <item>Native PICTURE metadata blocks (block type 6), per RFC 9639 §8.8.</item>
+///   <item>METADATA_BLOCK_PICTURE fields inside the VORBIS_COMMENT block (base64-encoded),
+///     per https://wiki.xiph.org/VorbisComment#METADATA_BLOCK_PICTURE.</item>
+/// </list>
+/// <para>
+/// This class provides a single Tag view that surfaces both so callers do not need
+/// to know FLAC's internal storage layout.
+/// </para>
+/// </remarks>
+public sealed class FlacTag : Tag
+{
+	readonly FlacFile _file;
+
+	internal FlacTag (FlacFile file)
+	{
+		_file = file;
+	}
+
+	/// <inheritdoc/>
+	public override TagTypes TagType => TagTypes.Xiph | TagTypes.FlacMetadata;
+
+	/// <inheritdoc/>
+	public override string? Title {
+		get => _file.VorbisComment?.Title;
+		set => EnsureVorbisComment ().Title = value;
+	}
+
+	/// <inheritdoc/>
+	public override string? Artist {
+		get => _file.VorbisComment?.Artist;
+		set => EnsureVorbisComment ().Artist = value;
+	}
+
+	/// <inheritdoc/>
+	public override string? Album {
+		get => _file.VorbisComment?.Album;
+		set => EnsureVorbisComment ().Album = value;
+	}
+
+	/// <inheritdoc/>
+	public override string? Year {
+		get => _file.VorbisComment?.Year;
+		set => EnsureVorbisComment ().Year = value;
+	}
+
+	/// <inheritdoc/>
+	public override string? Comment {
+		get => _file.VorbisComment?.Comment;
+		set => EnsureVorbisComment ().Comment = value;
+	}
+
+	/// <inheritdoc/>
+	public override string? Genre {
+		get => _file.VorbisComment?.Genre;
+		set => EnsureVorbisComment ().Genre = value;
+	}
+
+	/// <inheritdoc/>
+	public override uint? Track {
+		get => _file.VorbisComment?.Track;
+		set => EnsureVorbisComment ().Track = value;
+	}
+
+	VorbisComment EnsureVorbisComment () =>
+		_file.VorbisComment ??= new VorbisComment ("TagLibSharp2");
+
+	/// <inheritdoc/>
+#pragma warning disable CA1819 // Properties should not return arrays - Tag API contract
+	public override IPicture[] Pictures {
+		get {
+			var blockPictures = _file.Pictures;
+			var embedded = _file.VorbisComment?.Pictures ?? [];
+			var merged = new List<IPicture> (blockPictures.Count + embedded.Length);
+			var seen = new HashSet<(PictureType, string, BinaryData)> ();
+			foreach (var p in blockPictures) {
+				if (seen.Add ((p.PictureType, p.MimeType, p.PictureData)))
+					merged.Add (p);
+			}
+			foreach (var p in embedded) {
+				if (seen.Add ((p.PictureType, p.MimeType, p.PictureData)))
+					merged.Add (p);
+			}
+			return [.. merged];
+		}
+		set {
+			_file.RemoveAllPictures ();
+			_file.VorbisComment?.RemoveAllPictures ();
+			if (value is null)
+				return;
+			foreach (var p in value) {
+				var flacPic = p as FlacPicture ?? new FlacPicture (
+					p.MimeType, p.PictureType, p.Description, p.PictureData, 0, 0, 0, 0);
+				_file.AddPicture (flacPic);
+			}
+		}
+	}
+#pragma warning restore CA1819
+
+	/// <inheritdoc/>
+	public override BinaryData Render () => BinaryData.Empty;
+
+	/// <inheritdoc/>
+	public override void Clear () { }
+}

tests/TagLibSharp2.Tests/Core/CombinedTagTests.cs

@@ -0,0 +1,71 @@
+// Copyright (c) 2025-2026 Stephen Shaw and contributors
+// Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+using TagLibSharp2.Core;
+using TagLibSharp2.Id3;
+using TagLibSharp2.Id3.Id3v2;
+
+namespace TagLibSharp2.Tests.Core;
+
+/// <summary>
+/// Tests for <see cref="CombinedTag"/> — a Tag facade that exposes a unified view
+/// over multiple underlying Tag instances in a well-defined priority order.
+/// </summary>
+/// <remarks>
+/// The motivating case is an MP3 file that contains both an ID3v2 tag and an
+/// ID3v1 tag. Per the ID3v1 specification (https://id3.org/ID3v1), ID3v1 has
+/// strict field length limits (title/artist/album capped at 30 bytes, year at
+/// 4 bytes, etc.). ID3v2 has no such limits. When both are present, taggers
+/// generally treat ID3v2 as authoritative and ID3v1 as a legacy-compat copy,
+/// so reads must prefer ID3v2 and fall back to ID3v1 for fields missing in v2.
+/// </remarks>
+[TestClass]
+[TestCategory ("Unit")]
+[TestCategory ("Core")]
+public class CombinedTagTests
+{
+	/// <summary>
+	/// When the primary tag has a field value, that value wins regardless of what
+	/// later tags hold. This implements the "ID3v2 is authoritative" convention.
+	/// </summary>
+	[TestMethod]
+	public void Title_PrimaryTagValueWinsOverSecondary ()
+	{
+		var primary = new Id3v2Tag { Title = "From Primary" };
+		var secondary = new Id3v1Tag { Title = "From Secondary" };
+
+		var combined = new CombinedTag (primary, secondary);
+
+		Assert.AreEqual ("From Primary", combined.Title);
+	}
+
+	/// <summary>
+	/// When the primary tag does not have a value for a field, the combined tag
+	/// falls back to later tags. This prevents ID3v1-only information (typical
+	/// for files tagged prior to widespread ID3v2 adoption) from being lost.
+	/// </summary>
+	[TestMethod]
+	public void Title_FallsBackToSecondaryWhenPrimaryIsEmpty ()
+	{
+		var primary = new Id3v2Tag ();
+		var secondary = new Id3v1Tag { Title = "Only In Secondary" };
+
+		var combined = new CombinedTag (primary, secondary);
+
+		Assert.AreEqual ("Only In Secondary", combined.Title);
+	}
+
+	/// <summary>
+	/// A null tag in the priority list is skipped. This supports the common
+	/// case where a file is being read and one of the tag blocks is absent.
+	/// </summary>
+	[TestMethod]
+	public void Title_SkipsNullTagsInPriorityList ()
+	{
+		var secondary = new Id3v1Tag { Title = "From Secondary" };
+
+		var combined = new CombinedTag (null, secondary);
+
+		Assert.AreEqual ("From Secondary", combined.Title);
+	}
+}