Skip to content

Added support for QuickTime Metadata ItemList Tags besides the Keyed Tags #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stefanlenselink wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Added support for QuickTime Metadata ItemList Tags besides the Keyed Tags #420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a9dbdf1
Added support for QuickTime Metadata ItemList Tags besides the Keyed …
stefanlenselink Apr 5, 2024
e5664b0
Only when MetaData is read from Keys it should be valid othwise we do…
stefanlenselink Apr 5, 2024
ce84a34
Merge remote-tracking branch 'origin/main' into HEAD
drewnoakes May 26, 2025
7ccac78
Remove redundant suppressions
drewnoakes May 26, 2025
78138fa
Merge branch 'drewnoakes:main' into quicktime-itemlist-metadata
stefanlenselink May 26, 2025
8de03bd
Update comments for clarity on metadata key handling
stefanlenselink May 26, 2025
da13c16
Remove not required split operation
stefanlenselink May 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions MetadataExtractor/Formats/QuickTime/QuickTimeMetadataHeaderDirectory.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,29 @@ public sealed class QuickTimeMetadataHeaderDirectory : Directory
{ "com.android.version", TagAndroidVersion },
{ "com.android.manufacturer", TagAndroidManufacturer },
{ "com.android.model", TagAndroidModel },
{ "alb", TagAlbum },
{ "albm", TagAlbum },
{ "ART", TagArtist },
{ "aut", TagAuthor },
{ "auth", TagAuthor },
{ "cmt", TagComment },
{ "cpy", TagCopyright },
{ "cprt", TagCopyright },
{ "day", TagCreationDate },
{ "des", TagDescription },
{ "desc", TagDescription },
{ "dscp", TagDescription },
{ "dir", TagDirector },
{ "nam", TagTitle },
{ "titl", TagTitle },
{ "gen", TagGenre },
{ "gnre", TagGenre },
{ "keyw", TagKeywords },
{ "xyz", TagGpsLocation },
{ "prd", TagProducer },
{ "pub", TagPublisher },
{ "yrrc", TagYear },
{ "rtng", TagRating },
};

public QuickTimeMetadataHeaderDirectory() : base(_tagNameMap)
Expand Down
211 changes: 138 additions & 73 deletions MetadataExtractor/Formats/QuickTime/QuickTimeMetadataReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,10 @@

using MetadataExtractor.Formats.Exif;
using MetadataExtractor.Formats.Exif.Makernotes;
using MetadataExtractor.Formats.Iso14496;
using MetadataExtractor.Formats.Tiff;
using MetadataExtractor.Formats.Xmp;

#pragma warning disable CS8602 // Dereference of a possibly null reference
#pragma warning disable CS8604 // Dereference of a possibly null reference

namespace MetadataExtractor.Formats.QuickTime
{
public static class QuickTimeMetadataReader
Expand All @@ -19,6 +17,7 @@ public static IReadOnlyList<Directory> ReadMetadata(Stream stream)
{
var directories = new List<Directory>();
var metaDataKeys = new List<string>();
var metaDataHandlerType = string.Empty;
QuickTimeMetadataHeaderDirectory? metaHeaderDirectory = null;

QuickTimeReader.ProcessAtoms(stream, Handler);
Expand Down Expand Up @@ -125,6 +124,7 @@ void UserDataHandler(AtomCallbackArgs a)
switch (a.Type)
{
case 0xa978797a: // "?xyz" (with a copyright symbol)
{
var stringSize = a.Reader.GetUInt16();
a.Reader.Skip(2); // uint16 language code
var stringBytes = a.Reader.GetBytes(stringSize);
Expand All @@ -134,11 +134,20 @@ void UserDataHandler(AtomCallbackArgs a)
QuickTimeMetadataHeaderDirectory.TagGpsLocation,
new StringValue(stringBytes, Encoding.UTF8));
break;
case 0x584D505F: // "XMP_" (XMP metadata)
}
case 0x6d657461: // "meta":
{
a.Reader.Skip(4);
QuickTimeReader.ProcessAtoms(stream, MetaDataHandler, a.BytesLeft);
break;
}
case 0x584d505f: // "XMP_" (XMP metadata)
{
var xmpBytes = a.Reader.GetNullTerminatedBytes((int)a.BytesLeft);
var xmpDirectory = new XmpReader().Extract(xmpBytes);
directories.Add(xmpDirectory);
break;
}
}
}

Expand All @@ -147,8 +156,24 @@ void MetaDataHandler(AtomCallbackArgs a)
// see https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/Metadata/Metadata.html
switch (a.TypeString)
{
case "hdlr":
{
// QuickTime Handler Tags
a.Reader.Skip(8);

var handlerType = a.Reader.GetUInt32();
metaDataHandlerType = TypeStringConverter.ToTypeString(handlerType);

// metaDataHandlerType:
// mdir => Metadata Item List Tags
// mdta => Metadata Keys Tags

break;
}
case "keys":
{
// This directory contains a list of key names which are used to decode tags written by the "mdta" handler.

a.Reader.Skip(4); // 1 byte version, 3 bytes flags
var entryCount = a.Reader.GetUInt32();
for (int i = 1; i <= entryCount; i++)
Expand All @@ -163,84 +188,124 @@ void MetaDataHandler(AtomCallbackArgs a)
}
case "ilst":
{
// Iterate over the list of Metadata Item Atoms.
for (int i = 0; i < metaDataKeys.Count; i++)
// ilst is used by both mdir (ItemList Tags) and mdta (Keys Tags) handlers

if (metaDataHandlerType == "mdir")
{
long atomSize = a.Reader.GetUInt32();
if (atomSize < 24)
{
GetMetaHeaderDirectory().AddError("Invalid ilst atom type");
a.Reader.Skip(atomSize - 4);
continue;
}
var atomType = a.Reader.GetUInt32();
// ItemList Tags
QuickTimeReader.ProcessAtoms(stream, MetaDataItemListTagsHandler, a.BytesLeft);
}
else if (metaDataHandlerType == "mdta")
{
// Iterate over the list of Metadata Item Atoms.
QuickTimeReader.ProcessAtoms(stream, MetaDataKeysTagsHandler, a.BytesLeft);
}

// Indexes into the metadata item keys atom are 1-based (1…entry_count).
// atom type for each metadata item atom is the index of the key
if (atomType < 1 || atomType > metaDataKeys.Count)
{
GetMetaHeaderDirectory().AddError("Invalid ilst atom type");
a.Reader.Skip(atomSize - 8);
continue;
}
var key = metaDataKeys[(int)atomType - 1];
break;
}
}
}

// Value Atom
a.Reader.Skip(8); // uint32 type indicator, uint32 locale indicator
void MetaDataTagHandler(AtomCallbackArgs a, string key, bool keyShouldBeValid = false)
{
// Value Atom
a.Reader.Skip(8); // uint32 type indicator, uint32 locale indicator

// Data Atom
var dataTypeIndicator = a.Reader.GetUInt32();
if (!_supportedAtomValueTypes.Contains((int)dataTypeIndicator))
{
GetMetaHeaderDirectory().AddError($"Unsupported type indicator \"{dataTypeIndicator}\" for key \"{key}\"");
a.Reader.Skip(atomSize - 20);
continue;
}
// Data Atom
var dataTypeIndicator = a.Reader.GetUInt32();
if (!_supportedAtomValueTypes.Contains((int)dataTypeIndicator))
{
if (keyShouldBeValid)
{
GetMetaHeaderDirectory().AddError($"Unsupported type indicator \"{dataTypeIndicator}\" for key \"{key}\"");
}
return;
}

// locale not supported yet.
a.Reader.Skip(4);
// locale not supported yet.
a.Reader.Skip(4);

var data = a.Reader.GetBytes((int)atomSize - 24);
if (QuickTimeMetadataHeaderDirectory.TryGetTag(key, out int tag))
{
object value = dataTypeIndicator switch
{
// UTF-8
1 => new StringValue(data, Encoding.UTF8),

// BE Float32 (used for User Rating)
23 => BitConverter.ToSingle(BitConverter.IsLittleEndian ? Reversed(data) : data, 0),

// 13 JPEG
// 14 PNG
// 27 BMP
_ => data
};

value = tag switch
{
QuickTimeMetadataHeaderDirectory.TagCreationDate => DateTime.Parse(((StringValue)value).ToString()),
QuickTimeMetadataHeaderDirectory.TagLocationDate => DateTime.Parse(((StringValue)value).ToString()),
_ => value,
};

GetMetaHeaderDirectory().Set(tag, value);

static byte[] Reversed(byte[] data)
{
Array.Reverse(data);
return data;
}
}
else
{
GetMetaHeaderDirectory().AddError($"Unsupported ilst key \"{key}\"");
}
}
var data = a.Reader.GetBytes((int)a.Size - 24);
if (QuickTimeMetadataHeaderDirectory.TryGetTag(key, out int tag))
{
object value = dataTypeIndicator switch
{
// UTF-8
1 => new StringValue(data, Encoding.UTF8),

break;
// BE Float32 (used for User Rating)
23 => BitConverter.ToSingle(BitConverter.IsLittleEndian ? Reversed(data) : data, startIndex: 0),

// 13 JPEG
// 14 PNG
// 27 BMP
_ => data
};

value = tag switch
{
QuickTimeMetadataHeaderDirectory.TagCreationDate => DateTime.Parse(((StringValue)value).ToString()),
QuickTimeMetadataHeaderDirectory.TagLocationDate => DateTime.Parse(((StringValue)value).ToString()),
_ => value,
};

GetMetaHeaderDirectory().Set(tag, value);
}
else
{
if (keyShouldBeValid)
{
GetMetaHeaderDirectory().AddError($"Unsupported ilst key \"{key}\"");
}
}

static byte[] Reversed(byte[] data)
{
Array.Reverse(data);
return data;
}
}

void MetaDataKeysTagsHandler(AtomCallbackArgs a)
{
// Indexes into the metadata item keys atom are 1-based (1…entry_count).
// atom type for each metadata item atom is the index of the key
if (a.Type < 1 || a.Type > metaDataKeys.Count)
{
GetMetaHeaderDirectory().AddError("Invalid ilst atom type");
return;
}

var key = metaDataKeys[(int)a.Type - 1];

MetaDataTagHandler(a, key, true);
}

void MetaDataItemListTagsHandler(AtomCallbackArgs a)
{
var key = a.TypeString;
if (key.Length < 1)
{
return;
}
if (key[0] == 0xa9 || key[0] == 0x40)
{
//Tag ID's beginning with the copyright symbol (hex 0xa9) are multi-language text
//some stupid Ricoh programmer used the '@' (hex 0x40) symbol instead of the copyright symbol in these tag ID's for the Ricoh Theta Z1 and maybe other models

//The uint32 locale indicator following the key (which is skipped by the MetaDataTagHandler-call as its not supported (yet)) contains the locale information for the tag.
//It contains a dash followed by a 3-character ISO 639-2 language code to the tag name.

//For now we don't support those, we will strip the copyright/@-sign
key = key.Substring(1);

if (string.IsNullOrWhiteSpace(key))
{
return; // no valid key
}
}

MetaDataTagHandler(a, key);
}

void MoovHandler(AtomCallbackArgs a)
Expand Down