Added support for chapters by implementing the frames CHAP and CTOC (#228)

* Added support for chapters by implementing the frames CHAP and CTOC from the spec addendum at https://id3.org/id3v2-chapters-1.0.

* Added the ICloneable overrides for CHAP and CTOC.

Author: JanRomero

src/TaglibSharp/ByteVector.cs

@@ -1532,7 +1532,7 @@ public string ToString (StringType type)
 		/// </returns>
 		public override string ToString ()
 		{
-			return ToString (StringType.UTF8);
+			return ToString (StringType.UTF8, 0, Count);
 		}
 
 		/// <summary>

src/TaglibSharp/Id3v2/FrameFactory.cs

@@ -139,7 +139,7 @@ public static Frame CreateFrame (ByteVector data, File file, ref int offset, byt
 				position = offset;
 			}
 
-			// If the next data is position is 0, assume
+			// If the next data in position is 0, assume
 			// that we've hit the padding portion of the
 			// frame data.
 
@@ -162,8 +162,8 @@ public static Frame CreateFrame (ByteVector data, File file, ref int offset, byt
 			}
 
 			if (alreadyUnsynched) {
-				// Mark the frame as not Unsynchronozed because the entire
-				// tag has already been Unsynchronized
+				// Mark the frame as not unsynchronized because the entire
+				// tag has already been unsynchronized
 				header.Flags &= ~FrameFlags.Unsynchronisation;
 			}
 
@@ -270,6 +270,10 @@ public static Frame CreateFrame (ByteVector data, File file, ref int offset, byt
 			if (header.FrameId == FrameType.PRIV)
 				return new PrivateFrame (data, position, header, version);
 
+			// User Url Link (frames 4.3.2)
+			if (header.FrameId == FrameType.WXXX)
+				return new UserUrlLinkFrame (data, position, header, version);
+
 			// Url Link (frames 4.3.1)
 			if (header.FrameId[0] == (byte)'W')
 				return new UrlLinkFrame (data, position, header, version);
@@ -278,6 +282,14 @@ public static Frame CreateFrame (ByteVector data, File file, ref int offset, byt
 			if (header.FrameId == FrameType.ETCO)
 				return new EventTimeCodesFrame (data, position, header, version);
 
+			// Chapter (ID3v2 Chapter Frame Addendum)
+			if (header.FrameId == FrameType.CHAP)
+				return new ChapterFrame (data, position, header, version);
+
+			// Table of Contents (ID3v2 Chapter Frame Addendum)
+			if (header.FrameId == FrameType.CTOC)
+				return new TableOfContentsFrame (data, position, header, version);
+
 			return new UnknownFrame (data, position, header, version);
 		}
 

src/TaglibSharp/Id3v2/FrameTypes.cs

@@ -40,6 +40,8 @@ static class FrameType
 	{
 		public static readonly ReadOnlyByteVector APIC = "APIC";
 		public static readonly ReadOnlyByteVector COMM = "COMM";
+		public static readonly ReadOnlyByteVector CHAP = "CHAP"; // Chapter Frame
+		public static readonly ReadOnlyByteVector CTOC = "CTOC"; // Table of Contents Frame
 		public static readonly ReadOnlyByteVector EQUA = "EQUA";
 		public static readonly ReadOnlyByteVector GEOB = "GEOB";
 		public static readonly ReadOnlyByteVector IPLS = "IPLS";

src/TaglibSharp/Id3v2/Frames/ChapterFrame.cs

@@ -0,0 +1,278 @@
+using System;
+using System.Collections.Generic;
+
+namespace TagLib.Id3v2
+{
+	/// <summary>
+	///    This class extends <see cref="Frame" /> to provide support for
+	///    Chapter Frames, i.e. "<c>CHAP</c>", (ID3v2 Chapter Frame Addendum 1.0,
+	///    https://id3.org/id3v2-chapters-1.0).
+	/// </summary>
+	/// <remarks>
+	///    The Chapter Frame is special in that it can hold an arbitrary amount
+	///    of sub-frames, which are made available here in the SubFrames list.
+	///
+	///    Each Chapter Frame must have an identifying string that is unique across
+	///    all <see cref="ChapterFrame"/>s and <see cref="TableOfContentsFrame"/>s
+	///    in the tag. This is the property <see cref="Id"/>. It is not intended
+	///    for humans consumption and players will not display it. A chapter can
+	///    be titled by adding a "<c>TIT2</c>" <see cref="TextInformationFrame"/>.
+	///
+	///    There are two ways the Chapter Frame can state a chapter’s beginning
+	///    and end: by milliseconds or by byte offset, accessible here as
+	///    StartMilliseconds/EndMilliseconds and StartByteOffset/EndByteOffset
+	///    respectively. The byte offsets are the zero-based byte positions of
+	///    the first audio frame in the chapter or the first audio frame folliwing
+	///    the chapter, counted from the beginning of the file. The byte offsets
+	///    are to be ignored according to the spec if they are FF FF FF FF. This
+	///    class does not synchronize the two ways in any way, so make sure to set
+	///    both appropriately. The byte offsets are however initialized to be
+	///    ignored, so with blank frames, you can focus on the milliseconds.
+	///
+	///    According to the spec, chapters may overlap and have gaps.
+	/// </remarks>
+	public class ChapterFrame : Frame
+	{
+		#region Constructors
+
+		/// <summary>
+		///    Constructs and initializes a new empty instance of <see
+		///    cref="ChapterFrame" />.
+		/// </summary>
+		public ChapterFrame ()
+			: base(FrameType.CHAP, 4)
+		{
+		}
+
+		/// <summary>
+		///    Constructs and initializes a new empty instance of <see
+		///    cref="ChapterFrame" /> with the given chapter ID.
+		/// </summary>
+		public ChapterFrame (string id)
+			: this()
+		{
+			Id = id;
+		}
+
+		/// <summary>
+		///    Constructs and initializes a new instance of <see cref="ChapterFrame" />
+		///    with the given chapter ID and adds a <see cref="TextInformationFrame"/>
+		///    "<c>TIT2</c>" with the given title.
+		/// </summary>
+		public ChapterFrame (string id, string title)
+			: this(id)
+		{
+			SubFrames.Add(new TextInformationFrame("TIT2") { Text = new[] { title } });
+		}
+
+		/// <summary>
+		///    Constructs and initializes a new instance of <see
+		///    cref="ChapterFrame" /> by reading its raw data in a
+		///    specified ID3v2 version.
+		/// </summary>
+		/// <param name="data">
+		///    A <see cref="ByteVector" /> object starting with the raw
+		///    representation of the new frame.
+		/// </param>
+		/// <param name="version">
+		///    A <see cref="byte" /> indicating the ID3v2 version the
+		///    raw frame is encoded in.
+		/// </param>
+		public ChapterFrame (ByteVector data, byte version)
+			: base (data, version)
+		{
+			SetData (data, 0, version, true);
+		}
+
+		/// <summary>
+		///    Constructs and initializes a new instance of <see
+		///    cref="ChapterFrame" /> by reading its raw data in a
+		///    specified ID3v2 version.
+		/// </summary>
+		/// <param name="data">
+		///    A <see cref="ByteVector" /> object containing the raw
+		///    representation of the new frame.
+		/// </param>
+		/// <param name="offset">
+		///    A <see cref="int" /> indicating at what offset in
+		///    <paramref name="data" /> the frame actually begins.
+		/// </param>
+		/// <param name="header">
+		///    A <see cref="FrameHeader" /> containing the header of the
+		///    frame found at <paramref name="offset" /> in the data.
+		/// </param>
+		/// <param name="version">
+		///    A <see cref="byte" /> indicating the ID3v2 version the
+		///    raw frame is encoded in.
+		/// </param>
+		protected internal ChapterFrame (ByteVector data, int offset, FrameHeader header, byte version)
+			: base (header)
+		{
+			SetData (data, offset, version, false);
+		}
+
+		#endregion
+
+
+		#region Public Properties
+
+		/// <summary>
+		///    Gets and sets the internal chapter id. This should be
+		///    <see cref="StringType.Latin1" /> .
+		/// </summary>
+		public string Id { get; set; }
+
+		/// <summary>
+		///    Gets and sets the start time of the chapter in milliseconds.
+		/// </summary>
+		public uint StartMilliseconds { get; set; }
+
+		/// <summary>
+		///    Gets and sets the end time of the chapter in milliseconds.
+		/// </summary>
+		public uint EndMilliseconds { get; set; }
+
+		/// <summary>
+		///    Gets and sets the chapter’s first audio frame’s byte position
+		///    from the beginning of the file.
+		///    The spec makes this ignorable if it is FF FF FF FF, which is
+		///    the initial value.
+		/// </summary>
+		public uint StartByteOffset { get; set; } = 0xFFFFFFFF;
+
+		/// <summary>
+		///    Gets and sets the byte position of the first audio frame following
+		///    the chapter from the beginning of the file.
+		///    The spec makes this ignorable if it is FF FF FF FF, which is
+		///    the initial value.
+		/// </summary>
+		public uint EndByteOffset { get; set; } = 0xFFFFFFFF;
+
+		/// <summary>
+		///    Gets and sets the descriptive sub-fields for this chapter. It
+		///    is recommended by the spec to have at least a "<c>TIT2</c>"
+		///    <see cref="TextInformationFrame"/> with the chapter title, but
+		///    it can contain anything. Particularly, players like to display
+		///    per-chapter "<c>APIC</c>" <see cref="AttachmentFrame"/>s and
+		///    <see cref="UrlLinkFrame"/>s.
+		/// </summary>
+		/// <value>
+		///    A List of arbitrary <see cref="Frame" />s.
+		/// </value>
+		public List<Frame> SubFrames { get; set; } = new List<Frame>();
+
+		#endregion
+
+
+		#region Protected Methods
+
+		/// <summary>
+		///    Populates the values in the current instance by parsing
+		///    its field data in a specified version.
+		/// </summary>
+		/// <param name="data">
+		///    A <see cref="ByteVector" /> object containing the
+		///    extracted field data.
+		/// </param>
+		/// <param name="version">
+		///    A <see cref="byte" /> indicating the ID3v2 version the
+		///    field data is encoded in.
+		/// </param>
+		protected override void ParseFields (ByteVector data, byte version)
+		{
+			// https://id3.org/id3v2-chapters-1.0
+
+			int idLength = data.IndexOf((byte)0) + 1;
+
+			Id                = data.ToString(StringType.Latin1, 0, idLength - 1); //Always Latin1, at least there is no mention of encoding in the spec
+			StartMilliseconds = data.Mid(idLength,      4).ToUInt();
+			EndMilliseconds   = data.Mid(idLength +  4, 4).ToUInt();
+			StartByteOffset   = data.Mid(idLength +  8, 4).ToUInt(); //I don’t really know why one would use the offsets.
+			EndByteOffset     = data.Mid(idLength + 12, 4).ToUInt(); //They are to be ignored if all 4 Bytes are FF, i.e. 4,294,967,295.
+
+			SubFrames = new List<Frame>();
+			int frame_data_position = idLength + 16;
+			int frame_data_endposition = data.Count;
+			while (frame_data_position < frame_data_endposition)
+			{
+				Frame frame;
+				try
+				{
+					frame = FrameFactory.CreateFrame(data, null, ref frame_data_position, version, true /* ? */);
+				}
+				catch (NotImplementedException)
+				{
+					continue;
+				}
+				catch (CorruptFileException)
+				{
+					throw;
+				}
+
+				if (frame == null)
+					break;
+
+				// Only add frames that contain data.
+				if (frame.Size == 0)
+					continue;
+
+				SubFrames.Add(frame);
+			}
+		}
+
+		/// <summary>
+		///    Renders the values in the current instance into field
+		///    data for a specified version.
+		/// </summary>
+		/// <param name="version">
+		///    A <see cref="byte" /> indicating the ID3v2 version the
+		///    field data is to be encoded in.
+		/// </param>
+		/// <returns>
+		///    A <see cref="ByteVector" /> object containing the
+		///    rendered field data.
+		/// </returns>
+		protected override ByteVector RenderFields (byte version)
+		{
+			var data = ByteVector.FromString(Id, StringType.Latin1);
+			data.Add((byte)0); //it would be neat if Add were chainable…
+			data.Add(ByteVector.FromUInt(StartMilliseconds));
+			data.Add(ByteVector.FromUInt(EndMilliseconds));
+			data.Add(ByteVector.FromUInt(StartByteOffset));
+			data.Add(ByteVector.FromUInt(EndByteOffset));
+
+			foreach (var f in SubFrames)
+				data.Add(f.Render(version));
+
+			return data;
+		}
+
+		#endregion
+
+
+		#region ICloneable
+
+		/// <summary>
+		///    Creates a deep copy of the current instance.
+		/// </summary>
+		/// <returns>
+		///    A new <see cref="Frame" /> object identical to the
+		///    current instance.
+		/// </returns>
+		public override Frame Clone()
+		{
+			var frame = new ChapterFrame(Id);
+			frame.StartMilliseconds = StartMilliseconds;
+			frame.EndMilliseconds = EndMilliseconds;
+			frame.StartByteOffset = StartByteOffset;
+			frame.EndByteOffset = EndByteOffset;
+
+			foreach(var f in SubFrames)
+				frame.SubFrames.Add(f.Clone());
+
+			return frame;
+		}
+
+		#endregion
+	}
+}