code/Audio/Metadata/ID3/Frame.cs

Go to the documentation of this file.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Sylloge.Audio.Metadata.ID3
{
    public class Frame
    {
        //ID3 tag headers follow a specific format:
        //Tag ID: xx xx xx xx (four characters) 
        //Size:   xx xx xx xx
        //Flags:  xx xx

        #region Keys, Classes and Constants

        public const byte EOL = (byte)0;

        public static class Keys
        {
            public const string AttachedPicture = "APIC";
            public const string Comment = "COMM";
            public const string Album = "TALB";
            public const string Composer = "TCOM";
            public const string Genre = "TCON";
            public const string CopyrightInfo = "TCOP";
            public const string EncodedBy = "TENC";
            public const string TitleOfSong = "TIT2";
            public const string OriginalArtist = "TOPE";
            public const string Artist = "TPE1";
            public const string AlbumArtist = "TPE2";
            public const string DiscNumber = "TPOS";
            public const string Publisher = "TPUB";
            public const string Track = "TRCK";
            public const string Year = "TYER";
            public const string UserDefinedString = "TXXX";
            public const string UserDefinedURL = "WXXX";


            public static string[] Supported { get { return Keys.m_sup.ToArray(); } }

            public static string[] Reserved { get { return Keys.m_res.ToArray(); } }

            public static string[] User { get { return Keys.m_usr.ToArray(); } }

            static Keys()
            {
                Keys.m_res.AddRange(Keys.m_sup);
                Keys.m_res.Sort();
            }

            public static bool IsValidId(string id)
            {
                if (string.IsNullOrEmpty(id)) { return false; }
                if (id.Length != 4) { return false; }
                for (int i = 0; i < 4; i++) {
                    if (!char.IsLetterOrDigit(id[i])) { return false; }
                }
                return true;
            }

            #region Private Data

            private static List<string> m_sup = new List<string>() {
                Keys.AttachedPicture, Keys.Comment, Keys.Album, Keys.Composer, Keys.Genre,
                Keys.CopyrightInfo, Keys.EncodedBy, Keys.TitleOfSong, Keys.OriginalArtist,
                Keys.Artist, Keys.AlbumArtist, Keys.DiscNumber, Keys.Publisher, Keys.Track,
                Keys.Year, Keys.UserDefinedString, Keys.UserDefinedURL
            };

            private static List<string> m_res = new List<string>() {
                "AENC", "COMR", "ENCR", "EQUA", "ETCO", "GEOB", "GRID", "IPLS", "LINK",
                "MCDI", "MLLT", "OWNE", "PRIV", "PCNT", "POPM", "POSS", "RBUF", "RVAD",
                "RVRB", "SYLT", "SYTC", "TBPM", "TDAT", "TDLY", "TEXT", "TFLT", "TIME",
                "TIT1", "TIT3", "TKEY", "TLAN", "TLEN", "TMED", "TOAL", "TOFN", "TOLY",
                "TORY", "TOWN", "TPE3", "TPE4", "TRDA", "TRSN", "TRSO", "TSIZ", "TSRC",
                "TSSE", "UFID", "USER", "USLT", "WCOM", "WCOP", "WOAF", "WOAR", "WOAS",
                "WORS", "WPAY", "WPUB"
            };

            private static List<string> m_usr = new List<string>() { "XXXX", "YYYY", "ZZZZ" };

            #endregion
        }

        public class StatusFlags
        {
            public enum PreservationFlag : byte
            {
                Preserved = 0x00,
                Discarded = 0x01
            }
            
            public PreservationFlag TagAlter { get; set; }
            public PreservationFlag FileAlter { get; set; }
            public bool ReadOnly { get; set; }

            public bool HasData
            {
                get
                {
                    return this.TagAlter == PreservationFlag.Discarded ||
                           this.FileAlter == PreservationFlag.Discarded ||
                           this.ReadOnly;
                }
            }

            public StatusFlags(byte status)
            {
                this.SetValues(status);
            }

            public void Clear()
            {
                this.TagAlter = PreservationFlag.Preserved;
                this.FileAlter = PreservationFlag.Preserved;
                this.ReadOnly = false;
            }

            public void Set(byte flag)
            {
                this.SetValues(flag);
            }

            public byte ToByte()
            {
                //   654
                // %0abc0000 
                byte r = (byte)0;
                if (this.TagAlter == PreservationFlag.Discarded) { r = Sylloge.Memory.SetBit(r, 6); }
                if (this.FileAlter == PreservationFlag.Discarded) { r = Sylloge.Memory.SetBit(r, 5); }
                if (this.ReadOnly) { r = Sylloge.Memory.SetBit(r, 4); }
                return r;
            }

            private void SetValues(byte flag)
            {
                this.TagAlter = (Sylloge.Memory.IsBitSet(flag, 6) ? PreservationFlag.Discarded : PreservationFlag.Preserved);
                this.FileAlter= (Sylloge.Memory.IsBitSet(flag, 5) ? PreservationFlag.Discarded : PreservationFlag.Preserved);
                this.ReadOnly = Sylloge.Memory.IsBitSet(flag, 4);
            }
        }

        public class FormatFlags
        {
            private byte m_gi;
            private byte m_enc;
            private int m_dli;

            public byte GroupingIdentity
            {
                get { return this.m_gi; }
                set {
                    this.m_gi = value;
                    this.HasGroup = true;
                }
            }
            public bool IsCompressed { get; set; }
            public byte Encryption
            {
                get { return this.m_enc; }
                set {
                    this.m_enc = value;
                    this.IsEncrypted = true;
                }
            }
            public bool IsUnsynchronised { get; set; }
            public int DataLengthInicator
            {
                get { return this.m_dli; }
                set {
                    this.m_dli = value;
                    this.HasDataLength = true;
                }
            }

            public bool HasGroup { get; set; }
            public bool IsEncrypted { get; set; }
            public bool HasDataLength { get; set; }
            

            public bool HasData
            {
                get
                {
                    return this.HasGroup ||
                           this.IsCompressed ||
                           this.IsEncrypted ||
                           this.IsUnsynchronised ||
                           this.HasDataLength;
                }
            }

            public FormatFlags(byte flags)
            {
                this.SetValues(flags);
            }

            public void Clear()
            {
                this.HasGroup = false;
                this.IsCompressed = false;
                this.IsEncrypted = false;
                this.IsUnsynchronised = false;
                this.HasDataLength = false;
                this.DataLengthInicator = 0;
                this.GroupingIdentity = 0;
                this.Encryption = 0;
            }

            public void Set(byte flag)
            {
                this.SetValues(flag);
            }

            public byte ToByte()
            {
                //                 6  3210
                //     %0abc0000 %0h00kmnp
                //     
                //     where:
                //     h - Grouping identity
                //     k - Compression
                //     m - Encryption
                //     n - Unsynchronisation
                //     p - Data length indicator
                byte r = (byte)0;
                if (this.HasGroup) { r = Sylloge.Memory.SetBit(r, 6); }
                if (this.IsCompressed) { r = Sylloge.Memory.SetBit(r, 3); }
                if (this.IsEncrypted) { r = Sylloge.Memory.SetBit(r, 2); }
                if (this.IsUnsynchronised) { r = Sylloge.Memory.SetBit(r, 1); }
                if (this.HasDataLength) { r = Sylloge.Memory.SetBit(r, 0); }
                return r;
            }

            private void SetValues(byte flag)
            {
                this.HasGroup = Sylloge.Memory.IsBitSet(flag, 6);
                this.IsCompressed = Sylloge.Memory.IsBitSet(flag, 3);
                this.IsEncrypted = Sylloge.Memory.IsBitSet(flag, 2);
                this.IsUnsynchronised = Sylloge.Memory.IsBitSet(flag, 1);
                this.HasDataLength = Sylloge.Memory.IsBitSet(flag, 0);
            }
        }

        #endregion

        #region Tag Members

        public string ID { get; protected set; }
        public int Length { get { return ((this.Data == null) ? 0 : this.Data.Length); } }
        public StatusFlags Status { get; protected set; }
        public FormatFlags Format { get; protected set; }
        public byte[] Data { get; protected set; }
        
        #endregion

        #region Public Functions

        public Frame()
        {
            this.Initialize("ZXXX", (new byte[2]), null);
        }

        public Frame(Frame other)
        {
            this.Initialize(other.ID, (new byte[] { other.Status.ToByte(), other.Format.ToByte() }), other.Data);
        }

        public Frame(byte[] data, bool syncSafe)
        {
            this.Initialize(ref data, syncSafe);
        }

        public byte[] FullFrame
        {
            get
            {
                //byte[] data = new byte[this.FullFrameLength];
                List<byte> data = new List<byte>(this.FullFrameLength);
                if (this.ID.Length < 4) { this.ID = this.ID.PadRight(4, 'X'); }
                if (this.ID.Length > 4) { this.ID = this.ID.Substring(0, 4); }
                //System.Buffer.BlockCopy(ID3.Helper.ISO.GetBytes(this.ID.ToUpper()), 0, data, 0, 4);
                data.AddRange(ID3.Helper.ISO.GetBytes(this.ID.ToUpper()));
                //System.Buffer.BlockCopy(this.Size, 0, data, 4, 4);
                data.AddRange(this.Size);
                //data[8] = this.Status.ToByte();
                data.Add(this.Status.ToByte());
                //data[9] = this.Format.ToByte();
                data.Add(this.Format.ToByte());
                if (this.Format.HasGroup) {
                    //data[10] = this.Format.GroupingIdentity;
                    data.Add(this.Format.GroupingIdentity);
                }
                if (this.Format.IsEncrypted) {
                    //data[11] = this.Format.Encryption;
                    data.Add(this.Format.Encryption);
                }
                if (this.Format.HasDataLength) {
                    int dli = this.Format.DataLengthInicator;
                    if (this.Format.IsUnsynchronised) { dli = ID3.Helper.ToSynchsafeInt(this.Format.DataLengthInicator); }
                    byte[] blen = new byte[4];
                    System.Buffer.BlockCopy(BitConverter.GetBytes(dli), 0, blen, 0, 4);
                    data.AddRange(Sylloge.Memory.SwapByteOrder(blen));
                }
                //System.Buffer.BlockCopy(this.Data, 0, data, 10, this.Data.Length);
                // no need to 'sync/compress' here
                data.AddRange(this.Data);
                return data.ToArray();
            }
        }

        public int FullFrameLength
        {
            get
            {
                int len = this.Length + 10;
                if (this.Format.HasGroup) { ++len; }
                if (this.Format.IsEncrypted) { ++len; }
                if (this.Format.HasDataLength) { len += 4; }
                return len;
            }
        }

        public virtual byte[] GenerateTag()
        {
            return this.FullFrame;
        }

        public byte[] Size
        {
            get
            {
                int len = ID3.Helper.ToSynchsafeInt((int)this.Length);
                byte[] blen = new byte[4];
                System.Buffer.BlockCopy(BitConverter.GetBytes(len), 0, blen, 0, 4);
                return Memory.SwapByteOrder(blen);
            }
        }

        public override string ToString()
        {
            return this.ID;
        }

        #endregion

        #region Protected Functions
        // these functions are specific to derived classes

        protected Frame(string id)
        {
            this.Initialize(id, (new byte[2]), null);
        }

        protected Frame(string id, byte[] data)
        {
            this.Initialize(id, (new byte[2]), data);
        }

        protected Frame(string id, byte[] flags, byte[] data)
        {
            this.Initialize(id, flags, data);
        }

        protected Frame(string id, byte status, byte format, byte[] data)
        {
            this.Initialize(id, (new byte[] { status, format }), data);
        }

        #endregion

        #region Private Functions

        private void Initialize(ref byte[] data, bool syncSafe)
        {
            this.ID = ID3.Helper.ISO.GetString(data, 0, 4).ToUpper();
            this.Status = new StatusFlags(data[8]);
            this.Format = new FormatFlags(data[9]);
            // length is big-endian, need to swap bytes then can get proper length
            byte[] ts = new byte[4];
            System.Buffer.BlockCopy(data, 4, ts, 0, 4);
            int len = BitConverter.ToInt32(Sylloge.Memory.SwapByteOrder(ts, 0, 4), 0);
            if (syncSafe) { len = ID3.Helper.FromSynchsafeInt(len); }
            this.Data = new byte[len];
            System.Buffer.BlockCopy(data, 10, this.Data, 0, len);
        }

        private void Initialize(string id, byte[] flags, byte[] data)
        {
            this.ID = id;
            if (flags != null && flags.Length > 1) {
                this.Status = new StatusFlags(flags[0]);
                this.Format = new FormatFlags(flags[1]);
            }
            if (data != null) { this.Data = data; }
        }

        #endregion

        #region Static Functions

        public static byte[] GetFullTagData(string id, byte[] data)
        {
            return (new Frame(id, data)).FullFrame;
        }
        
        public static ID3.Frame Parse(byte[] data, bool unsync)
        {
            if (data == null) { return null; }
            if (data.Length < 10) { return null; }
            // ID3 frame headers follow a specific format:
            // Frame ID: xx xx xx xx (four characters) 
            string tag_id = ID3.Helper.ISO.GetString(data, 0, 4).ToUpper();
            if (!Frame.Keys.IsValidId(tag_id)) { return null; }
            List<byte> bdata = new List<byte>(data);
            bdata.RemoveRange(0, 4); // remove tag_id
            // Frame Size:   xx xx xx xx (this size is the total length - the header)
            int sz = BitConverter.ToInt32(Sylloge.Memory.SwapByteOrder(bdata.ToArray(), 0, 4), 0);
            if (unsync) { sz = ID3.Helper.FromSynchsafeInt(sz); }
            bdata.RemoveRange(0, 4); // remove size bytes
            // Flags:  xx xx
            Frame ret = new Frame(tag_id);
            ret.Status = new StatusFlags(bdata[0]);
            ret.Format = new FormatFlags(bdata[1]);
            bdata.RemoveRange(0, 2);
            if (ret.Format.HasData) {
                if (ret.Format.HasGroup) {
                    ret.Format.GroupingIdentity = bdata[0];
                    bdata.RemoveAt(0);
                }
                if (ret.Format.IsEncrypted) {
                    ret.Format.Encryption = bdata[0];
                    bdata.RemoveAt(0);
                }
                if (ret.Format.HasDataLength) {
                    int dli = BitConverter.ToInt32(Sylloge.Memory.SwapByteOrder(bdata.ToArray(), 0, 4), 0);
                    if (ret.Format.IsUnsynchronised) { dli = ID3.Helper.FromSynchsafeInt(dli); }
                    bdata.RemoveRange(0, 4);
                    ret.Format.DataLengthInicator = dli;
                }
            }
            if (sz > bdata.Count) { sz = bdata.Count; }
            ret.Data = new byte[sz];
            // copy all of the data, the individual tag is responsible
            // for 'unsyncing' the data (if applicable)
            System.Buffer.BlockCopy(bdata.ToArray(), 0, ret.Data, 0, sz);
            //bdata.RemoveRange(0, sz); // strictly speaking, not nessecary
            return ret;
        }

        public static byte[] Encrypt(byte[] data, byte method)
        {
            return data;
        }

        public static byte[] Decrypt(byte[] data, byte method)
        {
            return data;
        }

        public static byte[] Compress(byte[] data)
        {
            return data;
        }

        public static byte[] Decompress(byte[] data)
        {
            return data;
        }

        public static byte[] SyncData(byte[] data)
        {
            List<byte> ret = new List<byte>(data);
            for (int i = 0; i < ret.Count; i++) {
                if ((i + 1) > ret.Count) { break; }
                if (ret[i] == 0xFF && ret[i + 1] != 0x00) {
                    ret.Insert((i + 1), 0x00);
                }
            }
            /*
            Whenever a false synchronisation is found within the tag, one zeroed
            byte is inserted after the first false synchronisation byte. The
            format of synchronisations that should be altered by ID3 encoders is
            as follows:
                %11111111 111xxxxx
            and should be replaced with:
                %11111111 00000000 111xxxxx
            This has the side effect that all $FF 00 combinations have to be
            altered, so they will not be affected by the decoding process.
            Therefore all the $FF 00 combinations have to be replaced with the
            $FF 00 00 combination during the unsynchronisation.
            To indicate usage of the unsynchronisation, the unsynchronisation
            flag in the frame header should be set.
             */
            return ret.ToArray();
        }

        public static byte[] UnsyncData(byte[] data, int dli)
        {
            int max = (dli > 0 ? dli : data.Length);
            List<byte> ret = new List<byte>(data);
            for (int i = 0; i < max; ++i) {
                if ((i + 1) > ret.Count) { break; }
                if (ret[i] == 0xFF && ret[i + 1] == 0x00) {
                    ret.RemoveAt(i + 1);
                }
            }
            /*
            Whenever a false synchronisation is found within the tag, one zeroed
            byte is inserted after the first false synchronisation byte. The
            format of synchronisations that should be altered by ID3 encoders is
            as follows:
                %11111111 111xxxxx
            and should be replaced with:
                %11111111 00000000 111xxxxx
            This has the side effect that all $FF 00 combinations have to be
            altered, so they will not be affected by the decoding process.
            Therefore all the $FF 00 combinations have to be replaced with the
            $FF 00 00 combination during the unsynchronisation.
            To indicate usage of the unsynchronisation, the unsynchronisation
            flag in the frame header should be set.
             */
            return ret.ToArray();
        }

        #endregion
    }
}