Merge branch 'master' into feature/support-ETCO-frames

Author: decriptor

README.md

@@ -6,49 +6,116 @@
 [![Windows Build status](https://ci.appveyor.com/api/projects/status/v7vwgphs239i14ya?svg=true)](https://ci.appveyor.com/project/decriptor/taglib-sharp)
 
 
-(aka taglib-sharp) is a library for reading and writing
-metadata in media files, including video, audio, and photo formats.
+(aka *Taglib-sharp*) is a .NET platform-independent library (tested on Windows/Linux) for reading and writing
+metadata in media files, including video, audio, and photo formats. 
+This is a convenient one-stop-shop to present or tag all your media collection, regardless of which format/container 
+these might use. You can read/write the standard or more common tags/properties of a media, or you can also create and
+retrieve your own custom tags.
+
+It supports the following formats (by file-extensions):
+ * **Video:** mkv, ogv, avi, wmv, asf, mp4 (m4p, m4v), mpeg (mpg, mpe, mpv, mpg, m2v)
+ * **Audio:** aa, aax, aac, aiff, ape, dsf, flac, m4a, m4b, m4p, mp3, mpc, mpp, ogg, oga, wav, wma, wv, webm
+ * **Images:** bmp, gif, jpeg, pbm, pgm, ppm, pnm, pcx, png, tiff, dng, svg
 
 It is API stable, with only API additions (not changes or removals)
 occuring in the 2.0 series.
 
- * Bugs:     <https://bugzilla.gnome.org/page.cgi?id=browse.html&product=taglib-sharp>
- * Tarballs: <http://banshee.fm/download/>
- * IRC:      Several TagLib# developers are often in #banshee on irc.gnome.org
- * Git:      <https://github.com/mono/taglib-sharp> or <git://github.com/mono/taglib-sharp.git>
 
-TagLib# is free/open source software, released under the LGPL.
-We welcome contributions!  Please try to match our coding style,
-and include unit tests with any patches.  Patches can be submitted
-by filing a bug and attaching the diff to it.
+## Examples
+
+### Read/write metadata from a video
+```C#
+var tfile = TagLib.File.Create(@"C:\My video.avi");
+string title = tfile.Tag.Title;
+TimeSpan duration = tfile.Properties.Duration;
+Console.WriteLine("Title: {0}, duration: {1}", title, duration);
+
+// change title in the file
+tfile.Tag.Title = "my new title";
+tfile.Save();
+```
+
+### Read/write metadata from a Audio file
+```C#
+var tfile = TagLib.File.Create(@"C:\My audio.mp3");
+string title = tfile.Tag.Title;
+TimeSpan duration = tfile.Properties.Duration;
+Console.WriteLine("Title: {0}, duration: {1}", title, duration);
+
+// change title in the file
+tfile.Tag.Title = "my new title";
+tfile.Save();
+```
+
+### Read/write metadata from an Image
+```C#
+var tfile = TagLib.File.Create(@"C:\My picture.jpg");
+string title = tfile.Tag.Title;
+var tag =  tfile.Tag as TagLib.Image.CombinedImageTag;
+DateTime? snapshot = tag.DateTime;
+Console.WriteLine("Title: {0}, snapshot taken on {1}", title, snapshot);
+
+// change title in the file
+tfile.Tag.Title = "my new title";
+tfile.Save();
+```
+
+### Read/write custom tags from a specific format
+```C#
+var tfile = TagLib.File.Create(@"C:\My song.flac");
+var custom = (TagLib.Ogg.XiphComment) tfile.GetTag(TagLib.TagTypes.Xiph);
+
+// Read
+string [] myfields = custom.GetField("MY_TAG");
+Console.WriteLine("First MY_TAG entry: {0}", myfields[0]);
+
+// Write
+custom.SetField("MY_TAG", new string[] { "value1", "value2" });
+custom.RemoveField("OTHER_FIELD");
+rgFile.Save();
+```
+
+
+## Website
+TagLib# is available on GitHub: <https://github.com/mono/taglib-sharp>
+* **Bugs:**     Create an [issue](https://github.com/mono/taglib-sharp/issues)
+* **Chat:**     Join us at [Gitter](https://gitter.im/mono/taglib-sharp)
+* **Git:**      Get the source at <git://github.com/mono/taglib-sharp.git>
+
 
 ## Building and Running
 
-### To Build From Git:
+### Command Line  (Linux)
+
+#### To Build From Git:
 
 ```sh
 git clone https://github.com/mono/taglib-sharp.git
 cd taglib-sharp
 ./autogen.sh && make
 ```
 
-### To Build From Tarball:
+#### To Build From Tarball:
 
 ```
 ./configure && make
 ```
 
-### To Test:
+#### To Test:
 
 ```
 make test
 ```
 
-You can also build from MonoDevelop or Visual Studio using taglib-sharp.sln
+### Mono Develop  (Linux)
 
-### To Test/Run from Visual Studio (Windows):
+You can build from MonoDevelop using taglib-sharp.sln
 
-Running regression by using Nunit 3 Test Adapter:
+### Visual Studio (Windows):
+
+You can open it in Visual Studio by using taglib-sharp.sln
+
+#### Running regression by using Nunit 3 Test Adapter:
 
 1. Ensure NuGet packages have been restored
     1. See: <https://docs.microsoft.com/en-us/nuget/consume-packages/package-restore>
@@ -61,9 +128,27 @@ Running regression by using Nunit 3 Test Adapter:
    1. Double click on a test. Set some breakpoints in the test in the editor panel.
    2. right-click on the same test, select "Debug Selected tests".
 
-To test some scenarios and take advantage of the debugger:
+#### To test some scenarios and take advantage of the debugger:
 
 1. Make the "debug" project the Startup project
     (Right-click on the project, select: "Set as StartUp Project")
 2. Just modify the "Program.cs"
 3. Set some breakpoints and hit the "Start" button
+
+
+
+## They also use TagLib#
+Non exhaustive list of projects that use TagLib#:
+* [Lidarr](https://lidarr.audio/)
+* [MediaPortal 2](https://www.team-mediaportal.com/wiki/display/MediaPortal2/MediaPortal+2)
+* [F-Spot](https://en.wikipedia.org/wiki/F-Spot)
+
+And you, what do you use TagLib# for ? Reply [here](https://github.com/mono/taglib-sharp/issues/120)
+
+## Contributions
+
+TagLib# is free/open source software, released under the LGPL.
+We welcome contributions!  Please try to match our coding style,
+and include unit tests with any patches.  Patches can be submitted
+by issuing a Pull Request (Git).
+

src/TagLib/CombinedTag.cs

@@ -1838,8 +1838,180 @@ public override double ReplayGainAlbumPeak {
 					if (tag != null)
 						tag.ReplayGainAlbumPeak = value;
 			}
-		}
-
+		}
+
+		/// <summary>
+		///    Gets and sets the initial key of the media
+		///    represented by the current instance.
+		/// </summary>
+		/// <value>
+		///    A <see cref="string" /> object containing the initial
+		///    key of the media represented by the current
+		///    instance or <see langword="null" /> if no value present.
+		/// </value>
+		/// <remarks>
+		///    <para>When getting the value, the child tags are looped
+		///    through in order and the first non-<see langword="null" />
+		///    value is returned.</para>
+		///    <para>When setting the value, it is stored in each child
+		///    tag.</para>
+		/// </remarks>
+		/// <seealso cref="Tag.InitialKey" />
+		public override string InitialKey
+		{
+			get
+			{
+				foreach (Tag tag in tags)
+				{
+					if (tag == null)
+						continue;
+
+					string value = tag.InitialKey;
+
+					if (value != null)
+						return value;
+				}
+
+				return null;
+			}
+
+			set
+			{
+				foreach (Tag tag in tags)
+					if (tag != null)
+						tag.InitialKey = value;
+			}
+		}
+
+		/// <summary>
+		///    Gets and sets the remixer of the media
+		///    represented by the current instance.
+		/// </summary>
+		/// <value>
+		///    A <see cref="string" /> object containing the remixer
+		///    of the media represented by the current
+		///    instance or <see langword="null" /> if no value present.
+		/// </value>
+		/// <remarks>
+		///    <para>When getting the value, the child tags are looped
+		///    through in order and the first non-<see langword="null" />
+		///    value is returned.</para>
+		///    <para>When setting the value, it is stored in each child
+		///    tag.</para>
+		/// </remarks>
+		/// <seealso cref="Tag.RemixedBy" />
+		public override string RemixedBy
+		{
+			get
+			{
+				foreach (Tag tag in tags)
+				{
+					if (tag == null)
+						continue;
+
+					string value = tag.RemixedBy;
+
+					if (value != null)
+						return value;
+				}
+
+				return null;
+			}
+
+			set
+			{
+				foreach (Tag tag in tags)
+					if (tag != null)
+						tag.RemixedBy = value;
+			}
+		}
+
+		/// <summary>
+		///    Gets and sets the publisher of the media
+		///    represented by the current instance.
+		/// </summary>
+		/// <value>
+		///    A <see cref="string" /> object containing the 
+		///    publisher of the media represented by the current
+		///    instance or <see langword="null" /> if no value present.
+		/// </value>
+		/// <remarks>
+		///    <para>When getting the value, the child tags are looped
+		///    through in order and the first non-<see langword="null" />
+		///    value is returned.</para>
+		///    <para>When setting the value, it is stored in each child
+		///    tag.</para>
+		/// </remarks>
+		/// <seealso cref="Tag.Publisher" />
+		public override string Publisher
+		{
+			get
+			{
+				foreach (Tag tag in tags)
+				{
+					if (tag == null)
+						continue;
+
+					string value = tag.Publisher;
+
+					if (value != null)
+						return value;
+				}
+
+				return null;
+			}
+
+			set
+			{
+				foreach (Tag tag in tags)
+					if (tag != null)
+						tag.Publisher = value;
+			}
+		}
+
+		/// <summary>
+		///    Gets and sets the ISRC (International Standard Recording Code)
+		///    of the song represented by the current instance.
+		/// </summary>
+		/// <value>
+		///    A <see cref="string" /> object containing the ISRC
+		///    of the media represented by the current
+		///    instance or <see langword="null" /> if no value present.
+		/// </value>
+		/// <remarks>
+		///    <para>When getting the value, the child tags are looped
+		///    through in order and the first non-<see langword="null" />
+		///    value is returned.</para>
+		///    <para>When setting the value, it is stored in each child
+		///    tag.</para>
+		/// </remarks>
+		/// <seealso cref="Tag.ISRC" />
+		public override string ISRC
+		{
+			get
+			{
+				foreach (Tag tag in tags)
+				{
+					if (tag == null)
+						continue;
+
+					string value = tag.ISRC;
+
+					if (value != null)
+						return value;
+				}
+
+				return null;
+			}
+
+			set
+			{
+				foreach (Tag tag in tags)
+					if (tag != null)
+						tag.ISRC = value;
+			}
+		}
+
 		/// <summary>
 		///    Gets whether or not the current instance is empty.
 		/// </summary>

src/TagLib/Id3v2/FrameTypes.cs

@@ -63,6 +63,7 @@ internal static class FrameType {
 		public static readonly ReadOnlyByteVector TIT2 = "TIT2";
 		public static readonly ReadOnlyByteVector TIT3 = "TIT3";
 		public static readonly ReadOnlyByteVector TIME = "TIME";
+		public static readonly ReadOnlyByteVector TKEY = "TKEY";
 		public static readonly ReadOnlyByteVector TMCL = "TMCL";
 		public static readonly ReadOnlyByteVector TOLY = "TOLY";
 		public static readonly ReadOnlyByteVector TOPE = "TOPE";
@@ -71,6 +72,7 @@ internal static class FrameType {
 		public static readonly ReadOnlyByteVector TPE3 = "TPE3";
 		public static readonly ReadOnlyByteVector TPE4 = "TPE4";
 		public static readonly ReadOnlyByteVector TPOS = "TPOS";
+		public static readonly ReadOnlyByteVector TPUB = "TPUB";
 		public static readonly ReadOnlyByteVector TRCK = "TRCK";
 		public static readonly ReadOnlyByteVector TRDA = "TRDA";
 		public static readonly ReadOnlyByteVector TSIZ = "TSIZ";
@@ -79,6 +81,7 @@ internal static class FrameType {
 		public static readonly ReadOnlyByteVector TSOC = "TSOC"; // Composer Sort Frame
 		public static readonly ReadOnlyByteVector TSOP = "TSOP"; // Performer Sort Frame
 		public static readonly ReadOnlyByteVector TSOT = "TSOT"; // Track Title Sort Frame
+		public static readonly ReadOnlyByteVector TSRC = "TSRC";
 		public static readonly ReadOnlyByteVector TXXX = "TXXX";
 		public static readonly ReadOnlyByteVector TYER = "TYER";
 		public static readonly ReadOnlyByteVector UFID = "UFID";

src/TagLib/Id3v2/Frames/AttachmentFrame.cs

@@ -739,7 +739,7 @@ public void Load()
 			finally
 			{
 				// Free the resources
-				if (stream != null)
+				if (stream != null && file != null)
 				{
 					file.CloseStream(stream);
 				}